QR code for this page

Powered by Titania Delivery

Configuring the Proposals for Elements

There are many cases where elements have a relaxed content model and can accept a large number of child elements. For example, the DITA list item element (li) accepts more than 60 child elements. Oxygen XML Editor includes support to allow the content architect to put some constraints on the possible elements or attributes, or to impose some best practices in the way content is edited.

For an example of a specific use-case, suppose that you want restrict DITA list item elements (li) to only accept paragraph elements (p). In this case, the Content Completion Assistant should not offer any element other than a paragraph (p) when a list item (li) is inserted into a document. It would also be helpful if the required child element (p) was automatically inserted whenever a list item (li) is inserted.

One method of changing the content model is to alter the element definition in the associated schema (XML Schema, DTD, RelaxNG), but this may be quite complicated in some cases. Fortunately, Oxygen XML Editor offers a simple, alternative method of using a configuration file to customize the content completion proposals for each element.

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

Configuring Elements or Attributes that are Proposed for Each Element

For the purposes of customizing the elements or attributes that are proposed for each individual element, the configuration file (cc_config.xml) uses elementProposals elements. This element allows you to customize or filter the child elements and attributes for an element.

Elements:

To control the elements that are proposed for an element, you can use the following attributes for the elementProposals element:

  • path - A path within the document that matches the element that will have its content completion proposals changed. For example, "title" matches all the title elements in the document, while "chapter/title" matches only the title elements that are direct children of the chapter element. You can use simplified forms of XPath in this attribute.

    The XPath expressions can accept multiple attribute conditions and inside each condition you can use AND/OR boolean operators and parentheses to override the priority.

    You can use one or more of the following attribute conditions (default attribute values are not taken into account):

    • element[@attr] - Matches all instances of the specified element that include the specified attribute.
    • element[not(@attr)] - Matches all instances of the specified element that do not include the specified attribute.
    • element[@attr = "value"] - Matches all instances of the specified element that include the specified attribute with the given value.
    • element[@attr != "value"] - Matches all instances of the specified element that include the specified attribute and its value is different than the one given.

    Example: The following is an example of how you could use multiple boolean operators and parentheses inside an attribute condition: 

    *[@a and @b or @c and @d]
*[@a and (@b or @c) and @d]

    The following are just examples of how simplified XPath expressions might look like:

    • elementName
    • //elementName
    • /elementName1/elementName2/elementName3
    • //xs:localName Note: Using a namespace prefix requires that you declare it in the configuration file. For example: <elementProposals xmlns:db5="http://docbook.org/ns/docbook" path="db5:listitem" insertElements="db5:para" />
    • //xs:documentation[@lang="en"]

    Note

    If the path attribute is missing, the customization will apply to the proposals for all elements. You can intentionally omit this attribute and use possibleElements or rejectElements to specify or restrict elements for an entire framework.

    For example, suppose that in your DITA documents, you want to restrict your users from using image elements (image) because you do not want images to be included in your output. The configuration file should look like this:

    <elementProposals rejectElements="image" />

    Since the path attribute is missing, the specified element will be filtered out from the proposals for the entire framework.

  • insertElements - A space-separated sequence of child element names. Each time the element specified in the path attribute is inserted into the document, these child elements will also be inserted in the order that they are listed. For example, insertElements="b i" will insert exactly one b element, followed by an i element. An empty value ("") means that no child elements should be inserted.

    Note

    If this attribute is missing, the default required child elements will be inserted, as specified in the associated schema for the document.
  • possibleElements - A space-separated list of element names that will be shown in the content completion list when invoked inside an element that is specified in the path attribute. For example, "bold italic codeph ph" means that the Content Completion Assistant will contain these four elements when invoked on the element specified in the path attribute. The following other possible values are also supported:
    • NONE - There will be no proposals in the content completion list.
    • ALL - All the possible elements specified in the associated schema will be presented in the content completion list. This is also the default behavior if this attribute is missing.
    • INSERTED - The proposals will be the same list of elements that are defined in the insertElements attribute.
  • rejectElements - A space-separated list of element names that will be filtered out from the list of proposals that are presented in the content completion list. Each time the element specified in the path attribute is inserted into the document, the list of proposals in the Content Completion Assistant will include the entries that are defined in the associated schema, minus the elements specified in this attribute.

Attributes:

To control the attributes that are proposed for an element, you can use the following attributes for the elementProposals element:

  • path - A path within the document that matches the element that will have its attribute proposals changed. For example, "title" matches all the title elements in the document, while "chapter/title" matches only the title elements that are direct children of the chapter element. You can use simplified forms of XPath in this attribute. For examples of such forms of XPath expressions, see the note in XML Preferences.

    Note

    If this attribute is missing, the customization will apply to the proposals for all elements. You can intentionally omit this attribute and use possibleAttributes or rejectAttributes to specify or restrict attributes for an entire framework.

    For example, suppose that you only want to allow a limited set of attributes in a customized framework. The configuration file should look like this: 

    <elementProposals possibleAttributes="
               id domains href scope format type conref 
        	props keyref class"/>

    Since the path attribute is missing, this applies to the entire framework and only the specified attributes will be proposed.

  • insertAttributes - A space-separated sequence of attribute names that will be inserted along with the element.
  • possibleAttributes - A space-separated list of attribute names that will be shown in the content completion list when invoked inside an element that is specified in the path attribute.
  • rejectAttributes - A space-separated list of attribute names that will be filtered out from the list of proposals that are presented in the content completion list. Each time the element specified in the path attribute is inserted into the document, the list of proposals in the Content Completion Assistant will include the entries that are defined in the associated schema, minus the attributes specified in this attribute.

Other Important Notes About the Configuration File

Important

  • By default, the element names that do not have a namespace prefix are considered from no-namespace. Consider declaring the namespace mapping on the root of the configuration file and prefixing the element names from the elementPath and model attributes.
  • 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.
  • When an XML element from the document is matched against a list of configured elementProposals, the first one in sequence takes precedence. Therefore, make sure you place the more specific elementProposals (those with a longer path) first in your configuration file.
  • Regular expression patterns can be used in the following attributes: possibleElements, rejectElements, possibleAttributes, and rejectAttributes. For example, code*, *block, con*ref, _*.
  • Only simple recursion cases are detected and avoided by the editor, and logged to the console. Therefore, if complex elementProposals patterns are defined, you should avoid infinite recursions.

Examples: Configuring the Element Proposals

  • Example 1: Automatically Insert Elements

    Suppose that you want to automatically insert a paragraph element (p) whenever a DITA ordered list item element (ol/li) is inserted, and also to not allow any other element besides a paragraph inside the ordered list items.

    To achieve this, the configuration file should include the following:

    <elementProposals path="ol/li" insertElements="p"  
       possibleElements="_INSERTED_"/>

  • Example 2: Insert Complex Element Structure

    For a more complex example, suppose that you want to insert a complex structure whenever a DITA prolog element is inserted.

    For instance, if you need to insert the following structure inside prolog elements:

        <prolog>
      <author></author>
      <metadata>
          <keywords>
              <keyword></keyword>
              <keyword></keyword>
          </keywords>
      </metadata>
    </prolog>

    The configuration file should include the following:

        <elementProposals path="prolog" insertElements="author metadata"/>
    <elementProposals path="prolog/metadata" insertElements="keywords"/>
    <elementProposals path="prolog/metadata/keywords" 
           insertElements="keyword, keyword"/>

  • Example 3: Limit Possible Elements

    Suppose that you also want to limit the proposals for the keywords element to only allow the user to insert audience or keyword elements. The configuration file should include the following:

    <elementProposals path="prolog/metadata" insertElements="keywords" 
           possibleElements="audience keywords"/>

    Suppose that you want to simply restrict your users from inserting image elements inside DITA list item elements (li), but still propose all the other elements that are defined in the associated schema. The configuration file should look like this:

    <elementProposals path="li" rejectElements="image" />

Examples: Configuring the Attributes Proposals

  • Example 1: Automatically Insert Attributes

    Suppose that you want to insert an id attribute (with an empty value) whenever a DITA list item element (li) is inserted. The configuration file should include the following:

    <elementProposals path="li" insertAttributes="id"/>

  • Example 2: Limit Possible Attributes

    Suppose that you also want to limit the number of choices for attributes that are presented to the user whenever a DITA list item element (li) is inserted. The configuration file should look like this:

    <elementProposals path="li" insertAttributes="id" 
          possibleAttributes="id product platform audience"/>

    Suppose that you want to simply restrict your users from inserting conref attributes inside DITA topics (topic element), but still propose all the other attributes that are defined in the associated schema. The configuration file should look like this:

    <elementProposals path="topic" rejectAttributes="conref" />

Related information:

Configuring the Proposals for Attribute and Element Values
Customizing the Rendering of Elements
Parent topic: Customizing the Content Completion Assistant

Was this helpful?