DocumentID: ECMA-376/Part3/2.6.3 Title: ECMA-376, Part3: 2.6.3 Structured Document Tags Extracted-From: ECMA-376 Office Open XML File Formats, 1st Edition / December 2006 Warning: Coverted to HTML format by a script known to have bugs
The final example of customer-defined semantics which can be embedded in a WordprocessingML document is the structured document tag (SDT).
As shown above, smart tags and custom XML markup each provide a facility for embedding customer-defined semantics into the document: smart tags, via the ability to provide a basic namespace/name for a run or set of runs within a documents; and custom XML markup, via the ability to tag the document with XML elements and attributes specified by any valid XML Schema file.
However, each of these techniques, while they each provide a way to add the desired semantic information, does not provide a way to affect the presentation or interaction within the document. To bridge these two worlds, structured document tags allow both the specification of customer semantics as well as the ability to influence the presentation of that data in the document.
This means that the customer can define the semantics and context of the tag, but can then use a rich set of pre-defined properties to define its behavior and appearance within the WordprocessingML document's presentation.
Consider a region which should be tagged with the semantic of "birthday", for the user to enter their date or birth into the document. Ideally, this region would also utilize a date picker to allow the user to enter the date from a calendar::
This content would translate to the following WordprocessingML markup:
<w:sdt>
<w:sdtPr>
<w:alias w:val="Birthday"/>
<w:id w:val="8775518"/>
<w:placeholder>
<w:docPart w:val="DefaultPlaceholder_22479095"/>
</w:placeholder>
<w:showingPlcHdr/>
<w:date>
<w:dateFormat w:val="M/d/yyyy"/>
<w:lid w:val="EN-US"/>
</w:date>
</w:sdtPr>
<w:sdtContent>
<w:p>
<w:r>
<w:rPr>
<w:rStyle w:val="PlaceholderText"/>
</w:rPr>
<w:t>Click here to enter a date...</w:t>
</w:r>
</w:p>
</w:sdtContent>
</w:sdt>
As shown above, each of the structured document tags in the WordprocessingML file is represented using the sdt element.
Within a structured document tag, there are two child elements which contain the definition and the content of this SDT. The first of these is the sdtPr element, which contains the set of properties specified for this structured document tag. The second is the sdtContent element, which contains all the content which is contained within this structured document tag.
Within the SDT's properties, various properties can be set which affect the appearance and behavior of this content in the document. These properties can be divided into four groups:
The complete set of properties for a structured document tag are found on the sdtPr element.
The first group is properties shared by all types of SDTs. These include, but are not limited to, the semantic name for the SDT, a unique ID (as an integer) that is round-tripped and allows the control to be uniquely identified across sessions, and a reference to a document building block that should be displayed as placeholder text.
The next group is the locking properties for the tag -- these specify whether any consumer should allow the contents of the SDT to be edited, or the SDT itself to be deleted from the document.
The next group, the structured document tag's type, specifies how the content should be expressed in a document. These types include: plain text (all contents are of one formatting), rich text, date picker, combo box, drop-down list, and image. Each of the types provides user interface restrictions that restrict the contents to only those specified by the type (e.g., the picture cannot contain text).
Finally, the type-specific properties contain properties that are sensible in the context of that type. For example, the date format for a date picker or the drop-down list entries for a drop-down list/combo box. Type-specific properties are stored as children of the type's element.
Referring to the example above, the date properties are stored underneath the date element, as follows:
<w:sdtPr>
...
<w:date>
<w:dateFormat w:val="M/d/yyyy"/>
<w:lid w:val="EN-US"/>
</w:date>
</w:sdtPr>
This ensures that these properties are only available in the appropriate context(s).
The second child of the sdt element is the sdtContent element, which contains all the content which is contained within this structured document tag.
An additional property for SDTs allows their contents to be stored in another part (in particular, in the custom XML data storage within the file). The presence of the dataBinding element specifies that the contents of this SDT are simply a cache of the data stored at a particular XML element in a particular custom XML data storage part.