Edit online

Customizing the Rendering of Elements

In addition to the support for configuring the proposals that appear in the Content Completion Assistant, Oxygen XML Editor also includes support for customizing how the elements are rendered. You can do this by using the XMLNodeRendererCustomizer API extension, but you can also use the same configuration file that is used to configure the content completion proposals.

For an example of a specific use-case, suppose that in DITA you want the names of paragraph elements (<p>) to be rendered as "Paragraph" instead of "p" in the various components in Author mode (such as in the Outline view, Elements view, Attributes view, and the breadcrumb navigation bar). To achieve this, you can use the <elementRenderings> element in the configuration file.

Setting up the Content Completion Configuration File

To customize the configuration file for the Content Completion Assistant, follow these steps:

Create a new resources folder (if it does not already exist) in the frameworks directory for the particular document type (for example, OXYGEN_INSTALL_DIR/frameworks/dita/resources).
Open the Preferences dialog box (Options > Preferences) and go to Document Type Association. Select the particular document type, click the Edit button, and in the Classpath tab add a link to that resources folder (if it does not already exist).
Create a new configuration file or edit an existing one.
1. To easily create a new configuration file, you can use the Content Completion Configuration document template that is included in Oxygen XML Editor (File > New > Framework templates > Oxygen Extensions > Content Completion Configuration). The document template includes details about how each element and attribute is used in the configuration file.
2. If a configuration file (cc_config.xml) already exists for the particular document type (in the resources folder), you can modify this existing file.
3. If you extend a framework, you need to copy the content of the cc_config.xml file from the base framework and modify it (e.g. create a resources folder in your framework extension folder and place the file there). You also need to make sure that the folder that contains the cc_config.xml file in your extension (e.g. resources) is listed in the Classpath tab before the one from the base framework.
  
  If you only want to make small changes or add extra rules in your custom content completion configuration file, you need to name it cc_config_ext.xml and all the rules inside it are merged with the base cc_config.xml file. The merging is done by taking all the rules specified in the cc_config_ext.xml file into consideration after processing the set of rules from the base cc_config.xml file.
Make the appropriate changes to your custom configuration file.
Save the file in the resources folder for the particular document type, using the fixed name: cc_config.xml (for example, OXYGEN_INSTALL_DIR/frameworks/dita/resources/cc_config.xml).
Restart the application and open an XML document. In the Content Completion Assistant you should see your customizations.
Tip: In some cases, you can simply use the Refresh (F5) action to test your customizations, without having to restart the application.
Attention: In the Classpath tab, if you have references to multiple resources folders, each with its own cc_config.xml file, the first reference listed in the Classpath tab takes precedence and the multiple configuration files are not combined.

Changing the Rendering of Elements (Their Names, Annotations, and Icons)

For the purposes of customizing how the content completion elements are rendered, you can use the <render> element inside a <elementRenderings> element to specify how element names, their annotations, and their icons are rendered.

The <elementRenderings> element supports the @platform attribute, which can have one of the following values:

webapp: The element renderings are only applied to Oxygen XML Web Author.
standalone: The element renderings are only applied to standalone distributions of Oxygen.
eclipse: The element renderings are only applied to Eclipse plugin distributions of Oxygen.
Note: If the @platform attribute is missing, the element renderings are applied to all types of distributions.

You can use the following attributes for the <render> element:

element

Identifies the element to be customized, in the form of a qualified name. If it does not have a prefix, it is considered to be from noNamespace.

as

Provides the name (label) that will be displayed for the element in various components in Author mode (the Content Completion Assistant, the breadcrumb navigation bar, the Full Tags display mode, and the Outline, Elements, and Attributes views). This attribute is optional. If it is missing, the name of the element is used.

If you want to translate this label into another language, use the ${i18n(key_name)} editor variable. The following code snippet shows how the DITA paragraph elements (<p>) can be translated:

<elementRenderings>
    <render element="p" as="${i18n(cc_p)}"/>
</elementRenderings>

Note: The cc_p id is a key that identifies the translations available for the paragraph element.

iconPath

Optional attribute that specifies the icon for the element. This is shown in the Content Completion Assistant and the Outline view in Author mode. If it is a relative path, the full path of the icon image file will be computed starting from the directory of the configuration file (for example, a value of "myImg.png" will cause Oxygen XML Editor to load "frameworks/$ {framework}/resources/myImg.png"). If you want to access a built-in resource, the value can begin with a forward slash "/", and the image file will be searched for in the Oxygen XML Editor classpath resources (for example,"/images/OrderedList16.png" will load an icon from the built-in Oxygen XML Editor JAR file resources.

xml:lang (Deprecated)

It is recommended to use the ${i18n(key_name)} editor variable instead. Optional attribute that could be used to render the same element differently, depending on the language. If there are multiple <render> elements for the same @element attribute (element name) and the @xml:lang attribute is missing on one of them, that one will be considered the default fallback value to be used if none of the others match the language specified in the interface.

Note: The default entry should be listed first, since the application tries to match them in sequence and the last match found is the one that is used.

For example, suppose that you want the name of DITA paragraph elements (<p>) to be rendered as "Paragraphe" if the language is French, "Absatz" if the language is German, and "Paragraph" if the language is English (or any other language). Your configuration file should look something like this:

<elementRenderings>
    <render element="p" as="Paragraph"/>
    <render element="p" as="Paragraphe" xml:lang="fr"/>
    <render element="p" as="Absatz" xml:lang="de"/>
</elementRenderings>

You can also use the configuration file to customize the annotations for elements. For this purpose, the <render> element also accepts the following element to change the tooltip annotations for an element (in both Author mode and Text mode):

annotation

This element can be used within the <render> element to customize the tooltip annotations that are displayed for the element in various components in Author mode (such as tooltips shown in the Content Completion Assistant documentation window, the breadcrumb navigation bar, the Full Tags display mode, and the Outline, Elements, Attributes views), as well as the tooltips that are displayed when you hover over elements in Text mode. You can use HTML content to style the annotations (see the example below).

Note: If this element is missing, the styling for the annotations for that element is collected from the associated schema.

Tip: The annotations can also be translated in the configuration file. For example:

<elementRenderings>
    <render element="p" as="${i18n(cc_p)}">
        <annotation>${i18n(cc_p)}</annotation>
    </render>
</elementRenderings>

Other Important Notes About the Configuration File for Rendering Elements

Important:

This configuration file only affects the content completion assistance, not validation.
To test the effects of your changes, you should restart the application, although in some cases, you can simply use the Reload (F5) action to test your customizations.
If the framework has an associated style guide, then the annotations defined in the configuration file will take precedence over those defined in the style guide. To check to see if your framework uses a style guide, look for the following folder: ${oXygenInstallDir}frameworks/${framework}/styleguide/. If that folder exists, it is recommended that you make your annotation changes directly in the style guide, rather than in the configuration file.
If an XMLNodeRendererCustomizer API extension has been implemented for the framework and a configuration file is also used, the rendering customization for an element will be the result of merging the two. For example, if the XMLNodeRendererCustomizer implementation customizes the element name, while the configuration file specifies an icon for the element, the properties of both customizations will be rendered. However, if both implementations define the same property (for example, both specify the rendering of an element name), the customizations defined in the configuration file take precedence.
The rendering customizations defined in the configuration file also apply to aspects of the Oxygen XML Web Author interface.

Example: Changing the Rendering of an Element

Suppose that you want to render the name of the DITA <title> element to begin with a capital letter, use a custom icon for it, and provide specific documentation for that element in the various components in Author mode. The configuration file should look like this:

<elementRenderings>
   <render element="title"   as="Title"  iconPath="cimg/AcceptAll16.png">
      <annotation>
         <html xmlns="http://www.w3.org/1999/xhtml">
           <head>
             <title>Documentation for the Title Element</title>
           </head>
             <body>
           <p>A <i>heading</i> or <b>label</b> for the main parts of a topic</p>
             </body>
         </html>
             </annotation>
   </render>
</elementRenderings>