Use the Content Template Creator

This separately-licensed feature, available only to Certified System Implementers for use in development orgs, lets you create custom "user-defined" content templates and associated content editors that meet the specific needs of your customers.

Custom Content Template Export/Import

As part of the OrchestraCMS Content Template Creator feature, you can easily export custom content templates from a development Salesforce organization and import custom content templates into sandbox and production Salesforce organizations.

The custom templates are available in OrchestraCMS Setup under Content Templates. A button, New Content Template, opens the Content Template Creator so you can begin creating your new content template.

Each template has an edit link that allows you to change different parts of the templates. You can choose a content template name, label, description and thumbnail.

Create a Custom Content Template

1. In Setup, under Templates, select Content Templates.
2. On the Content Template page, to the right of "User-defined Content Templates", click New.
3. On the Content Template Creator page, fill in the "Name", "Label" and "Description" fields. (The "Description" field is optional but recommended.)

You can also set a thumbnail for the content template so users can easily and quickly identify it when they’re creating new content.

To set a thumbnail for a content template

1. In the Content Template Creator,  under Thumbnail, select Choose File.
   
2. In your local browser window, navigate to the required image. Click OK.
3. Click Save.

Images selected as thumbnail images will be scaled down to 194 x 144 px and have a grey border placed around them.

To create content template attributes

1. In Attributes and Editor Settings, fill in "Section Title". This labels a section within the content edit screen that OrchestraCMS users see when they create an instance using this content template. You can label multiple sections to be displayed in the same content edit screen.
   
2. Under Type, from the dropdown menu, choose an attribute type. The available types are defined below.
3. Under Attribute name, name the attribute. This is the value that will be used to reference the attribute programmatically.

4. Under Input Label, give the attribute a label. This is the value that will be displayed to the end user when they are creating or editing a piece of content based on this content template.
5. Continue in the same way to create further new attribute sets.
6. Click Save.
   • To delete an attribute, click on the "X" symbol.
   • To edit a content template, in Content Templates, under "User-defined Content Templates, click the checkbox beside the relevant content template and then click Edit. You can make revisions on the Content Template Creator page.
   • To delete a content template, click the checkbox beside the relevant content template and then click Edit. On the Content Template Creator page, click Delete.
   • To create a new section, type a name in the "Section Title" box. Click on the arrow on the left for options.
   • To delete a section, click the arrow at the right of the section pane and then click Delete Section.
     

Attribute types

The following are descriptions of the attribute types in Attributes and Editor Settings.

Check box

Provides a single check box displayed on the edit page for the content. Returns a boolean value.

Image selector

Provides a UI component on the content edit page that allows the end user to select a file from the OrchestraCMS media library.  Returns the servlet URL from Salesforce for the selected media file.

Integer

Provides a field on the content edit page for the user to enter a number. Additional fields are provided on the attribute to allow the developer to set an initial number value and the minimum and maximum values the user can enter in the field. If users try to enter a value outside of the defined range, they will be presented an error message indicating the valid range. Returns the provided integer.

Multi-select picklist

Provides a field on the content edit page with a list of values defined in the attribute by the developer.

This list can be displayed on the edit page as either a box list or list of labelled checkboxes. The user can select multiple values from the list.  Returns the selected values as a string of semicolon separated values.

Single-select picklist

Provides a field on the content edit page with a list of values defined in the attribute by the developer.  This list can be displayed on the edit page as either a dropdown list or a series of labelled radio buttons.  The developer can specify the initial value to be selected in the list. The user can select a single value from the list.  Returns the selected value as a string.

Rich Text Editor

The rich text editor is an implementation of a third party tool called CKEditor within OrchestraCMS. CKEditor has a variety of configuration settings that can be used to control its behaviour and appearance on the edit page. Those options can be specified here for this particular initialization of the CKEditor UI on the content edit page.  Returns the entered text as a string.

Tag selector

The tag selector provides a field on the content edit page for the user to select tags from a taxonomy. These tags are not automatically applied to the content. This is just an interface to expose a taxonomy tag selector for the user to select tags.  Returns the selected tag as a string.

Text area

Provides a multi-line text area for plain text to be entered on the content edit screen. The developer can supply an initial value for the field as well as the maximum length.  If data is entered by the user that exceeds the maximum length, it will be truncated to the maximum length.  The Escape HTML checkbox allows special characters in the string to be escaped. Returns the entered text as a string.

Text input

Provides a standard text input field on the content edit page.  The developer can set an initial value and maximum length, after which the data is truncated and the Escape HTML, which escapes special characters in the returned string.

Custom

Intended for non-configurable attributes that will not be used across different content templates. In a content editor, it loads a specified Javascript file (JavaScript Path) and a specified CSS file (Stylesheet Path), then instantiates a Javascript Attribute object (JavaScript Object Name). Saved attribute data is processed by an Apex class (Apex Class) before being returned to the editor or generator.

The JavaScript Path should include the full resource path to a JavaScript file (ex. ‘/resource/resource_name/path/to/js/myAttribute.js’). The Stylesheet Path is optional, but should take the same form as the JavaScript path. The JavaScript Object Name should be the full name of a CTC Attribute constructor. Apex Class is optional and should have the name of an Apex AttributeDefinition class to process saved attributes.

Manage markup

Markup placed in the Markup pane will be used to render instances of content using this template on the live web site and in preview mode.

1. Under Markup, the attributes you have created will appear as buttons at the top of the markup text field.                
2. Markup can then added to the Markup frame.
   
3. To insert attributes into the appropriate locations in the markup, click the relevant buttons with the cursor located where you want to use that attribute in the markup.

When adding an attribute of the type Page Selector, clicking the button will produce a list of sub attributes you can add to the markup. Each subtype and its output is listed in the table below.

To add and reorder the sections in your content template

1. Click and hold the green bar at the top of a section.
2. Drag it up or down to place it in the order you prefer.
3. Click Save.

Add a custom content template to a content type

1. In Setup, under Templates, select Content Types.
2. Beside Custom Content Types, click New.
3. Name and label the new content type.
   
4. Click Add Templates.
5. Select the check box beside the custom content template in the dropdown list.
   
6. Save.

Attribute types as they appear in a Custom Content Template

The following images are representative of the user’s view of the fields created in the content template creator when a user creates or edits a piece of content based on the associated custom content template.

Export/import a Custom Content Template

As part of the OrchestraCMS Content Template Creator feature, you can easily export and import custom content templates between Salesforce organizations.  The Content Template Creator is only enabled for creating custom content templates in a Salesforce development org.  To move the configured content template to any other org you must use the following procedure to export it from the developer org and import it into any other Salesforce org.

To export a Custom Content Template

1. In Setup, select Content Templates.
2. In the section User-defined Content Templates, click the check box beside the relevant content template.
3. Click Export.
   
4. Copy the import string.

To import a Custom Content Template

1. In Orchestra Setup in another organization, select Content Templates.
2. In the section User-defined Content Templates, click the check box beside the relevant content template.
3. Click Import.
4. Paste the provided string in the Import Templates box.
5. Click Submit.

A notification will appear to tell you the import was successful.

Moving beyond basic templates

The Content Template Creator provides a visual interface within OrchestraCMS to define attributes. These attributes are then used:

• in the edit page of the custom content template when a user creates new content
• in the markup to be used when the content is included in the site.

A content layout record is also generated in Salesforce when a new content template is created in Content Template Creator. By default the content layout record uses values specific to the Content Template Creator for the Visualforce Edit and Controller fields on the content layout record. If a developer needs to incorporate more than the basic markup suitable to the Markup pane of the Content Template Creator, the Controller field on the content layout record can be replaced with the name of a custom apex class created by the developer.

1. Extending the generator

The default CTC generator provides logicless templating which is suitable for the most basic content templates. The following information is provided if a more robust approach is necessary.

It is not strictly necessary to use CTC's layout controller. All attributes are stored as normal, so extending cms.ContentTemplateController is still viable, although the server-side validation of CTC is not present.

To extend CTC, a layout controller should extend cms.CTCLayoutController. cms. CTCLayoutController itself extends cms.ContentTemplateController so all standard OrchestraCMS functionality (ServiceAPI, getProperty, this.content, this.content_layout_instance, etc.) is still easily accessible if necessary. There is one method to override.

String getHTML()

A controller's getHTML method functions similarly to a standard cms.ContentTemplateController extension with two key differences:

• The first line of getHTML must call this.init()
• CTC provides the global member Map<String, Object> attributeGenerateValues as an alternative to getProperty

attributeGenerateValues will be populated with validated, processed attribute data but values must be cast to the appropriate Apex type. For example, handling a page reference in a standard cms.ContentTemplateController may look similar to:

global class OldLayout extends cms.ContentTemplateController {

public String myPageReferenceString {

                get {

                        String value = getProperty('myPageReference');

                if(value == null) return '';

                        return value;

        } set;

}

public cms.Link myPageReference {

                get {

                        return new cms.Link(myPageReferenceString);

        }

}

…

global String getHTML() {

                return '<a href="' + myPageReference.targetPage + '">Link</a>';

}

}

With CTC, this code can be replaced with:

global class NewLayout extends cms.CTCLayoutController {

global String getHTML() {

        init();

                cms.Link myPageReference = (cms.Link)attributeGenerateValues.get('myPageReference');

        return '<a href="' + myPageReference.targetPage + '">Link</a>';

}

}

1.1. Testing

Testing CTC layout controllers is typically easy. The attributeGenerateValues map is exposed as a global so can be directly written to. The values inserted into the map in this way will not be processed by CTC, so will contain exactly the key/value pairs you insert. For example:

@isTest

public class TestNewLayout {

        public static testmethod void testNewLayoutHTML() {

                NewLayout lc = new NewLayout();

                lc.attributeGenerateValues = new Map<String, Object> {

                        'myPageReference' => '...', // a link CSV

                        'numberAttribute' => 7,

                        'textAttribute' => 'foo'

                };

                try {

                        lc.getHTML();

                } catch(e) {

                        System.debug(e);

                        System.assert(false, 'getHTML threw an exception.');

                }

        }

}

If a getHTML method relies on base cms.ContentTemplateController methods the underlying data properties must be set on the controller manually (lc.content = new cms__Content__c();). Any calls to the ServiceAPI must have their supporting objects inserted as normal.

2. Custom attributes

A CTC Attribute Type is composed of three pieces of code:

• A Javascript AttributeDefinition defines what fields appear for configuration in the CTC interface.
• An Apex AttributeDefinition performs any server-side processing or validation associated with the attribute type.
• A Javascript Attribute defines the appearance and behavior in a content editor.

To expose a new attribute type in CTC, a new Attribute_Data__c record must be manually created with the following fields. Any irrelevant fields may be left blank (no CSS, using a standard CTC Javascript control, no special Apex handling)

Name: A unique name used internally within CTC.

Label__c: A human-readable label used in the CTC editor.

Apex_Class_Name__c: A namespace-qualified Apex class name that should process any attributes of this type.

Editor_JS_Constructor__c: A Javascript constructor name that CTC will instantiate in the content editor. Namespacing is allowed (ex. cms_ctc.CheckboxAttribute).

Editor_Resource_Name__c: The name of a static resource that contains the Attribute Javascript and CSS files.

Editor_Script_Path__c: The path and filename within the Editor resource that contains the editor Javascript file.

Editor_Stylesheet_Path__c: The path and filename with the Editor resource that contains the editor CSS file.

Definition_JS_Constructor__c: A Javascript constructor name that CTC will instantiate in the CTC editor. Namespacing is allowed (ex. cms_ctc.CheckboxAttributeDefinition).

Definition_Resource_Name__c: The name of a static resource that contains the AttributeDefinition's Javascript and CSS files.

Definition_Script_Path__c: The path and filename within the Editor resource that contains the editor Javascript file.

Definition_Stylesheet_Path__c: The path and filename with the Editor resource that contains the editor CSS file.

2.1. Custom JavaScript AttributeDefinition

Any custom AttributeDefinition should extend cms_ctc.AttributeDefinition to provide a common base level of functionality:

function MyAttributeDefinition(id, params) {

        cms_ctc.AttributeDefinition.call(this, id, params);

        // Perform type-specific initialization

}

MyAttributeDefinition.prototype = new cms_ctc.AttributeDefinition();

A custom AttributeDefinition is responsible for rendering a set of input controls and maintaining a data store of parameter values. When a content template is saved in CTC the AttributeDefinition should return its parameter values so they can be used to configure the content editor.

For standard HTML input types, CTC provides event delegation to set values within an instance of an AttributeDefinition. By default, CTC will look at the input's "name" attribute and directly set that on an AttributeDefinition instance. This can be overridden using custom setters to provide validation or other processing.

There are several methods and properties to define on a custom AttributeDefinition's prototype that CTC will call.

MyAttributeDefinition = function(id, params)

The constructor for an AttributeDefinition takes a unique ID value and a parameter's object. Any DOM IDs produced by the AttributeDefinition should use the unique ID as a suffix to avoid conflicts, for example parameter{id}. The parameters object will contain any saved data about the attribute. See getTypeSpecificData.

MyAttributeDefinition.prototype.set_{name} = function(value)

A custom setter is named set_{name} and will be called by CTC when an input named {name} changes value in the UI. The default behavior if no setter is provided is equivalent to:

MyAttributeDefinition.prototype.set_myName = function(value) {

        this.myName = value;

}

MyAttributeDefinition.prototype.getPreviewMarkup = function()

CTC allows an attribute type to provide a custom piece of preview markup to accept a default value. The getPreivewMarkup method should return a string for a single input field. To accept a default value, the input field should have name="defaultValue".

MyAttributeDefinition.prototype.getTypeSpecificData = function()

getTypeSpecificData is called when CTC is saving changes. This should return a Javascript object containing any configuration data specific to MyAttributeDefinition. CTC will automatically store the name, label, type and helpText members.

MyAttributeDefinition.prototype.renderOptions = function($domElement)

This method should render any type-specific option markup for your attribute type into the passed jQuery container. There are CSS classes provided on the CTC page to assist in maintaining the look and feel. For example:

<div class="row attributeRow">

        <div class="column attributeOptionColumn">

                <label>

                        <div>Single column text input</div>

                        <input type="text" name="textInput">

                </label>

        </div>

        <div class="column attributeOptionColumn-2">

                <label>

                        <div>Two column textarea</div>

                        <textarea name="textareaInput"></textarea>

                </label>

        </div>

        <div class="column attributeColumn">

                <label>

                        <input type="checkbox" name="checkboxInput">

                        <span>Single column checkbox</span>

                </label>

        </div>

</div>

A CTC custom attribute type may have several rows of inputs. A row container should have at minimum the classes row and attributeRow. The row container's direct children should all have the class column, and one of attributeOptionColumn or attributeOptionColumn-2.

MyAttributeDefinition.prototype.hasOptions = {true|false}

Set to true if MyAttributeDefinition renders custom options in renderOptions. This currently controls the appearance of the button to expand and collapse the detailed view of an attribute.

MyAttributeDefinition.prototype.getNames = function()

The CTC generator allows for compound attribute names. For example, a page selector stores a CSV-formatted string as the raw attribute value. The CSV is not useful on its own in a generator and must be parsed to produce a cms.Link object with many properties. The getNames method on an AttributeDefinition tells CTC about any child attributes. It should return an object similar to:

{

        name: this.name,

        subNames: [

                this.name + '.subName1',

                this.name + '.subName2',

                …

                this.name + '.subNamen'

        ]

};

2.2. Custom Apex AttributeDefinition

An Apex AttributeDefinition class allows a developer to process stored OrchestraCMS attribute values before presenting them to the content editor or generator. This could include validation, object construction or any other cacheable logic.

Apex AttributeDefinition  classes should extend cms.AttributeDefinition. There are four virtual methods to override.

void setDefinition(Map<String, Object> definition)

After creation, CTC will call setDefinition on an instance of an AttributeDefinition. The passed Map<String, Object> will contain any configuration information specified in the CTC editor.

Object getValue(String property)

If an AttributeDefinition should return the same value in both edit and generate contexts, getValue should be overridden. Otherwise, it should be ignored and getGenerateValues and getEditValue should be overridden instead.

getValue is passed a stored OrchestraCMS attribute value that would be retrieved by getProperty in a non-CTC layout controller. It can return any Object (Integer, String, List<>, etc.). It is the responsibility of the editor or generator to correctly cast and interpret those values.

Map<String, Object> getGenerateValues(String property)

If an AttributeDefinition should return different values in edit and generate contexts, getGenerateValues and getEditValue should be overridden. In this case, getValue will be ignored by CTC.

getGenerateValues is passed a stored OrchestraCMS attribute value that would be retrieved by getProperty in a non-CTC layout controller. It should return a Map<String, Object>. The map keys correspond to any name/subname pairs (ex. myLinkName.targetPage, myLinkName.javascript, etc.)

Object getEditValue(String property)

If an AttributeDefinition should return different values in edit and generate contexts, getGenerateValues and getEditValue should be overridden. In this case, getValue will be ignored by CTC.

getEditValue is passed a stored OrchestraCMS attribute value that would be retrieved by getProperty in a non-CTC layout controller. It should return a single Object to be interpreted and used by the content editor.

2.3. Custom JavaScript attribute

Any custom Attribute should extend cms_ctc.Attribute to provide a common base level of  functionality.

function MyAttribute(id, params) {

        cms_ctc.Attribute.call(this, id, params);

        // Perform type-specific initialization

}

MyAttribute.prototype = new cms_ctc.Attribute();

A custom Attribute type is responsible for rendering and maintaining a set of input controls in an OrchestraCMS content editor. It should be configurable through parameters defined in the CTC editor and be able to return an attribute value when the content author saves their content.

There are several methods to define on a custom Attribute's prototype.

MyAttribute = function(id, params)

The constructor for an Attribute takes a unique ID and a parameters object. Any DOM IDs produced by the Attribute should use the unique ID as a suffix to avoid conflicts, for example Dialog{id}. The parameters object will contain any configuration data that was saved in the CTC editor.

MyAttribute.prototype.setValue = function(value)

After initialization, the CTC Editor will call an Attribute's setValue method once. The passed value will be the value from the Apex attributeEditValues map.

MyAttribute.prototype.renderEditorControls = function($container)

This method is responsible for rendering any markup and attaching any event handlers relevant to the Attribute instance. The passed $container is a jQuery collection containing a single DOM element. renderEditorControls should not modify the container, or manipulate the DOM outside of the container.

MyAttribute.prototype.getCmsAttribute = function($container)

This method is called when the content author presses save. It should return a Javascript object representing a single OrchestraCMS attribute, for example:

MyAttribute.prototype.getCmsAttribute = function($container) {

return {

                name: this.name,

                value: this.value,

                type: 'Text'

        };

};

If getCmsAttribute throws a string as an error, CTC will display the string to the user in a modal dialog, for example:

My Attribute.prototype.getCmsAttribute = function($container) {

        if(isNaN(this.value)) {

                throw new Error(this.label + ' must be a number.');

        }

        …

}

3. Core attribute types

This section details the core CTC attribute types. Any custom attribute type may reference the following core CTC Javascript or Apex to reuse functionality. In the case of Javascript files, all core CTC attribute types will be present. The resource name and resource path fields on an Attribute_Data__c should be left blank.

An attribute type without a specified Apex class will default to returning the attribute's stored value, as if getProperty were called directly.

3.1. Checkbox

Presents a checkbox input.

Its Apex class returns a Boolean type and accepts the following type-specific parameters:

• defaultValue (Boolean)

Definition_JS_Constructor__c = cms_ctc.CheckboxAttributeDefinition

Apex_Class_Name__c = CheckboxAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.CheckboxAttribute

3.2. Custom

Allows non-configurable attribute types (No AttributeDefinition JS) to be easily used without creating an Attribute_Data__c record.

Its Apex class delegates to the specified apexClass, and accepts the following type-specific parameters:

• apexClass (String)

Definition_JS_Constructor__c = cms_ctc.CustomAttributeDefinition

Apex_Class_Name__c = CustomAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.CustomAttribute

3.3. Image selector

Presents an OrchestraCMS media library selector.

It does not have a specialized Apex class.

Definition_JS_Constructor__c = cms_ctc.ImageSelectorAttribute

Editor_JS_Constructor__c = cms_ctc.ImageSelector

3.4. Integer

Presents an HTML number input.

Its Apex class returns an Integer and accepts the following type-specific parameters:

• minimum (Integer)
• maximum (Integer)
• defaultValue (Integer)

Definition_JS_Constructor__c = cms_ctc.IntegerAttributeDefinition

Apex_Class_Name__c = IntegerAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.IntegerAttribute

3.5. Page selector

Presents an OrchestraCMS page selector.

Its Apex class returns several entries in the generate map:

• {name} (cms.Link)
• {name}.csv (String)
• {name}.target (String)
• {name}.targetPage (String)
• {name}.javascript (String)
• {name}.linkType (String)
• {name}.link (String)
• {name}.linkName (String)
• {name}.linkId (String)
• {name}.targetType (String)
• {name}.linkJSON (String)

Its apex class does not take any type-specific parameters.

Definition_JS_Constructor__c = cms_ctc.PageSelectorAttributeDefinition

Apex_Class_Name__c = PageSelectorAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.PageSelectorAttribute

3.6. Rich text

Presents a CKEditor rich text interface.

It does not have a specialized Apex class.

Definition_JS_Constructor__c = cms_ctc.RichTextAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.RichTextAttribute

3.7. Text area

Presents a multiline HTML textarea.

Its Apex class returns a String and accepts the following type-specific parameters:

• maxLength (Integer)
• escapeHtml (Boolean)
• defaultValue (String)

Definition_JS_Constructor__c = cms_ctc.TextAreaAttributeDefinition

Apex_Class_Name__c = TextAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.TextAreaAttribute

3.8. Text input

Presents a single HTML text input.

Its Apex class returns a String and accepts the following type-specific parameters:

• maxLength (Integer)
• escapeHtml (Boolean)
• defaultValue (String)

Definition_JS_Constructor__c = cms_ctc.TextInputAttributeDefinition

Apex_Class_Name__c = TextAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.TextInputAttribute

3.9. Single picklist

Presents a single-select picklist as either an HTML select, or a series of HTML radio button inputs.

Its Apex class returns a String and accepts the following type-specific parameters:

• defaultValue (String)

Definition_JS_Constructor__c = cms_ctc.SinglePicklistAttributeDefinition

Apex_Class_Name__c = SinglePicklistAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.SinglePicklistAttribute

3.10. Multi picklist

Presents a multi-select picklist as either a pair of HTML multiple select controls, or a series of HTML checkbox inputs.

Its Apex class returns a String of semicolon-separated options and takes no type-specific parameters.

Definition_JS_Constructor__c = cms_ctc.MultiPicklistAttributeDefinition

Apex_Class_Name__c = MultiPicklistAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.MultiPicklistAttribute

3.11. Taxonomy selector

Presents an OrchestraCMS taxonomy selector control. This does not tag the content, but allows a single tag path to be selected and saved.

It does not have a specialized Apex class.

Definition_JS_Constructor__c = cms_ctc.TaxonomySelectorAttributeDefinition

Editor_JS_Constructor__c = cms_ctc.TaxonomySelectorAttribute