Documentation Center

Creating a custom Footprint field with a custom input control

If none of the standard controls offered out of the box are suitable for your Footprint, you may choose to implement a custom input control. Use the GUI extension mechanism of SDL Tridion Sites to define, configure and implement your custom input control. Then configure one or more custom Footprint fields that use the control.

Procedure

  1. Implement your custom input control as a JavaScript class that inherits from the class Tridion.Web.UI.Editors.SiteEdit.Controls.FootprintControl. Write an ASCX control to go with it.
  2. If you want, implement the following additional functionality for Footprint fields that use this control:
    Validation

    The base class contains a checkValidation method that applies basic validation and returns a Boolean value indicating that the input was valid (true) or invalid (false). If the return value is false, you can find more information about the nature of the invalidity in the property this.properties.validationResult. The checkValidation method in the base class implements the following validation functionality:

    • If the configuration for the control has an isMandatory element set to true, an empty value results in the return value false.
    • If the configuration for the control has a regExp element that contains a regular expression, any value that does not match the regular expression results in the return value false.

    You can implement checkValidation in your own class to add your own validation business logic to this functionality, or replace it altogether. In that case, you can also set the value of this.properties.validationResult to your own custom invalidity message.

    Getting and setting values
    Implement the setDisplayValue to implement how a value is visualized in your control, and getDisplayValue to implement the retrieval of a value from your control.
    Enabling and disabling the control
    Implement the enableEditing and disableEditing to implement what should happen if the user selects or clears, respectively, the option to overwrite the existing value for the Footprint.
    Event handling
    Implement the addEventHandlers and removeEventHandlers methods to hook into DHTML events that are triggered when the user is changing a Footprint using the control.
  3. Read the documentation about building a GUI extension, noting the following differences:
    • When you configure your extension, set the target attribute of your ext:editorextension element to the value SiteEdit, and not to CME.
    • Inside the ext:editorextension section, create a subelement called <ext:deckpages>. The various Footprints are implemented as the pages of a 'deck', a list of screens of which only one is showing at any one time.
  4. Create the following <ext:deckpages> section:
    <ext:deckpages>
    	<ext:add>
    		<ext:extension assignid="myFootprint" name="myFootprint">
    			<ext:control>~/Controls/Footprints/MyFootprint.ascx</ext:control>
    			<ext:pagetype>CustomFootprint</ext:pagetype>
    			<ext:apply>
    				<ext:view name="FootprintSettings">
    					<ext:control id="FootprintEditors" />
    				</ext:view>
    			</ext:apply>
    		</ext:extension>
    	</ext:add>
    </ext:deckpages>

    In this fragment, MyFootprint.ascx is the ASCX control you built.

    You have now created a custom input control. Your next step is to configure one or more custom Footprint fields that use the control. You do this in the configuration file.
  5. On your Content Manager server, access %TRIDION_HOME%.
  6. Navigate to the subfolder web\WebUI\Models\SiteEdit\Configuration\.
  7. As a precaution, back up the file SiteEditModel.config.
  8. Open the file SiteEditModel.config in a plain-text or XML editor.
  9. Find the customconfiguration section. This section has a subsection called clientconfiguration, which in turn contains a footprints subsection.
    You see the list of footprint elements that represent the Footprints which are currently displayed in the Footprint Set dialogs.
  10. Insert a new footprint element for the custom Footprint field you want to configure, and give it the following attributes:
    ID
    a unique string that identifies this Footprint
    ClaimUri

    the URI of a Claim associated with this Footprint, for example:

    taf:claim:foo
  11. Insert a <title> section inside your new footprint element.
  12. For each language that your installation of SDL Tridion Sites supports, insert a value element inside the title element, and give it a lang attribute set to the four-digit Microsoft locale ID belonging to that language:
    • 1031 for German
    • 1033 for US English
    • 1036 for French
    • 1041 for Japanese
    • 1043 for Dutch
    • 3082 for Spanish
  13. Set the contents of each value element to the localized name of this Footprint, as you want it to appear in the Footprint Settings dialog.
  14. Also insert a value element without a lang attribute. This is used as a fallback if the language is none of the above. (If you do not insert such a value element, the value of the ID attribute of the parent footprint element is displayed.)
    You have now configured a title for your Footprint.
  15. If you want, you can also write a description for your Footprint. The description appears under the title in the content area on the right if the user selects this Footprint. To create a Footprint description, insert a <description> section inside your new footprint element, directly under the <title> section.
  16. For each language that your installation of SDL Tridion Sites supports, insert a value element inside the description element, and give it a lang attribute set to the four-digit Microsoft locale ID belonging to that language.
  17. Set the contents of each value element to the localized description of this Footprint, as you want it to appear in the Footprint Settings dialog.
  18. Also insert a value element without a lang attribute. This is used as a fallback if the language is none of the above. (If you do not insert such a value element, an empty string is displayed.)
    You have now configured a description for your Footprint.
  19. If you want to disallow empty values for this field, insert a <settings> section inside your new footprint element, and inside it, insert an <isMandatory> element containing the value true.
  20. If the input values for this field need to match a regular expression, specify that regular expression for the field in the form of a regExp element inside the <settings> section (create this section if you have not done so yet). Set the value of regExp to the regular expression that the input value should match. For example, to match only uppercase and lowercase letters, set regExp to ^[A-Za-z]+$.
  21. If you implemented the control to recognize and handle a default value, specify a default value for the Footprint.

    To specify a default value, insert a <values> section inside the footprint element. Inside <values>, create a value element with the following attributes:

    text
    The value of the field, as it will be submitted. Set this attribute to the empty string (text="") to make the empty value default.
    default
    Set this attribute to true.
  22. For each language that your installation of SDL Tridion Sites supports, insert a label element inside the value element, and give it a lang attribute set to the four-digit Microsoft locale ID belonging to that language.
  23. Set the contents of the label element to the localized text that you want to use to represent the value. For example, if the value refers to the African continent, and the label has a lang attribute set to "1036" (France), then the contents of label would be Afrique.
  24. Also insert a label element without a lang attribute. This is used as a fallback if the language is none of the above. (If you do not insert such a label element, the value of the text attribute of the parent value element is displayed.)
    You have now configured a default value for your control.
  25. If the input value for this field needs to be one of a closed to a set values, add a value element for each of the allowed values, specifying a text attribute and a set of label subelements, as you did for the default value. (For these new elements, omit the default attribute.)
  26. If you want, repeat steps 9-24 to configure further custom Footprint fields that use the same input control.
  27. Save and close SiteEditModel.config.
  28. Navigate to the subfolder web\WebUI\Editors\SiteEdit\Configuration\.
  29. As a precaution, back up the file SiteEditEditor.config.
  30. Open SiteEditEditor.config.
  31. Find the customconfiguration section. This section has a subsection called clientconfiguration, which in turn contains a footprints subsection.
    You see the list of footprint elements that represent the Footprints which are currently displayed in the Footprint Set dialogs.
  32. Create an icon for the custom Footprint in the form of a set of PNG files named footprint.<iconname>.16x16.png (16 by 16 pixels), footprint.<iconname>.24x24.png (24 by 24 pixels), footprint.<iconname>.32x32.png (32 by 32 pixels) and footprint.<iconname>.48x48.png (48 by 48 pixes), where <iconname> is a name for your icon. Save these files in the folder %TRIDION_HOME%\web\WebUI\Editors\SiteEdit\Themes\Carbon\Images\Icons\.
  33. Add a new footprint element with the following attributes:
    ID
    The identifier of the Footprint, as set in SiteEditModel.config.
    ControlID
    The ID of the custom control, as set in your Editor extension.
    Icon
    The name you provided for the icon (<iconname>).
  34. Repeat this step for each new Footprint you configured in SiteEditModel.config.
  35. Save and close SiteEditEditor.config.
  36. In the cd_ambient_conf.xml Ambient Data Framework configuration file, add a new Claim element in the GloballyAcceptedClaims section and set its Uri attribute to the Claim URI of your new Claim.