Page Properties

Parameter
Parameter Select Option

Page properties are a useful tool for managing nearly any page characteristic. Edit hidden content with ease, such as meta keywords, description, and author; change the page template, or choose a different skin for a content region; and select a page header, from a list of available possibilities, without having to worry about user error or "editing code". These are some of the many possible applications website administrators can provide to users through the Page Properties window.

Implementation of page properties is simple. This section describes the implementation process and outlines several common applications to provide dynamic control of a page through the page properties window.

For information on the end-user interface, visit the interface page properties page.

1.2 Limited to PCF/XML-based implementations

Advanced configuration parameters are written in eXtensible Markup Language (XML) and reside in the publish control file (PCF). Because these parameters are XML-based, they are not supported on pages without an XML Stylesheet Language Translations (XSLT) implementation. For more information, see the section on PCF implementation, section 2.3.

The PCF is an XML file, which is processed by the XSL engine into an HTML document. This process is shown in the following flowchart diagram:

XSL Flowchart

Figure 1.2.1: XSL Flowchart diagram, rendering the PCF as HTML

1.3 Common Applications

The advanced parameters shown in figure 1.1 are very useful. These can be used to control the behavior of a page within a restricted, user-friendly form that is easy to implement. This section outlines several applications, and briefly explains how to implement them.

1.3.1 Show or Hide a Page Region

Page properties are implemented in the PCF file, and are used by the XSL stylesheet when rendering the page as HTML. Using a radio button, a page region may be turned on and off using conditional logic in an XSL Stylesheet. To begin, insert a radio option page property tag into the  section. Page parameters should be located within an XML <config> tag, as shown in the code sample in figure 1.1 (a). To copy this code sample to the clipboard, use the mouseover buttons as shown in figure 1.1 (b):

<?xml version="1.0" encoding="utf-8"?>
<?pcf-stylesheet path="/_resources/xsl/default.xsl" extension="html"?>

<!DOCTYPE document SYSTEM "http://www.gallenauniversity.com/_resources/dtd/standard.dtd">

<document>
	<config>
		<!-- com.omniupdate.properties -->
              
		<parameter name="details_box" type="radio" group="Everyone" prompt="Details Box" alt="Enable the Details Box?">
			<option value="true" selected="true">Yes</option>
			<option value="false" selected="false">No</option>
		</parameter>

		<!-- /com.omniupdate.properties -->
	</config>

	<!-- com.omniupdate.properties -->
	<title>Gallena University Athletics</title>
	<!-- /com.omniupdate.properties -->

	<content>
	</content>
</document>

(a)

copy button

(b)

Figure 1.3.1: PCF File showing a radio button parameter field. Showing (a) a sample PCF file, and (b) the mouseover button used to copy this code snippet

Next, use an <xsl:if> statement to control whether the region is displayed on the page. This will reside in your XSL template file:

<xsl:if test="document/config/parameter[@name=‘details_box']/option[@selected=‘true' and @value=‘true']">
	<xsl:copy-of select="document/content/details_box/node()" /> 
</xsl:if>

Figure 1.3.2: XSL conditional logic, which tests if a page property is set

If the selected parameter option does not have a value of "true", the XSL Stylesheet does not display the content region on the page. In this way, a content region may be shown or hidden using an easily adjustable page property.

1.3.2 Pre-determined keywords

The traditional way of specifying meta keywords is using a comma separated list of terms that are related to a page. Advanced configuration parameters make this process even easier.

A potential list of keywords may be defined in the page properties window as a set of checkbox fields, with a checkbox assigned to each keyword; the user can then select the keywords that they want.

The following code snippet in figure 1.3 shows a set of checkbox options that determine the meta keywords. XSL should be used to convert this parameter tag into an XHTML meta tag in the published file.

<parameter name="keywords" type="checkbox" group="Everyone" prompt="Keywords" alt="Select keywords that relate to this page.">
	<option value="academics" selected="false">Academics</option>
	<option value="admissions" selected="false">Admissions</option>
	<option value="matriculation" selected="false">Matriculation</option>
	<option value="athletics" selected="true">Athletics</option>
	<option value="sports" selected="true">Sports</option>
	<option value="basketball" selected="true">Basketball</option>
	<option value="football" selected="true">Football</option>
	<option value="volleyball" selected="true">Volleyball</option>
	<option value="tennis" selected="true">Tennis</option>
</parameter>

Figure 1.3.3: Checkbox page property field, which allows the selection of predefined meta keywords

<meta name="keywords">
	<xsl:attribute name="content">
		<xsl:for-each 
			select="document/config/parameter[@name=‘keywords']/
			option[@selected=‘true']">
				<xsl:value-of select="@value" />
				<xsl:if test="position()!=last()">
					<xsl:text>, </xsl:text>
				</xsl:if>
		</xsl:for-each>
	</xsl:attribute>
</meta>

Figure 1.3.4: XSL param variable, which retrieves the parameter pagetype setting

1.3.3 Position Objects

Object positioning can be controlled using parameters and XSL. In the following example, a page properties select field is used to control the position of a content box on the page:

<parameter name="box_position" type="select" group="Everyone" prompt="Details box position?" alt="Specify the position of the details box.">
	<option value="right_top" selected="true">Right Top (Box)</option>
	<option value="top_banner" selected="false">Top (Banner)</option>
	<option value="bottom" selected="false">Bottom (Banner)</option>
	<option value="hide" selected="false">Hide</option>
</parameter>

Figure 1.3.5: Select page property field, which determines the location of a content box within the page

1.3.4 Change templates

Change your page template quickly and easily using page properties and XSL! Simply define a select field page property for "page type" and apply the appropriate XSL logic as you see fit:

<parameter name="pagetype" type="select" group="pagetype_editors" prompt="Pagetype" alt="Specify a template pagetype.">
	<option value="full_screen" selected="true">Full Screen</option>
	<option value="two_column" selected="false">Two-column</option>
</parameter>

Figure 1.3.6: Select page property field, which determines the template page type

<xsl:choose>
	<xsl:when 
		test="document/config/parameter[@name=‘pagetype']/option[@selected=‘true']/@value = 'two_column'">
		<div id="col1" ></div>
		<div id="col2" ></div>
	</xsl:when>
	<xsl:otherwise>
		<div id="full_screen" ></div>
	</xsl:otherwise>
</xsl:choose>

Figure 1.3.7: XSL choose statement, displays content according to the parameter pagetype setting

1.3.5 Control Navigation Locations

Sometimes it is desirable to change the location of the sub-navigation. The following example has three location options: in the left column, just underneath the left navigation; in the body of the main content region, at the top of the page, and right aligned; or hidden entirely.

<parameter name="subnav_position" type="select" group="Everyone" prompt="Sub-navigation position?" alt="Specify the position of the sub-navigation.">
	<option value="left" selected="true">Below Left Navigation</option>
	<option value="box_right" selected="false">Box, Right Aligned</option>
	<option value="hide" selected="false">Hidden</option>
</parameter>

Figure 1.3.8: Select page property field, which determines the location of the sub-navigation

1.3.6 Use a file-chooser to select a content include file

File-choosers are used to browse for a file. This field type is an excellent method for allowing end users to provide a valid, absolute path to an include file. The following example shows how to use a file chooser parameter field:

<parameter name="article_include" type="filechooser" group="Everyone" prompt="Article include location?" alt="Specify the article you would like to import.">
</parameter>

Figure 1.3.9: File chooser page property field, which determines the path to an include file

1.3.7 Choose an RSS feed XML file to display on a page

As with the previous example, a file chooser is used again to specify the path to an RSS XML file:

<parameter name="RSS_path" type="filechooser" group="admins" prompt="RSS XML path?" alt="Specify the location of an RSS XML file.">
</parameter>

Figure 1.3.10: File chooser page property field, which determines the path to an RSS XML file

<xsl:variable name="rss" select="document/config/parameter[@name='RSS_path']" />
<xsl:value-of select="document($rss)/rss/channel/title" />

Figure 1.3.11: XSL file referencing an external XML document

1.3.8 Choose an external XML resource

Again, the file chooser can be used to select the path to an external XML resource file for use in your XSL or server-side scripts:

<parameter name="XML_path" type="filechooser" group="resource_editors" prompt="Path to an XML file?" alt="Specify the location of an XML resource file.">
</parameter>

Figure 1.3.12: File chooser page property field, which determines the path to an external XML resource file

<xsl:value-of select="document/config/parameter[@name='XML_path']" />

Figure 1.3.13: Get the absolute path from the file chooser parameter defined in figure 1.13

1.3.9 Choose an XML resource for javascript or flash

Once more, the file chooser is useful in selecting XML data for javascript and flash applications:

<parameter name="XML_path" type="filechooser" group="javascript_editors" 
	prompt="Path to an XML resource?" alt="Specify the location of an XML resource file.">
</parameter>

Figure 1.3.14: File chooser page property field, which determines the path to an XML data file

1.3.10 Choose a CSS skin

CSS skins can be dynamically selected using a page properties select field. The XSL Stylesheet then chooses from a set of CSS files based on the value of this parameter.

<parameter name="css_skin" type="select" group="Everyone" prompt="CSS Skin" alt="Specify a CSS skin.">
	<option value="sea_blue" selected="true">Sans-serif Fonts, Sea Blue</option>
	<option value="georgia_grey" selected="false">Georgia, Grey, Burgundy</option>
	<option value="futuristic" selected="false">Futuristic</option>
</parameter>

Figure 1.3.15: Select page property field, which allows the user to choose a CSS skin

<xsl:choose>
	<xsl:when 
		test="document/config/parameter[@name='css_skin']/option[@selected=‘true' and @value=‘sea_blue']">
		<link rel="stylesheet" type="text/css" href="/css/sea_blue.css" /> 
	</xsl:when>
	<xsl:when 
		test="document/config/parameter[@name='css_skin']/option[@selected=‘true' and @value=‘georgia_grey']">
		<link rel="stylesheet" type="text/css" href="/css/georgia_grey.css" /> 
	</xsl:when>
	<xsl:when 
		test="document/config/parameter[@name='css_skin']/option[@selected=‘true' and @value=‘futuristic']">
		<link rel="stylesheet" type="text/css" href="/css/futuristic.css" /> 
	</xsl:when>
	<xsl:otherwise>
		<link rel="stylesheet" type="text/css" href="/css/default.css" />
	</xsl:otherwise>
</xsl:choose>

Figure 1.3.16: XSL param variable, which retrieves the parameter pagetype setting

1.3.11 Specify a graphic or video resource, or display none at all

Use a filechooser parameter and select parameter to choose a resource for the webpage header. This resource can be any type, so long as the type is selected in the dropdown field. An example is shown below:

<parameter name="resource_type" type="select" group="header_editors" prompt="Resource Type?" alt="Specify the resource type.">
	<option value="graphic" selected="true">Graphic</option>
	<option value="flash" selected="false">Flash</option>
	<option value="quicktime" selected="false">Quicktime Video</option>
	<option value="none" selected="false">Off</option>
</parameter>
<parameter name="resource_path" type="filechooser" group="header_editors" prompt="Resource Path?" alt="Specify the location of a resource file.">
</parameter>

Figure 1.3.17: Select a resource type and absolute file path

Next, configure your XSL Stylesheet to output appropriate HTML tagging for the resource, according to its resource type. An example XSL snippet is shown below:

<xsl:variable name="resource_path" 
	select="document/config/parameter[@name='resource_path']" />
<xsl:choose>
	<xsl:when test="document/config/parameter[@name='resource_type']/option[@selected=‘true' and @value=‘graphic']">
		<img src="{$resource_path}" border="0" /> 
	</xsl:when>
	<xsl:when test="document/config/parameter[@name='resource_type']/option[@selected=‘true' and @value=‘flash']">
		<object width="550" height="400">
			<param name="movie"	value="{$resource_path}">
			<embed src="{$resource_path}" width="550" height="400"></embed>
		</object> 
	</xsl:when>
	<xsl:when test="document/config/parameter[@name='resource_type']/option[@selected=‘true' and @value=‘quicktime']">
		<object 
			classid="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B" 
			codebase="http://www.apple.com/qtactivex/qtplugin.cab"
			height="200"
			width="200">
		<param name="src" value="{$resource_path}"/>
		<param name="scale" value="aspect" />
		<param name="controller" value="true" />
		<param name="autoplay" value="false" />
		<embed 
			type="video/quicktime"
			pluginspage="http://www.apple.com/quicktime/download/"
			height="200"
			width="200"
			src="{$resource_path}"
			scale="aspect"
			controller="true" 
			autoplay="false" />
		</object>
	</xsl:when>
	<xsl:otherwise>
		<!-- do nothing -->
	</xsl:otherwise>
</xsl:choose>

Figure 1.3.18: XSL snippet, which outputs a graphic or video resource based on the specified resource type

2. Implementing Page Properties

Page properties may be implemented either on a per-page basis or within page templates. The property tagging is written to the publish control file (PCF); this file is an XML representation of a webpage and requires an XSL Stylesheet to preview or publish HTML output. Page properties are represented in templates by variable parameters in the template control file (TCF). These variables can then be used immediately during the creation of a new page with echo statements in the template file (TMPL).

This section outlines the implementation of page properties within all relevant file types: TCF, TMPL, PCF, and XSL.

2.1 Template Control File (TCF)

TCF variables provide a means to control page creation and insert content immediately into a new page. These variables are presented to the user as one of five possible form field types: text, checkbox, dropdown (select), radio, file chooser.

The default TCF variable type is 'text'. The variable type can be changed using the type attribute. Variables with option nodes must have output="xml" declared. Example variable tags are shown below:

<variable-list>
         <variable name="title"></variable>
         <variable name="description></variable>

         <variable name="color" type="select" output="xml">
                 <option value="red">Red Text</option>
                 <option value="green">Green Text</option>
                 <option value="blue">Blue Text</option>

         </variable>
         <variable name="keywords" type="checkbox" output="xml">
                 <option value="sports">Sports</option>
                 <option value="academics">Academics</option>
                 <option value="admissions">Admissions</option>

         </variable>
         <variable name="fullpage" type="radio" output="xml">
                 <option value="true">Yes</option>
                 <option value="false">No</option>
         </variable>

</variable-list>

Figure 2.1.1: Sample TCF variable list

For a complete reference on template control files (TCF), visit the following url: http://support.omniupdate.com/documentation/ox/10/implementation/templates/reference/tcf

2.2 Template File (TMPL)

Template (TMPL) files determine the output of a page template. This file contains the structure of the page, in either XHTML or XML format, and references variables in the TCF using an echo statement. An example template file is shown below:

<?xml version="1.0" encoding="utf-8"?>
<?pcf-stylesheet path="/_resources/xsl/default.xsl" extension="html"?>
 
 
<!DOCTYPE document SYSTEM "http://www.gallenauniversity.com/_resources/dtd/standard.dtd">
 
<document>
 
         <config>
                 <!-- com.omniupdate.properties -->
                 <parameter name="color" type="select" group="Everyone">
                          <!--%echo encoding="none" var="color" -->
                 </parameter>
                 
                 <parameter name="keywords" type="checkbox" group="Everyone">
                          <!--%echo encoding="none" var="keywords" -->
                 </parameter>
                 
                 <parameter name="description" type="text" group="Everyone">
                           <!--%echo var="description" -->
                  </parameter>
                 
                 <parameter name="fullpage" type="radio" group="Everyone">
                          <!--%echo encoding="none" var="fullpage" -->
                 </parameter>
                  <!-- /com.omniupdate.properties -->

         </config>
 
         <!-- com.omniupdate.properties -->
         <title><!--%echo var="title" --></title>
         <!-- /com.omniupdate.properties -->
 
         <content>

 
         </content>
 
</document>

Figure 2.2.1: Sample TMPL File, showing several page property form types

The echo statements shown in figure 2.2 reference TCF variables by name using the "var" attribute. If the encoding attribute is set to "none", characters will not be escaped to their entity equivalents. For example, the '<' character will not be converted to <. This allows XML nodes to be directly injected into the page, which is required for some page property types to function. Encoding must be set to "none" for the following variable types: checkbox, select, and radio.

Template (TMPL) Reference

2.3 Publish Control File (PCF)

Publish control files (PCF) contain the content of XML-based pages. These files are converted into XHTML, using an XSL Stylesheet. Page properties are defined in the PCF config node and reside between opening and closing  comment tags. A sample config node is shown below:

<?xml version="1.0" encoding="utf-8"?>
<?pcf-stylesheet path="/_resources/xsl/default.xsl" extension="html"?>

<!DOCTYPE document SYSTEM "http://www.gallenauniversity.com/_resources/dtd/standard.dtd">

<document>
       <config>
              <!-- com.omniupdate.properties -->
              <parameter name="color" type="select" group="Everyone" prompt="Color" alt="Page Type">
                     <option value="red" selected="true">Full width</option>

                     <option value="green" selected="false">Left Column</option>
                     <option value="blue" selected="false">Left and Right Columns</option>
              </parameter>

              <parameter name="keywords" type="checkbox" group="Everyone" prompt="Keywords" alt="Select keywords that relate to this page.">

                     <option value="academics" selected="false">Academics</option>
                     <option value="admissions" selected="false">Admissions</option>
                     <option value="matriculation" selected="false">Matriculation</option>
                     <option value="athletics" selected="true">Athletics</option>

                     <option value="sports" selected="true">Sports</option>
                     <option value="basketball" selected="true">Basketball</option>
                     <option value="football" selected="true">Football</option>
                     <option value="volleyball" selected="true">Volleyball</option>

                     <option value="tennis" selected="true">Tennis</option>
              </parameter>

              <parameter name="author" type="text" group="Everyone" prompt="Author" 
                     alt="Please tell us your name."></parameter>

              <meta name="description" content="Athletics at Gallena University!" />

              <!-- /com.omniupdate.properties -->
       </config>

       <!-- com.omniupdate.properties -->
       <title>Gallena University Athletics</title>
       <!-- /com.omniupdate.properties -->

       <content>
       </content>
</document>

Figure 2.3.1: Example PCF file, showing page properties tagging

2.4 XML Stylesheet Language Translations File (XSL)

XSL is used to convert XML-based content, such as within a PCF file, into production-ready XHTML. Page properties tagging, using the parameter and option tags in the PCF file, allows an XSL Stylesheet to use conditional logic to format the page in any way that is desired.

XSL is very powerful. Several applications and examples of XSL interacting with page properties are described in section 1.3; nonetheless, these applications, as listed in section 1.3, are not exhaustive. This technology affords the developer limitless creativity, and many additional applications are possible.

3. Best Practices

Several best practices can be followed. Each of these is outlined in this section.

3.1 Avoid page properties to store and edit content

Page properties are meant to store hidden data and control aspects of the page. Page content should not be stored using page properties; instead it should be stored in an editable region on the page instead.

The reason behind this is clear when looking at the structure of the PCF file. Page properties are children of the <config> node; therefore, these properties are meant to merely affect the configuration of the page, not provide content. Likewise, editable regions are children of the <content> node because these regions provide content for the page.

3.2 Assign sensitive properties to user groups

The page properties window supports the assignment of user groups. Each property is assigned a user group, and only members of that group can edit that particular property. For example, if the group is set to 'administrators', then only members of the 'administrators' group will see this field in the page properties window. If the group parameter is set to 'Everyone', then all users will have access to that property.

4. Tagging Reference

Page properties are implemented in the PCF using two XML tags: parameter and option. Each page property is defined by a single parameter node. Option nodes define selectable options for the following parameter types: checkbox, select, and radio. This section is a reference for parameter and option and describes these nodes in detail.

Parameter

The parameter node allows for the storing of parameters in the pcf to be accessed through the page properties interface.

A grouping of parameters are defined by surrounding them with the <-- com.omniupdate.properties --><-- /com.omniupdate.properties --> tag.

Syntax:
<parameter> </parameter>

Example:

<parameter type="text" name="description" prompt="Description" alt="A short description for this page." group="Everyone">Here is an example.</parameter>

Parameters ( toggle all )

alt

Similar to the prompt parameter, alt gives more information about the input required in a text field. It's displayed to the right of the text box, and usually offers an example or more information. This field is not required, and defaults to null / not displayed.
Syntax:
alt="string"
group (Required)
Editing group that can edit this area (Optional): The group identifies which group has access to edit the specific parameter. If you do not include a group there will be no parameter shown, even for administrators. Level-9 and 10 users will only see the parameters that have a valid group defined. All other editors will only see the parameters that have a valid group defined, assuming they are also a member of the specified group.

It is often helpful to use the default group "Everyone" for the main parameters of the page, then unique groups for such parameters that not everyone should be changing. Because the group "Everyone" contains all users, you'll be able to quickly assign page access to any specific sub-group without changing the group attribute in the code. Remember that only people assigned access to a page can access and edit the properties for that page, regardless of the "Group" assigned to selective parameters.
Syntax:
group="Everyone | group name"
- Everyone - All users
- group name - A group name as configured within OUCampus' group setup.
name (Required)

The name of the parameter is to be used by the system as an identifier, and therefore is not seen by the end-user. This parameter is, by nature, required to be defined for each parameter. It needs to be unique and is generally the attribute you use to refer back to the specific parameter from the XSL.
Syntax:
name="string variable name"
prompt

This is the question posed to the user. It's displayed on the left side of the user's input text field. A colon (:) is automatically added to the end of this prompt. This parameter is not required, and defaults to null / not displayed.
Syntax:
prompt="string"
type
This is the type of parameter. This is used to determine how the parameter is displayed to the end-user. If the type is checkbox, select, or radio then you should have more than one <option> element as a child of the parameter.
Syntax:
type="text | select | filechooser | checkbox | radio"
- text - Parameter is simple text
- select - Parameter is defined by user by choosing from a select-pulldown. Parameter will be the value of the user-selected option.
- filechooser - Parameter is defined by user by navigating to and selecting a file. Parameter will be an absolute path from the root of the staging or production server.
- checkbox - Parameter is defined by user by toggling the value of a checkbox. Parameter will be the value of the user-selected option.
- radio - Parameter is defined by user by choosing from a set of radio buttons. Parameter will be the value of the user-selected option.

Parameter Select Option

This will produce a drop-down menu; the value of the choice will be marked as selected in the pcf.

This only applies to the parameter node where the type is select,checkbox, or radio.

Syntax:
<option> </option>

Example:

<parameter name="color" type="select" group="Everyone" prompt="Color" alt="Pick a color.">
  <option value="red" selected="false">Red</option>
  <option value="green" selected="false">Green</option>
  <option value="blue" selected="true">Blue</option>
</parameter>

Parameters ( toggle all )

selected (Required)

This determines whether or not the option has been marked or selected. This attribute can be used by the XSL to find only options that have been selected.
Syntax:
selected="true | false"
value (Required)

This is the same format and functionality as the option element defined in the XHTML specification and defines an options value for user-selection in a select field.
Syntax:
value="string value"

Example:
<option value="blue" selected="true">Blue Text</option>

Page Properties

Contents

1.2 Limited to PCF/XML-based implementations

1.3 Common Applications

1.3.1 Show or Hide a Page Region

1.3.2 Pre-determined keywords

1.3.3 Position Objects

1.3.4 Change templates

1.3.5 Control Navigation Locations

1.3.6 Use a file-chooser to select a content include file

1.3.7 Choose an RSS feed XML file to display on a page

1.3.8 Choose an external XML resource

1.3.9 Choose an XML resource for javascript or flash

1.3.10 Choose a CSS skin

1.3.11 Specify a graphic or video resource, or display none at all

2. Implementing Page Properties

2.1 Template Control File (TCF)

2.2 Template File (TMPL)

2.3 Publish Control File (PCF)

2.4 XML Stylesheet Language Translations File (XSL)

3. Best Practices

3.1 Avoid page properties to store and edit content

3.2 Assign sensitive properties to user groups

4. Tagging Reference

Parameter

Parameters ( toggle all )

alt

group (Required)

name (Required)

prompt

type

Parameter Select Option

Parameters ( toggle all )

selected (Required)

value (Required)

Documents