Advanced XML Features for the Developer [Word 2003 XML Reference] --  Microsoft Office Word 2003 XML Software Development Kit

  • Article

Advanced XML Features for the Developer [Word 2003 XML Reference]

Important  The information set out in this topic is presented exclusively for the benefit and use of individuals and organizations outside the United States and its territories or whose products were distributed by Microsoft before January 2010, when Microsoft removed an implementation of particular functionality related to custom XML from Word. This information may not be read or used by individuals or organizations in the United States or its territories whose products were licensed by Microsoft after January 10, 2010; those products will not behave the same as products licensed before that date or licenses for use outside the United States.

This topic briefly discusses a few of the XML capabilities of Microsoft® Office Word 2003 that are not immediately apparent from a review of its XML-related user interface elements and object model.

  1. Specifying custom XML validation error messages.
  2. Importing XML document fragments as "context-free chunks" in scenarios where you want to combine sections of existing content into a new document.
  3. Using an XML document like a .Dot template to provide a central definition of style, list, and font information used in a set of documents.

Specifying custom XML validation error messages

Summary. By default, Word displays technical error messages from the XML parsing engine to indicate violations of the attached XML schema. Users may find these error messages intimidating and difficult to understand. You can use the SetValidationError method of Word's XMLNode object to attach more useful and user-friendly error messages programmatically to specific nodes in an XML document.

Programming Steps

  1. In your code, select the XMLNode for which you want to create a custom validation error message.
  2. Call the node's SetValidationError method. This method has one required and two optional parameters.
    • The required Status parameter uses an enumerated constant to specify whether to set or to clear the custom error message text.
    • The ErrorText parameter contains the custom validation error message text. ErrorText is an optional parameter if you are manually setting the status to OK.
    • The optional ClearedAutomatically parameter specifies whether to clear this error message the next time Office Word 2003 validates the contents of the node. In other words, when this value is True, the custom error message is only used once.
  3. To confirm that the custom validation error message has been set, switch to the Word application and simulate a schema violation that affects the node or nodes for which you have set custom messages. View the error messages indicated by the icons in the XML Structure task pane. (This step assumes that you have not disabled validation or disabled the display of validation errors.)

Importing XML document fragments as "context-free chunks"

Summary. When you want to import portions of one Word XML document into another, you can do this using the cfChunk element in the XML Document 2003 namespace. You wrap the content that you want to insert, including any required styles, fonts, and lists, in a cfChunk element. Next, Word takes care of merging the imported styles, fonts, and lists with those in the destination document, inserting the new content, and then discarding the cfChunk wrapper element. This enables you to perform simple document assembly tasks by manipulating the WordProcessingML of a set of documents with standard XML programming syntax.

For example, imagine that you would like to combine a group of WordprocessingML documents, each containing a single legal clause, into a single document. Your initial idea may be to write something like the following:

<w:wordDocument> ... boilerplate content of main contract doc ... <w:wordDocument>
            ... file that has clause 1 ... </w:wordDocument> <w:wordDocument> ...
            file that has clause 2 ... </w:wordDocument> <w:wordDocument> ... file
            that has clause 3 ... </w:wordDocument> ... more boilerplate ... </w:wordDocument>

This doesn't work because it's illegal XML by the WordprocessingML schema. However, the cfChunk element lets you accomplish this. You can build up each clause as a cfChunk using any XML-aware programming tool. This means you can programmatically generate dynamic documents on the server by adding the cfChunks into the parent document at the desired locations. When the document is opened by Office Word 2003, the application merges the content of each cfChunk, including all required style, font, and list information into a single well-formed WordprocessingML document.

Here is the schema of the cfChunkElt complex type used by the cfChunk element.

<xsd:complexType name="cfChunkElt" > <xsd:sequence> <xsd:element
        name="lists" type="listsElt" minOccurs="0"> </xsd:element> <xsd:element
        name="styles" type="stylesElt" minOccurs="0"> </xsd:element> <xsd:element
        name="fonts" type="fontsListElt" minOccurs="0"> </xsd:element> <xsd:group
        ref="blockLevelChunkElts" minOccurs="0" maxOccurs="unbounded"></xsd:group>
        </xsd:sequence> </xsd:complexType>

Programming Steps

  1. In your code, open the main WordprocessingML document into which you want to import content from other WordProcessingML documents.
  2. Separately, open the first WordProcessingML document from which you want to import content.
  3. Programmatically create a new XML document with a cfChunk element as its root node. You now have two open WordProcessingML documents, and one XML document which will temporarily hold the content to be transferred from one to the other.
  4. Construct the cfChunk element. Begin by inserting the list, style, and font elements from the document you wish to import into the cfChunk. These will hold the contents of the list, style, and font information for the piece of content to be added to the target document. Next, find the appropriate content from the import source document and add the WordprocessingML for that content into the body element of the cfChunk node.
  5. Choose the location in the main destination WordProcessingML document where you want to insert the imported piece of content.
  6. Insert the cfChunk node into the destination WordProcessingML document at the chosen location using standard XML methods to import into a subtree.
  7. Repeat these steps as needed.

Using an XML document like a .DOT template

Summary. You can attach a Word document saved in XML format (not, however, as "data only") to another Word document as a template, just as you would use a typical Word template in .DOT format. Word disregards any content in the attached XML document, but makes its styles, fonts, and lists available to the user in the main document.

Steps

  1. Open a document in Word.
  2. On the Tools menu, open the Templates and Add-Ins dialog box.
  3. On the Templates tab, click Attach... to attach a document template.
  4. In the Attach Template dialog box, change the selection in the Files of type list from Document Templates (*.dot) to XML Files (*.xml) or All Word Documents (*.doc;*.dot;*.htm;*.html;*.url;*.xml) or All Files (*.*).
  5. Browse for and select a Word document saved in XML format and click Open.
  6. Click OK to close the Templates and Add-Ins dialog box.
  7. Display the Styles and Formatting task pane to view the styles from the XML template document that are now available in the main document.

©2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp