Office Open XML
17 WordprocessingML Reference Material
17.5 Custom Markup
17.5.1 Custom XML and Smart Tags

17.5.1 Custom XML and Smart Tags

The first form of extra-standard semantics that can be embedded in a WordprocessingML document is represented by smart tags. Implementations can establish sets of smart tags that allow semantic labels to be added around an arbitrary run or set of runs within a document to provide information about the type of data contained within.

[Example: Consider the following text in a WordprocessingML document, with a smart tag around the stock symbol ‘CNTS’:

This is a stock symbol: CNTS

This text would translate to the following WordprocessingML markup:

<w:p w:rsidR="00672474" w:rsidRDefault="00672474">
  <w:r>
    <w:t xml:space="preserve">This is a stock symbol: </w:t>
  </w:r>
  <w:smartTag w:uri="http://www.example.com"
      w:element="stockticker">
    <w:r>
        <w:t>CNTS</w:t>
    </w:r>
  </w:smartTag>
</w:p>

As shown above, the smart tag is delimited by the smartTag element, which surrounds the run (or runs) which contain the text which is part of the smart tag. end example]

The smartTag element has two required attributes:

  • The uri attribute is used to specify the namespace, in terms of a vocabulary or classification scheme, of
  • which the term specified for this smart tag is a member. [Example: In the above example, the smart tag
  • specifies http://www.example.com to identify the classification scheme. end example]
  • The element attribute, in combination with the uri attribute, specifies the classification for this smart
  • tag. [Example: In the above example, the smart tag specifies the classification term stockticker from
  • the identified namespace. end example]

The second 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 schema syntax (XML Schema, NVDL, etc.) to be applied to the contents of a WordprocessingML document in two types of location: 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 schema definition.

The distinction between custom XML markup and smart tags is that custom XML markup is based on a schema, which may be specified using the attachedSchema element (17.15.1.5). As a result, the custom XML elements can be validated against the schema. Also, as shown below, custom XML markup can be used at the block-level as well as on the inline (run) level.

[Example: 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:

image

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 supplied XML schema is represented within the document output as a customXml element. end example]

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.

[Example: 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. end example]…

Subsections

Last updated on