Publish Control Files (PCF)

The publish control file (PCF) is an XML data file which contains specific instructions concerning the manner in which OU Campus processes XML data upon publishing. The TMPL and the TCF process to define the PCF and this can also include XSL. In addition, the PCF specifies how the data is editable and displayed within the system itself. The PCF has the .pcf extension and the listing of PCF files are visible to end-users from the Content > Pages view.

The examples on this page make use of a sample PCF. The source code for the example PCF file is provided in a zip file. The file can be downloaded and unzipped to make use of the examples: faculty-directory-2.zip

Stylesheet Declarations

The OU Campus templates typically include a stylesheet declaration in the processing instructions in the prolog. The PCF example (faculty-directory.pcf) includes the stylesheet declarations:

<?pcf-stylesheet path="faculty-directory.xsl" extension="html"?>
<?pcf-stylesheet path="faculty-directory-csv.xsl" extension="csv" alternate="yes"?>

This specifies the XSL file that the system uses in order to transform the XML data into a desired output. There must be at least one such declaration in every PCF, but there is no limit to the number of such declarations that can be defined. Each declaration represents a desired output file that OU Campus generates from the PCF. For example, if the published page should be published as an HTML file and a PDF, two pcf-stylesheet declarations will be included.

One of the example pcf-stylesheet declarations has three attributes, two of which are required. The three attributes are the path, extension and alternate.

The path attribute specifies the location of the XSL file to be used to generate the output, which will have the file extension defined in the extension attribute. Path is usually defined as a path from root and may also include a separate site identifier if the XSL is in a different OU Campus site. Any output file always shares the file name of the PCF file with only the file extensions differing accordingly. Finally, the alternate attribute specifies that the declaration defines additional output that should be generated when the PCF file is published. In the example, this allows for the creation of an HTML document, as well as additional output of a CSV (comma separated values) file.

If alternate is left undefined, the CMS assumes that alternate="no". The primary declaration (that with alternate set to "no" or undefined) will be the declaration used if previewed within OU Campus. As a side note, if OU Campus does not find a pcf-stylesheet declaration, the PCF file will be opened using the Source Editor. This is also true for generic XML files with xml extensions.

PCF Stylesheet Declaration Reference 

Attribute Name Syntax Message Description
path path="/_resources/xsl/default.xsl" Required. Defines the path to the XSL file that will be used to transform the page.
extension extension="html" Required. Defines the extension that is used to replace .pcf on publish.
site site="templates" Defines an alternative site where the XSL file that was defined as part of the path resides.
title title="Web" Defines a friendly name, which will appear in place of the extension on the tabs shown in the preview.
alternate alternate="yes" Used when there is more than one PCF-Stylesheet declaration to identify the file as a secondary output type in order to create a preview based on the alternative output.
params params="varname=string" Passes an <xsl:param> value to a top-level parameter by identifying the parameter with the same name and providing the value.
publish publish="no" Prevents the defined stylesheet from publishing. This is useful for stylesheets that should only create a preview, such as a debug XSL for developers.

​Tagging in PCF Files

Lines 16, 17, and 19 of the example, show the tagging for an Editable Region. 

<!-- com.omniupdate.div label="title" group="Everyone" button="464" -->
<!-- com.omniupdate.editor wysiwyg="yes" -->
Faculty Directory
<!-- /com.omniupdate.div -->

This method of defining editable regions is the same as used in standard page tagging. As a general rule when using OmniUpdate tagging within a PCF, there should be absolutely no child nodes within the region defined by the page tagging except for any XHTML output generated by the WYSIWYG editor, or otherwise valid XHTML. This is due to the nature of XML.

Additional qualities of XML leave a large range of character entity references undefined. These include entity references such as those for a non-breaking space: &nbsp; or for a copyright mark: &copy; In order to function correctly within a PCF, they must first be defined in the Document Type Declaration (DTD).

DTDs can be declared either in-line or by referencing an external DTD. The DOCTYPE must be declared at the beginning of the PCF following any pcf-stylesheet declarations. 

Take, for example, lines 4–8:

<!DOCTYPE document [ 
<!ENTITY nbsp "&#160;">
<!ENTITY copy "&#169;">
<!ENTITY trade "&#8482;">
]>

This makes use of an in-line definition for non-breaking spaces, copyright symbol, and trademark symbol.

Step By Step Explanation of Example

The faculty-directory.pcf example contains fictitious faculty directory-type data stored in XML format. The first pcf-stylesheet declaration instructs OmniUpdate via the extension attribute to output a file named faculty-directory.html using the XSL file defined by the path attribute. The second pcf-stylesheet declaration directs OmniUpdate to output at publish time, an additional CSV file, formatted by the respective XSL file (because the alternate attribute is set to "yes").

When a user edits faculty-directory.pcf within the OmniUpdate environment, they will be presented with data in the PCF file rendered according to the XSL file defined in the pcf-stylesheet declaration where the alternate attribute is not defined or defined as "no". An edit button will appear wherever the XSL file renders the document/title node because OmniUpdate tagging resides within this node.