L.1.6.2 Custom XML Markup

The next form of extra-standard semantics that can be embedded in a WordprocessingML document is custom XML markup. Custom XML markup allows the application of the XML elements defined in any valid XML Schema file to be applied to the contents of a WordprocessingML document in one of two locations: around a paragraph or set of paragraphs (at the block level); or around an arbitrary run or set of runs within a document (at the inline level) to provide semantics to that content within the context and structures defined by the associated XML Schema definition file.

The distinction between custom XML markup and smart tags is based on the fact that custom XML markup corresponds with the contents of a custom XML schema; which means that as shown below, custom XML markup can be used at the block-level to mark up the contents of a document on levels beyond that of one or more runs as well as on the inline (run) level. It can also be validated against a custom XML schema by a producer at run time.

Consider a simple XML Schema which defines two elements: a root element of invoice, and a child element of customerName - the first defining that this file’s contents are an invoice, and the second specifying that the enclosed text as a customer’s name:

This output would translate to the following WordprocessingML markup:

<w:customXml w:uri="http://www.example.com/2006/invoice"
w:element="invoice">
  <w:p>
    <w:r>
      <w:t>This is an invoice.</w:t>
    </w:r>
  </w:p>
  <w:p>
    <w:r>
      <w:t xml:space="preserve">And this is a customer name: </w:t>
    </w:r>
    <w:customXml w:uri="http://www.example.com/2006/invoice"
w:element="customerName">
      <w:r>
        <w:t>Tristan Davis</w:t>
      </w:r>
    </w:customXml>
  </w:p>
</w:customXml>

As shown above, each of the XML elements from the customer-supplied XML schema is represented within the document output as a customXml element.

Similar to the smart tag example above, a custom XML element in a document has two required attributes.

The first is the uri attribute, whose contents specify the namespace of the custom XML element in the document. In the example above, the elements each belong to the http://www.example.com/2006/invoice namespace.

The second is the element attribute, whose contents specify the name of the custom XML element at this location in the document. In the example above, the root element is called invoice and the child element is called customerName.

As well as the required information specified above, custom XML elements can also specify any number of attributes (as specified in the associated XML Schema) on the element. To add this information, the customXmlPr (properties on the custom XML element) specify one or more attr elements.

Using the example above, we can add a type attribute to the customerName element as follows:

<w:customXml w:uri="http://www.example.com/2006/invoice"
w:element="customerName">
  <w:customXmlPr>
    <w:attr w:uri="http://www.example.com/2006/invoice" w:name="type"
w:val="individual"/>
  </w:customXmlPr>
  <w:r>
    <w:t>Tristan Davis</w:t>
  </w:r>
</w:customXml>

The resulting XML, as seen above, simply adds an attr element which specifies the attribute for the custom XML element.

A producer can embed a custom XML element around or with block-level or run-level content in a WordprocessingML document in order to embed the structure of the extra-standard XML Schema within the WordprocessingML content. This allows ‘tagging’ of specific regions of a document with the semantics from this schema, while ensuring that the resulting file can be validated to the WordprocessingML schemas.

A consumer can read this custom XML markup and provide additional functionality around this extra- standard XML markup, which might or might not be specific to that particular XML namespace. Examples of this functionality include: the ability to add/remove this XML markup via a user interface, ability to provide actions to operating in the context of this namespace, etc.

Each custom XML element is analogous to an XML element in the specified XML schema, and can be nested arbitrarily to any depth in the document. This facility is limited only by the XML Schema file itself, and the contents of the current document.