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 file template that is included in Oxygen XML Editor (File > New > Framework templates > Oxygen Extensions > Content Completion Configuration). The file 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.
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.

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.

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 (such as in 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.
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 - 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, and 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.

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 Refresh (F5) action to test your customizations.
If the framework has an associated styleguide, then the annotations defined in the configuration file will take precedence over those defined in the styleguide. To check to see if your framework uses a styleguide, 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 styleguide, 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 applies to aspects of the Oxygen XML WebApp Component 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>