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 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.

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 .
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 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 classpath resources (for example,"/images/OrderedList16.png" will load an icon from the built-in Oxygen XML 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 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>