Custom Field Configuration

« Return to Notes Listing

Author:JonK
Last Updated:August 29, 2017 1:28 PM

TitanCMS has eight generic fields available as placeholders for simple customizations.

Of the eight fields, three are returned with Navigation requests (including TOC and Filter Blocks).  These three Navigation-related fields along with the remaining five are returned with Document requests and are available to Blocks.  Of the five Document-related fields, three are treated as versioned data and two are non-versioned.  All of the fields can store Unicode strings up to the limit of SQL Server (i.e., NVARCHAR(MAX)).  Within the workstation, all eight fields are retrieved with requests for the Properties Tab, and, if present are saved when the Properties Tab is saved. 

Webmasters have control over the display of these fields. Instead of the fields being hard-coded into the Properties Tab, you can fine-tune the data entry for the fields using the AppControl variable, “CustomPropertiesXML”.

 

XML Format Overview

The XML stored in the variable, CustomPropertiesXml, has a format of:

<Fields>
  <Field ControlType="Header" Header="Custom Information"/>

  <Field ID="propCustomNavFlag1"
       XPathExtractor="/Properties/CustomNavFlag1[@Same=1]"
       XPathName="CustomNavFlag1"
       FriendlyName="Custom Navigation Data 1"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormFilePicker"
       Source="ClientCssRoot"/>
	   
  <Field ID="propCustomNavFlag2"
       XPathExtractor="/Properties/CustomNavFlag2[@Same=1]"
       XPathName="CustomNavFlag2"
       FriendlyName="Custom Navigation Data 2"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormInputControl" />
	   
  <Field ControlType="Alert" Header="Non-Versioned Data">
    Changes take effect immediately upon saving.
  </Field>
</Fields>

The XML defines zero or more fields to be displayed within the Properties Tab.  All of the fields specified within the XML will appear together, in the same order they appear within the XML.  In addition to specifying controls for data entry, you can also define headers for grouping your controls and alert messages for providing additional information.

 

Custom Property Pseudo Controls

Two pseudo fields can be specified: Headers and Alerts.  

Header Type

Use the Header Pseudo Control to define your custom control area on the Properties Tab. 

A field specified with a ControlType set to “Header” will display a title area.  The content of the title area is the text you specify with the required Header attribute.  Note: that keyword “Header” within ControlType is case sensitive.

<Fields>
  ...
  <Field ControlType="Header" Header="Custom Information"/>
  ...
</Fields>
Alert Type

In some circumstances you may need to provide additional information to the user of the system.  The Alert Pseudo Control allows you to add standard Titan alert messages within your custom field area. 

A Field defined with the Pseudo ControlType of Alert will display the standard Titan Alert panel.  The attribute Header defines the title area of the alert and the content of the Field Element will be used for the body of the alert. 

<Fields>
  ...
  <Field ControlType="Alert" Header="Non-Versioned Data">
    Changes take effect immediately upon saving.
  </Field>
  ...
</Fields>

 

Custom Property Input Controls

Include one Field element in the CustomPropertiesXML for each custom field you want displayed on the Properties Tab. The database fields you may access can be found at:

<Fields>
  ...
  <Field ID="propCustomNavFlag2"
       XPathExtractor="/Properties/CustomNavFlag2[@Same=1]"
       XPathName="CustomNavFlag2"
       FriendlyName="Custom Navigation Data 2"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormInputControl" />
  ...
</Fields>
Required Attributes
  • ID – must be an ID unique to the Properties Tab.
  • ControlType – One of the two pseudo controls, Header or Alert, or any .Net control that inherits from CmsFormControlBase. 
Common Attributes
  • Label – text that appears above the control.  If not provided, FriendlyName is used
  • Title – hover text for label.  If not provided, Label is used.
  • FriendlyName – label that appears in the Session Edit History tab
  • SupportsMultiEdit – if false, hides the control in multi-edit mode.  Defaults to true.
  • XPathExtractor – used to extract the initial value from document data.  Required if Field element is not CmsFormCheckboxSet or CmsFormRadioButtonSet.
    • The Titan custom fields can be found at:
      • /Properties/CustomNavFlag1
      • /Properties/CustomNavFlag2
      • /Properties/CustomNavFlag3
      • /Properties/CustomFlag1
      • /Properties/CustomFlag2
      • /Properties/CustomFlag3
      • /Properties/CustomFlag4
      • /Properties/CustomFlag5
        • You will notice the use of the qualifier [@Same=1] on most properties.  This qualifier will always be true in single-edit scenarios; under multi-edit scenarios it is only true if the value for the field is the same for all CMS Items in the edit set.  Thus, by adding the qualifier [@Same=1], no value will be displayed unless all Cms Items in the edit set contain the same value.
  • XPathName – node name used in packaging changed data. Required if CustomXPathFunction is not provided.
  • CustomXPathFunction – JavaScript function that overrides the default XML packaging for the control.  If not provided, the ValueExtractor is used in combination with the XPathName.
  • ValidatorFunction – JavaScript function used to test validity of user input.  Most controls supply a default value based on the rendered HTML type.  If not provided, it is assumed the control is always in a valid, savable state.
  • ChangeDetector – JavaScript function used to determine if the user changed the value.  Most controls supply a default value based on the rendered HTML type.  If not provided, defaults to false and no data will be saved.
  • ChangeMessage – JavaScript function used to override the default change message that appears in the Session Edit History tab.  Most controls supply a default value based on the rendered HTML type.
  • DefaultValueExtractor– JavaScript function used to retrieve the original control value.  Most controls supply a default value based on the rendered HTML type.
  • ValueExtractor – JavaScript function used to retrieve the current control value.  Most controls supply a default value based on the rendered HTML type.
  • SetValueFunction – JavaScript function used to reset the current value of a control.  Most controls supply a default value based on the rendered HTML type.   Currently this function is no longer used by the framework, but is reserved for future use.
  • AdditionalStyles – values supplied are passed directly to the HTML element’s style attribute.

 

Controls Supplied with Titan
CmsFormInputControl

Displays a simple HTML input control.  Generally used with AdditionalStyles=”width:85%” or another appropriate width. 

<Fields>
  ...
  <Field ID="propCustomNavFlag2"
       XPathExtractor="/Properties/CustomNavFlag2[@Same=1]"
       XPathName="CustomNavFlag2"
       FriendlyName="Custom Navigation Data 2"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormInputControl" />
  ...
</Fields>

 

CmsFormTextAreaControl

Displays a textarea HTML control.  You can control the width and height using the standard style attribute.

<Fields>
  ...
  <Field ID="propCustomNavFlag2"
       XPathExtractor="/Properties/CustomNavFlag2[@Same=1]"
       XPathName="CustomNavFlag2"
       FriendlyName="Custom Navigation Data 2"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormTextAreaControl" />
  ...
</Fields>

 

CmsFormSpan

Displays a non-editable span tag on the tab (e.g., UploadDate in the File Editor).  The value of the span can be just informative or it can be a control whose data is packaged and returned to the server.  CmsFormSpan does not support multi-edit mode.

<Fields>
  ...
  <Field ID="propCustomNavFlag2"
       XPathExtractor="/Properties/CustomNavFlag2[@Same=1]"
       XPathName="CustomNavFlag2"
       FriendlyName="Custom Navigation Data 2"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormSpan" />
  ...
</Fields>

 

CmsFormFreeform

Displays the Freeform editor. Additional configuration parameters include:

  • IFrameWidth is a string that can be assigned to the css width attribute.  Note: setting a width that is too wide will cause the freeform editor’s div to wrap to the next line, thus losing its left margin.
  • IFrameHeight is a string that can be assigned to the css height attribute.  Note: a minimum height of 480px is required to support the standard CMS dialogs for image and link management.
  • CmsExtensions is a Boolean indicating whether or not the standard CMS extension dialogs (e.g., image manager and link manager) should be added to the toolbars.
  • ConfigFile is the path to the RadEditor XML config file.  The file name should begin with a /.   No equivalent is provided for FCK.
  • CssClass is the class name to associated within the editor.
<Fields>
  ...
  <Field ID="propCustomNavFlag2"
       XPathExtractor="/Properties/CustomNavFlag2[@Same=1]"
       XPathName="CustomNavFlag2"
       FriendlyName="Custom Navigation Data 2"
       ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormFreeform" 
       IFrameHeight="480px"
       IFrameWidth="85%" />
  ...
</Fields>

 

FormRadioButtonSet

Displays a set of HTML radio button or checkbox controls. Individual controls are defined as Item elements within the Field element. XPath extraction information is provided with each item, but packaging information remains with the enclosing control

<Fields>
  ...
  <Field ID="propCustomNavFlag3"
		XPathName="CustomNavFlag3"
		FriendlyName="Custom Navigation Data 3"
		ControlType="NorthwoodsSoftwareDevelopment.Cms.Display.CmsFormRadioButtonSet">
		
		<Item ID="propCustomNavFlag3_val1"
			Value="val1"
			XPathExtractor="/Properties/CustomNavFlag3[@Same=1][.!='val2']"
			Label="Value 1 label" />
			
		<Item ID="propCustomNavFlag3_val2"
			Value="val2"
			XPathExtractor="/Properties/CustomNavFlag3[@Same=1][.='val2']"
			Label="Value 2 label"/>
  </Field>
  ...
</Fields>

Additional configuration for each item:

  • ID – must be a unique ID for the Properties Tab.
  • Value – is the value of the radio button or checkbox.  It is delivered to the database as the value of the containing control.
  • XPathExtractor – is used to determine the initial check state of the radio button or checkbox.  This extractor should return true or false.
  • Label – is the value that appears to the right of the control

 

FormCheckBoxSet

Displays one or more HTML checkbox controls.  Individual checkbox controls are specified with the Item sub-element (see FormRadioButtonSet for arguments).  Note: only the first checkbox control will be saved to the assigned field using the default XML Packaging routines.  If you use more than one checkbox in your set you must provide a CustomXPathFunction and should probably also provide custom functions for the extractor and setter functions.

 

CmsFormFilePicker

Displays an input control with a paired Browse button (e.g., CSS File in the Properties tab).  When the button is pressed, the CMS File Picker is displayed and the user’s selection is written to the input control.  

CmsFormFilePicker adds the attribute:

  • Source – determines what appears in the picker.  One of FilePiles (shows all file pile items), Images (shows just the images from the file piles), or ClientCssRoot (points to the root of the display-side CSS directory).
top