Edit online

Configuring the Proposals for Attribute and Element Values

Oxygen XML includes support for configuring the proposed values that appear in the Content Completion Assistant. To do so, a configuration file is used, along with the associated schema, to add or replace possible values for attributes or elements that are proposed in the Content Completion Assistant.

For an example of a specific use-case, suppose that you want the Content Completion Assistant to propose several possible values for the language code when you use an @xml:lang attribute.

Configuring Proposed Values

For the purposes of adding or replacing the values that are proposed, the configuration file (cc_config.xml) includes a series of valueProposals instructions that will match an element or attribute name and has the following attributes:

path - A path within the document that matches the element or attribute that will have its content completion proposals changed. For example:
- path="title" matches all the <title> elements in the document.
- path="chapter/title" matches only the <title> elements that are direct children of the <chapter> element.
- path="@xml:lang" matches all the @xml:lang attributes in the document.
- path="title/@xml:lang" matches only the @xml:lang attributes that appear on <title> elements.
You can use simplified forms of XPath in this attribute.
editable - Specifies the editable state of the attribute values, as reflected in the Attributes view and the In-place Attributes Editor. The possible values for the @editable attribute are:
- true - The attribute values can be edited by choosing from a combo box or manually providing a value.
- false - The attribute values cannot be edited.
- onlyAllowedItems - The attribute values can be edited, but only by choosing from a list of proposed values, in a non-editable combo box.

The new value proposals are specified in the <valueProposals> element through:

One or more <item> elements, which are grouped inside an <items> element.
Tip:
The <item> element can have a @listValue attribute, which can be set to true if you want those items to be part of a list attribute value (such as attr="item1 item2").
An <xslt> element that references an XSLT script that gets executed and must return an <items> element.

The behavior of the <items> or <xslt> elements are specified with the help of the @action attribute, which can have any of the following values:

append - Adds new values to appear in the proposals list (default value).
addIfEmpty - Adds new values to the proposals list only if no other values are contributed by the schema.
replace - Replaces the values contributed by the schema with new values to appear in the proposals list.

The values in the configuration file can be specified either directly or by calling an external XSLT file that will extract data from an external source. An <xslt> element must be used in this situation.

Note:

valueProposals offers more flexibility compared to the old match element that was marked as deprecated.

<match elementName="lg" elementNS="http://www.oxygenxml.com/ns/samples">
    <items action="replace">
        <item value="stanza"/>
        <item value="refrain"/>
    </items>
</match>

Other Important Notes About the Configuration File

Important:

This configuration file only affects the content completion assistance, not validation.
To test the effects of your changes, you should Refresh the source document.

Example: Specifying Values Directly

If you want to specify the values directly, the configuration file should look like this:

<!-- Replaces the values for an element with the local name "lg",
      from the given namespace -->
<valueProposals path="x:lg" xmlns:x="http://www.oxygenxml.com/ns/samples">
  <items action="replace">
    <item value="stanza"/>
    <item value="refrain"/>
  </items>
</valueProposals>

<!-- Adds two values for an attribute "type", from no namespace -->
<valueProposals path="@type" editable="onlyAllowedItems">
    <items>
        <item value="stanza"/>
        <item value="refrain"/>
    </items>
</valueProposals>

Example: Using Attribute Conditions

The possible values of an attribute depend on the value of another attribute from the same element:

<valueProposals path="property[@name='color']">
  <items>
    <item value="red"/>
    <item value="blue"/>
  </items>
</valueProposals>

<valueProposals path="property[@name='shape']">
  <items>
    <item value="rectangle"/>
    <item value="square"/>
  </items>
</valueProposals>

Example: Calling an External XSLT Script

If you want to collect values from an external XSLT script, the configuration file should include something like this:

<xslt href="../xsl/get_values_from_db.xsl" useCache="false" action="replace"/>

In this example, the get_values_from_db.xsl is executed to extract values from a database.

Tip:

You can use xsl:message as a debugging mechanism. These messages are presented in the results area at the bottom of the application whenever the Content Completion Assistant is invoked.

Note:

A comprehensive XSLT sample is included in the Content Completion Configuration document template (in the Framework Templates > Oxygen Extensions section of the New document wizard New from templates wizard).

Note:

If @useCache is set to false, then the XSLT will be invoked any time the proposals are needed. If @useCache is set to true, then the XSLT is executed once and the obtained proposals are kept in a cache and returned every time the proposals are requested again. You can use the

Validate action to drop the cached values and recompute them.

Configuring Proposed Values in the Context Where the Content Completion was Invoked

Web Author Customization Note:

This particular scenario is not supported for an customization.

A more complex scenario is if you want to choose the possible values to propose, depending on the context of the element where the content completion was invoked.

Suppose that you want to propose certain possible values for one property (for example, color) and other values for another property (for example, shape). If the property represents a color, then the values should represent applicable colors, while if the property represents a shape, then the values should represent applicable shapes. See the following code snippets:

Your main document:

<sampleArticle>
  <!-- The possible values for @value should be "red" and "blue" -->
  <property name="color" value=""/>
  <!-- The possible values for @value should be "square" and "rectangle" -->
  <property name="shape" value=""/>
</sampleArticle>

The content completion configuration file:

<config xmlns="http://www.oxygenxml.com/ns/ccfilter/config">
    <valueProposals path="property/@value">
      <xslt href="get_values.xsl" useCache="false" action="replace"/>
    </valueProposals>
</config>

The stylesheet that defines the possible values based on the context of the property on which the content completion was invoked:

<xsl:stylesheet 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  exclude-result-prefixes="xs"
  version="3.0">
  
  <xsl:param name="documentSystemID" as="xs:string"></xsl:param>
  <xsl:param name="contextElementXPathExpression" as="xs:string"></xsl:param>
  
  <xsl:template name="start">
    <xsl:apply-templates select="doc($documentSystemID)"/>
  </xsl:template>
  
  <xsl:template match="/">
   <xsl:variable name="propertyElement" as="element()">
     <xsl:evaluate xpath="$contextElementXPathExpression" context-item="./*"/>
   </xsl:variable>
    
   <items>
     <xsl:if test="$propertyElement/@name = 'color'">
       <item value='red'/>
       <item value='blue'/>  
     </xsl:if>
     <xsl:if test="$propertyElement/@name = 'shape'">
       <item value='rectangle'/>
       <item value='square'/>  
     </xsl:if>
   </items>
  </xsl:template>
</xsl:stylesheet>

The contextElementXPathExpression parameter will be bound to an XPath expression that identifies the element in the context where the content completion was invoked.