Configuring the Proposals for Elements and Attributes

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 Author Eclipse plugin 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 to restrict DITA list item elements (<li>) to only accept paragraph elements (). In this case, the Content Completion Assistant should not offer any element other than a paragraph () when a list item (<li>) is inserted into a document. It would also be helpful if the required child element () 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 complicated in some cases. Fortunately, Oxygen XML Author Eclipse plugin 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:

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 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 Author Eclipse plugin (File > New > New from Templates > 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.

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.

Warning: Note that you can only choose elements or attributes that are already allowed by the schema in a particular context. For example, you cannot specify an element that is not allowed by the schema as a child of a particular node.

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 are examples 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
- //xs:documentation[@lang="en"]
Note: Using a namespace prefix requires that you declare it on the <elementProposals> element or on an ancestor element. For example:
```
<elementProposals xmlns:db5="http://docbook.org/ns/docbook"
 path="db5:listitem" insertElements="db5:para" />
```
Other Important Notes:
- 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 particular elements for a framework.
 For example, suppose that in your DITA documents, you want to restrict your users from using <image> and <fig> elements because you do not want images to be included in your output. The configuration file should look like this:
 <elementProposals rejectElements="image fig" />
 Since the @path attribute is missing, the specified element will be filtered out from the proposals for the entire framework.
- If the particular document type has name namespaces, the @path should contain the qualified name. For example, in TEI documents, if you want to set a list of possible attributes for the  element, you need to use a qualified name like this (notice the declaration of the namespace prefix "t" and its usage):
```
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.oxygenxml.com/ns/ccfilter/config 
 http://www.oxygenxml.com/ns/ccfilter/config/ccConfigSchemaFilter.xsd"
 xmlns="http://www.oxygenxml.com/ns/ccfilter/config"
 xmlns:t="http://www.tei-c.org/ns/1.0">
 
 <elementProposals path="t:span" possibleAttributes="type"/>
```
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  element, followed by an  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, "b i 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.
When using this attribute to specify multiple elements, only use one entry with the element names separated by a space:
```
<elementProposals possibleElements="b i codeph ph" />
```
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.

Note:
This setting makes the application behave as if the rejected elements were not allowed by the schema in that location. Most of the toolbar actions take the schema into account when inserting content. If the inserted content is not allowed by the schema in that particular location, the application tries to find another location within close proximity where the content is allowed.

For example, suppose you reject the insertions of images in paragraphs. If a user has the cursor inside a paragraph and uses the toolbar action that inserts an image, the image will be inserted after the current paragraph rather than at the current location.

If you want to avoid having users insert an element directly from the content completion mechanism and want them to use a toolbar action instead, it is better to use the Document Type Configuration dialog box to remove the element.
When using this attribute to specify multiple elements, only use one entry with the element names separated by a space:
```
<elementProposals rejectElements="image fig imagemap foreign" />
```
contentType - Forces an element to have an imposed content type. The possible values are: elementOnly, mixed, or empty.
```
<elementProposals path="section" insertElements="title p" contentType="elementOnly"/>
```
merge - By default, if there are multiple element proposal rules that match the current element context, then only the rule that has the most specific path is used. By setting the @merge attribute to true on the proposal rules that might match the same element context, all the rules will be applied. Example:
```
 <elementProposals
 path="/*[not(@xml:lang='ja')]//*"
 rejectElements="japaneseTag"
 merge="true"/>

 <elementProposals
 path="/*[@xml:lang!='he']//*"
 rejectElements="hebrewTag"
 merge="true"
 />
```

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.
```
<elementProposals path="ol/li" insertAttributes="product platform"/>
```
insertAttribute - This is similar to the preceding attribute, but this one also allows you to specify a value for the attribute that will be inserted. This attribute should be used like this:
```
<elementProposals path="ol/li">
 <insertAttribute name="platform" value="test"/>
</elementProposals>
```
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.
When using this attribute to specify multiple attributes, only use one entry with the attribute names separated by a space:
```
<elementProposals possibleAttributes="scope format type"/>
```
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.
When using this attribute to specify multiple attributes, only use one entry with the attribute names separated by a space:
```
<elementProposals rejectAttributes="importance platform product"/>
```

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. It has no effect on validation or operations invoked from other areas in the interface (such as the toolbar or menus).
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.
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.
Simple wildcard patterns can be used in the following attributes: @possibleElements, @rejectElements, @possibleAttributes, and @rejectAttributes. For example, code*, *block, con*ref, _*.

Editor variables can be used in the @value attribute of the <insertAttribute> element. For example:

<elementProposals path="prolog/critdates/created">
    <insertAttribute name="date" value="${date(yyyy-MM-dd)}"/>
</elementProposals>

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 () 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_"/>
```
Tip: This particular example modifies an action that inserts a list in a DITA document. There are several ways to invoke this action in the interface. For example, there is a toolbar button and an action in the DITA menu that inserts a list. However, since the configuration file only affects the Content Completion Assistant, this modification will have no effect on the behavior of the toolbar or menu action. Those actions would need to be configured separately if you want the result to be the same as the content completion proposal. For more information, see Customizing the Author Mode Editing Experience for a Framework.

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 want 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" />
```