Custom XML Markup

The next example of customer-defined semantics which 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.contoso.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.contoso.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.contoso.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.contoso.com/2006/invoice" w:element="customerName">
  <w:customXmlPr>
    <w:attr w:uri="http://www.contoso.com/2006/invoice" w:name="type" w:val="individual"/>
  </w:customXmlPr>
  <w:r>
    <w:t>Tristan </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 customer-defined 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 customer-defined XML markup, which may or may not be specific to that type of XML in the document. 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 data type, 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.