Customizing the Rendering of Elements

Setting up the Content Completion Configuration File

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

1. 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).
2. Open the Preferences dialog box 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).
3. 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 Author plugin (File ⇒ New ⇒ New from Templates ⇒ 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.
4. Make the appropriate changes to your custom configuration file.
5. 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).
6. 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 Author plugin 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 Author plugin classpath resources (for example,"/images/OrderedList16.png" will load an icon from the built-in Oxygen XML Author plugin 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

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>