Developing Editors With the Experience Manager Editor SDK

This chapter covers steps for developing your own editors using the Experience Manager Editor SDK.

As soon as you have set up your development environment, creating and using new editors consists of the following general steps:

  1. Configure external Flex Framework and Experience Manager API dependencies as Runtime Shared Libraries (RSLs).

  2. Build your editor module and copy the SWF file to your <app dir>\config\import\configuration\tools\xmgr\modules directory.

  3. Register your custom editor module and the included editors within your application's editor configuration file.

  4. Upload the editor module and editor configuration file to your deployed application by using the <app dir>\control\set_editors_config script.

  5. Add your editors to an existing cartridge template or create a new cartridge template that includes them.

    Note

    If you make changes to an existing cartridge, any saved cartridges that use the old template are unchanged until you access them in Experience Manager. When accessed, they are updated with default values specified in the cartridge template. For this reason, Oracle does not recommend updating cartridges that are in widespread use throughout your application.

  6. Upload the cartridge template to your deployed application by using the <app dir>\control\set_templates script.

Note

When naming your editors, note that the package names com.xmgr and com.endeca.xmgr are reserved for the Experience Manager product. Do not use them for custom editors.

You must create an editor module to contain your custom editors. Oracle Experience Manager Extensions includes a sample editor module that you can use as a reference.

In order to add your editors to the sample_editors.swf file, you must modify the sample_editors.mxml editor registry to include them.

To create an editor module for custom editors:

  1. Create an MXML registry file for your editor module.

    For the sample editor project, this is editor_sdk\reference\build\maven\src\main\flex\sample_editors.mxml.

  2. Define the editor namespace within a root <editor:EditorModule> element: 

    <editor:EditorModule xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:editor="com.endeca.tools.pagebuilder.editor.*">

</editor:EditorModule>

  3. Within the root <editor:EditorModule> element, add a <editor:registeredEditors> element that contains an <mx:Array>: 

    <editor:EditorModule xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:editor="com.endeca.tools.pagebuilder.editor.*">
  <editor:registeredEditors>
    <mx:Array>
      
    </mx:Array>
  </editor:registeredEditors> 
</editor:EditorModule>

  4. Within the <mx:Array> element, add an <editor:EditorEntry > element for each of your custom editors: 

    <editor:EditorModule xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:editor="com.endeca.tools.pagebuilder.editor.*">
  <editor:registeredEditors>
    <mx:Array>
      <editor:EditorEntry/>
    </mx:Array>
  </editor:registeredEditors> 
</editor:EditorModule>

  5. Specify the following attributes:

    AttributeValue
    uri The editor namespace. This is used in your cartridge templates and in the editor configuration file.
    localName The name to use for the editor in your cartridge templates.
    editor The fully qualified name of your editor.
    <editor:EditorModule xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:editor="com.endeca.tools.pagebuilder.editor.*">
  <editor:registeredEditors>
    <mx:Array>
      <editor:EditorEntry 
        uri="http://endeca.com/sample/2010"
        localName="MyCustomEditor" 
        editor="com.endeca.tools.pagebuilder.samples.editors.MyCustomEditor" />
    </mx:Array>
  </editor:registeredEditors>
</editor:EditorModule>

  6. Repeat Steps 4-5 for each editor you wish to register.

  7. Save and close the file.

  8. Build the editor module.

    For the sample editor module, this consists of the following steps:

    1. Navigate to the %ENDECA_TOOLS_ROOT%\editor_sdk\reference\build\maven directory.

    2. Build the sample editor module using the following command: 

      mvn clean install

      The sample_editors.swf file is output to the target subdirectory.

  9. Upload the editor module to your application:

    1. Navigate to your build output directory.

      For example, %ENDECA_TOOLS_ROOT%\editor_sdk\reference\build\maven\target.

    2. Copy the editor SWF file to the config\import\configuration\tools\xmgr\modules directory of your deployed application.

      If this directory does not exist, you must create it.

    3. Navigate to the control directory of your deployed application.

    4. Run the set_editors_config script.

You must modify the editor configuration file to register new editors with Experience Manager. The file, editors.xml, is maintained in the Endeca Configuration Repository and stored locally within the <app dir>\config\import\configuration\tools\xmgr directory.

Note

The steps below assume a default installation, with Workbench running on port 8006 of your local machine.

To register a custom editor:

  1. Navigate to the <app dir>\config\import\configuration\tools\xmgr directory of your deployed application.

    For the default Discover Electronics reference application, this is C:\Endeca\apps\Discover\config\import\configuration\tools\xmgr on Windows or /usr/local/endeca/apps/Discover/config/import/configuration/tools/xmgr on UNIX.

  2. Open the editors.xml file.

  3. Add an <EditorModule> element within the closing </EditorConfig> tag, and set the url attribute to your custom editor module.

    For example: 

        ...
    <EditorModule url="/ifcr/sites/Discover/configuration/tools/xmgr/modules/sample_editors.swf">
    </EditorModule>
</EditorConfig>

  4. To add additional editors, insert an <Editor> element inside the <EditorModule> element for each new editor that you wish to include.

    For example: 

        ...    
    <EditorModule url="/ifcr/sites/Discover/configuration/tools/xmgr/modules/sample_editors.swf">
        <Editor name="http://endeca.com/sample/2010:RichTextEditor">
        </Editor>
    </EditorModule>
</EditorConfig>

  5. To set default editor configuration, add an <EditorConfig> element within each <Editor> element:

    For example: 

        ...
    <EditorModule url="/ifcr/sites/Discover/configuration/tools/xmgr/modules/sample_editors.swf">
        <Editor name="http://endeca.com/sample/2010:RichTextEditor">
            <EditorConfig sample="customAttribute">
                <ExampleCustomEditorXML foo="bar" size="10" resizeable="false" />
            </EditorConfig>
        </Editor>
    </EditorModule>
</EditorConfig>

  6. Save and close the file.

  7. Navigate to the <app dir>\control directory of your deployed application.

  8. Run the set_editors_config batch or shell script.

    This script uploads the updated editors.xml file and any editor modules in the <app dir>\config\import\configuration\tools\xmgr directory to the Endeca Configuration Repository.

To use your custom editors in Experience Manager, you need to create and upload a cartridge template that includes the new editors. You can choose to create a new cartridge, or to modify an existing cartridge template.

After creating or modifying a cartridge to include your custom editors, you must upload it to your application.. You can accomplish this by moving the template to your deployed application's \config\import\templates directory and running the control\set_templates batch or shell script.

The Experience Manager editor SDK includes a sample RichTextEditor and associated cartridge template that you can use as a reference when developing your own editors.

The source code for the RichTextEditor is available under editor_sdk\reference\build\maven\src\main\flex\com\endeca\tools\pagebuilder\samples\editors\RichTextEditor.mxml.

The Rich Text Box cartridge is provided as a sample cartridge that makes use of the RichTextEditor. The associated cartridge template is included with the Experience Manager Editor SDK.

The cartridge template is available under editor_sdk\reference\cartridge_templates\SampleEditor\template.xml. The cartridge uses a basic StringEditor for the title box, and the RichTextEditor to enter and configure body text: 

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" type="SecondaryContent">
  <Description>Displays rich text.</Description>
    <ThumbnailUrl>/thumbnails/PageTemplate/TextBoxSidebar.png</ThumbnailUrl>
  <ContentItem>
    <Name>New Rich Text Box</Name>
    <Property name="title">
      <String/>
    </Property>
    <Property name="rich_text">
      <String/>
    </Property>
  </ContentItem>

  <EditorPanel>
    <BasicContentItemEditor>
      <StringEditor propertyName="title" label="Title" enabled="true" xmlns="editors"/>
      <!-- default value for the optional height attribute for RichTextEditor is 400px -->
      <!-- make sure not to make it any smaller or it will not render well -->
      <RichTextEditor propertyName="rich_text" xmlns="http://endeca.com/sample/2010" label="Custom Editor" />
    </BasicContentItemEditor>
  </EditorPanel>
</ContentTemplate>

The Experience Manager Editor SDK includes a sample editor module with a Rich Text editor that you can install in your application.

Note

For example purposes this guide assumes that you are extending the default Discover Electronics reference application, with Workbench running on port 8006 of your local machine.

To install the sample editor module and cartridge template:

  1. Create a directory for custom editor modules:

    1. Navigate to the <app dir>\config\import\configuration\tools\xmgr directory.

      For the default Discover Electronics reference application, this is C:\Endeca\apps\Discoverconfig\import\configuration\tools\xmgr on Windows, or /usr/local/endeca/apps/Discover/config/import/configuration/tools/xmgr on UNIX.

    2. Create a modules directory.

  2. Build the sample editor module:

    1. Navigate to the %ENDECA_TOOLS_ROOT%\editor_sdk\reference\build\maven directory.

    2. Build the sample editor module using the following command: 

      mvn clean install

      The sample_editors.swf file is output to the target subdirectory.

    3. Navigate to the %ENDECA_TOOLS_ROOT%\editor_sdk\reference\build\maven\target directory.

    4. Copy the sample_editors.swf file to the <app dir>\config\import\configuration\tools\xmgr directory you created in Step 1.

  3. Register the sample editors:

    1. Open the sample editor configuration file, editor_sdk\reference\editors_config\sample_editors.xml.

    2. Open the editor configuration file for your application.

      For the default Discover Electronics reference application, this is C:\Endeca\apps\Discover\config\import\configuration\tools\xmgr on Windows, or /usr/local/endeca/apps/Discover/config/import/configuration/tools/xmgr on UNIX. .

    3. Copy the <EditorModule> element from the sample_editors.xml file to the editor registry file: 

      <EditorModule url="/ifcr/sites/[site name]/configuration/tools/xmgr/modules/sample_editors.swf">
    <Editor name="http://endeca.com/sample/2010:RichTextEditor">
        <EditorConfig sample="customAttribute">
            <ExampleCustomEditorXML foo="bar" size="10" resizeable="false" />
        </EditorConfig>
    </Editor>
</EditorModule>

      The element should be parallel to the existing <EditorModule> element.

    4. Replace [site name] with the name of your application: 

      <EditorModule url="/ifcr/sites/[site name]/configuration/tools/xmgr/modules/sample_editors.swf">

      For the default Discover Electronics reference application, this is Discover.

    5. Save and close the file.

  4. Upload your custom content:

    1. Navigate to the <app dir>\control directory.

    2. Run the set_editors_config batch or shell script.

      This uploads the sample_editors.swf and editors.xml files to the Endeca Configuration Repository.

  5. Upload a template that includes the custom editor:

    1. Copy editor_sdk\reference\cartridge_templates\SampleEditor directory to your <app dir>\config\import\templates directory.

    2. Navigate to the <app dir>\control directory.

    3. Run the set_templates batch or shell script.

      This uploads the template files to the Endeca Configuration Repository.

If your implementation supports multiple locales, you can localize your custom editors.

You must do the following:

You need to pass a list of locales and a directive to the compiler to retain the declarations of embedded resource bundles to the compiler. The following task uses a POM file for passing this information.

  1. Open the pom.xml file in an editor.

    For the sample editor project, this is under editor_sdk\reference\build\maven

  2. Within the <configuration> element add a <localesCompiled> element with a list of locales: 

    <configuration>
      <localesCompiled>
           <locale>en_US</locale>
           <locale>fr_FR</locale>
           <locale>de_DE</locale>
      </localesCompiled>              
</configuration>

    This example includes US, French, and German locales.

  3. Specify a <keepAs3Metadatas> element to a declare embedded resources bundles. This allows the editor container to detect the embedded resources automatically. 

    <configuration>
      <localesCompiled>
           <locale>en_US</locale>
           <locale>fr_FR</locale>
           <locale>de_DE</locale>
      </localesCompiled>
      <keepAs3Metadatas>
           <keepAs3Metadata>ResourceBundle</keepAs3Metadata>
      </keepAs3Metadatas>              
</configuration>

  4. Save and close the file.

You must create resource property files for each locale for storing localized strings.

Each locale is required to reside in its own directory. The default location is src/main/locales/<locale> where <locale> is the ISO language and region code combination. For example src/main/locales/en_US/com/endeca/tools/pagebuilders/samples/SampleResources.properties indicates that US values are stored in the properties file.

Here is an example of SampleResources.properties file contents: 

editor.sample.message=Enter your message in the following box.

This localized content can be obtained by the custom editor using the getMessage() function to retrieve the string from the properties file. See the following example: 

<ext:Editor>
  <!-- ... -->
  <mx:FormItem id="propertyItem"
      label="{info.templateConfig.@label}"
      labelWidth="135"
      labelStyleName="leftColumnLabel"
      required="false">
    <mx:Label text="{locale.getMessage('editor.sample.message')}" />
    <mx:RichTextEditor id="propertyValueTextInput"
        htmlText="{property.string}"
        change="property.string = propertyValueTextInput.htmlText;"
        borderThickness="3"
        fontFamily="Verdana"/>
  </mx:FormItem>
</ext:Editor>

You must modify your editor module for custom editors to add locale support for to your SWF file.

To modify your editor module:

  1. Open the MXML registry file for your editor module.

    For the sample editor project, open editor_sdk\reference\build\maven\src\main\flex\sample_editors.mxml.

  2. Within the <editor:EditorModule> element, add a <mx:Metadata> declaration of one or more resource bundles to be included in the SWF.

    For example: 

    <editor:EditorModule xmlns:mx="http://www.adobe.com/2006/mxml"
  xmlns:editor="com.endeca.tools.pagebuilder.editor.*">
  <mx:Metadata>
    [ResourceBundle("com.endeca.tools.pagebuilder.samples:SampleResources")]
  </mx:Metadata>
  <editor:registeredEditors>
    <mx:Array>
      <editor:EditorEntry
        uri="http://endeca.com/sample/2010"
        localName="RichTextEditor"
        editor="com.endeca.tools.pagebuilder.samples.editors.RichTextEditor" />
    </mx:Array>
  </editor:registeredEditors>
</editor:EditorModule>

  3. Save and close the file.

  4. Rebuild the editor module.

    For the sample editor module, this consists of the following steps:

    1. Navigate to the %ENDECA_TOOLS_ROOT%\editor_sdk\reference\build\maven directory.

    2. Build the sample editor module using the following command: 

      mvn clean install

      The sample_editors.swf file is output to the target subdirectory.

  5. Upload the editor module to your application:

    1. Navigate to your build output directory.

      For example, %ENDECA_TOOLS_ROOT%\editor_sdk\reference\build\maven\target.

    2. Copy the editor SWF file to the config\import\configuration\tools\xmgr directory of your deployed application.

      If this directory does not exist, you must create it.

    3. Navigate to the control directory of your deployed application.

    4. Run the set_editors_config script.

Copyright © Legal Notices