|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Microsoft Office Word 2003 XML: Memo Styles Sample
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Summary: Microsoft Office Word 2003 has added a number of features related to working with XML. These features are integrated in new task panes, menu options, and additions to the object model. In this article, we will examine some of these features from the perspective of the user interface and programmatically. (22 printed pages)
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.
Frank C. Rice, Microsoft Corporation
Applies to: Microsoft Office Word 2003
Microsoft Office Word 2003 includes several new XML-related features and improvements to existing features. For example, Word now supports a XML file format called Word XML that support round-tripping. Round-tripping means that the XML that is exported by Word can also be imported and understood by Word. Microsoft Office 2003 supports a new Word XML file format that can be easily read, transformed, and manipulated by XML tools. Word 2003 will also make it easy for you to attach a schema to a document and then assign elements from the schema to parts of the document. For more information on these and other new and updated features of Word 2003, see the articles Microsoft Office Word 2003 Preview (Part 1 of 2) and Microsoft Office Word 2003 Preview (Part 2 of 2).
A number of new properties, methods, and objects have also been added to the Word Visual Basic for Applications (VBA) object model to account for the new XML features and to help make Word the XML authoring platform of choice. The object model is derived from the existing widely accepted standard: the document object model (DOM), as implemented by Microsoft XML Core Services (MSXML) Version 5.0, so that existing DOM programmers will find the Word environment familiar and professionally designed.
In this article, we will look at working with XML in Word 2003. We will do this by examining some common XML-related tasks using the menus, task panes, and other parts of the user interface. We will also look at performing many of these same tasks programmatically. We will use a plain memo template, XML file, and an XML Schema Document (XSD) file, all of which are available as a download from this article.
So that you can quickly scan and locate the VBA samples in this article, those sections are preceded with the following computer graphic:
To demonstrate working with XML in Word, open the file Plain Memo.doc in Word 2003 (see Figure 1). This is a plain memo template.
As you can see, this document is formatted as a typical business correspondence. Our task is to add XML elements to the memo to create a model. That way, when you import data from an XML file, the memo fields will be populated exactly as you specified. To add XML to this template, you'll need to install and attach an XML schema.
Attaching a schema to the document will allow you to use the schema's elements to mark up the document.
To attach a schema using the user interface:
On the Tools menu, click Templates and Add-Ins.
Click the XML Schema tab (see Figure 2).
Click Add Schema.
Browse to the folder where the memo.xsd file is located, click the file, and then click Open.
In the Schema Settings dialog box, you can enter an alias for the schema. Type Memo Example and then click OK.
When the new schema is installed, it is visible in the box under Available XML schemas. Select the check box to attach the schema to the current document, and then click OK.
You should now be back in the document window with the sample memo and the XML Structure pane visible (See Figure 4).
When you install a schema in Word, it will be referred to by its namespace. If you also specify an alias, Word will refer to the schema by its alias instead. This can be helpful since most namespaces are long and complex.
The following statement is used to programmatically install the Memo.xsd schema, and give it an alias titled "Memo Example":
ActiveDocument.XMLSchemaReferences.Add _ "urn:schemas-microsoft-com.office.demos.memo", _ " Memo Example ", "C:\Word11XML\Memo.xsd"
Now that you have attached a schema to the document, you can use it to mark up the memo with XML. The first step is to bring up the XML Structure pane (if it is not already displayed). You can do this by selecting Task Pane on the View menu. Then at the top of the task pane, where the title is, click the drop-down list, and then click XML Structure.
To display the XML Structure pane programmatically, use the following:
Application.TaskPanes(Index:=wdTaskPaneXMLStructure).Visible = True
Now select the entire document (CTRL+A), and then click the <memo> element located in the box at the bottom of the XML Structure pane.
Word may ask you if you want to apply this element to the entire document. Click Apply to Entire Document.
To programmatically apply the root element <memo> to the document, use the following:
ActiveDocument.XMLNodes.Add Name:="memo", Namespace:="urn:schemas-microsoft-com.office.demos.memo"
You now have XML in your document. The XML Structure pane will be very useful in working with the other XML in your documents.
Let's quickly go through the different portions of the pane:
Elements in the document: This box at the top of the pane is where you can see a tree view of the XML you have applied to your document. If you click on an element in the tree, Word will select that element in the document. You can also use this tree view to manipulate the element itself. If you right-click an element, you will see:
A description of any schema validation errors on that element (if they exist). In the case of our memo example, the <memo> element has an error because it is expecting more elements inside of it. We will fix this error later.
Remove tag. You can use this option to remove the tag from the document.
Attributes. You can use this option to bring up a dialog where you can add or remove attributes to your element.
Show XML tags in the document. This check box is located directly below the Elements in the document tree view. It specifies whether or not XML tags should be displayed directly in the document. By turning this option off, the XML tags will still be in the document; they will just be hidden.
Choose an element to apply to your current selection. This is a list of all possible child elements of the element your selection is currently inside. These elements are listed in the order they appear in the schema file. There are also two small buttons (an up arrow and a down arrow) that allow you to adjust the size of this list box.
List only child elements of current element. This option controls what is displayed in the list box above. If this element is unchecked, every element will be shown instead of just the children of the current selection.
XML Options. This will take you to the XML Options dialog box.
Now that you are familiar with the XML Structure pane, let's move on.
The heading data (To, From, Subject, etc.) for the memo is contained in a table in the document. You can either manually add the tags to the cells in the table or do it programmatically. To add the tags manually:
Select the name in the document's To: field (John Doe) and click the <to> element located in the list box at the bottom of the XML Structure pane. The <to> element is applied to the name.
To continue adding tags manually, select the name in the From: field (Jane Doe) and click the <from> element located in the box at the bottom of the XML Structure pane.
Select the subject of the memo (My memo to all) and click the <subject> element located in the box at the bottom of the XML Structure pane.
You can also apply elements by right-clicking. Select the Priority (High) located in the priority line. Right-click the selection, point to Apply XML element, and then click the <priority> element.
Select the date (1/15/2003). Right-click the selection, point to Apply XML element, and then click the <date> element.
Select the text in the body of the memo. Right-click, point to Apply XML element, and then click the <body> element.
To add individual tags to the document programmatically:
ActiveDocument.Tables(1).Columns(2).Cells(1).Select Selection.XMLNodes.Add Name:="to", Namespace:="urn:schemas-microsoft-com.office.demos.memo"
You can also add XML tags from an Array. Assuming an array named arLtrHeading containing the name of each element, you can add each element to the appropriate cell in the document with the following code:
For i = 1 To UBound(arLtrHeading) + 1 ActiveDocument.Tables(1).Columns(2).Cells(i).Select Selection.XMLNodes.Add Name:=arLtrHeading(x), Namespace:="urn:schemas-microsoft-com.office.demos.memo" x = x + 1 Next i
To add the <body> tag to the document programmatically:
Set rngMainText = ActiveDocument.Range(Start:=ActiveDocument.Paragraphs(18).Range. _ Start, End:=ActiveDocument.Paragraphs(18).Range.End) rngMainText.XMLNodes.Add Name:="body", Namespace:="urn:schemas-microsoft-com.office.demos.memo"
The memo is now marked up with XML.
There are a number of options for saving this file. If you want to use this as a template, you can save it as a Microsoft Word template file (*.dot), and it will keep the XML structure you have applied and be available as a template for other documents. You can also save it as a Microsoft Word document (*.doc), which will also preserve the XML structure. A new option available in Microsoft Office Word 2003 is to save only the data from the file:
To save the XML memo, open the Save As dialog box.
Change the Save as type to XML Document.
Select the Save Data Only check box.
Type a file name (or leave the default), and save the file. Word will prompt you to confirm that you want to save the document as XML only.
Click Continue to save the new XML data only.
To save the XML data only, programmatically:
ActiveDocument.SaveAs "Plain Memo2", XMLSaveMode:=wdXMLSaveMode = wdXMLSaveUserDataOnly
The file created now contains only the XML elements you inserted into the file, and the textual content of the file. Use Microsoft Internet Explorer to open the XML file you saved and look at the results.
This file contains no Word information, and if you were to open it back in Word, all the layout and formatting would be lost. (This is not the case if you have an XSL transformation, which will be explained later in this article.)
Another available option is to save the XML file with the Microsoft Word XML document schema. When you do this, the XML from Word will all be in Word's namespace, and the XML you added will be in its own namespace. This makes it fairly easy to work with the XML you marked up, while still preserving the layout and structure from Word.
To save the XML memo with the Word XML document schema, open the Save As dialog box.
Change Save as type to XML Document.
Make sure the Save Data Only check box is cleared.
Type a new file name, and then click Save to save the file.
Use Internet Explorer to open the XML file you saved and look at the results. You will see all of Word's information for this document, and if you scroll down into the <w:body> tag, you will start to see XML from the memo schema as well.
To save the document as Word XML programmatically:
ActiveDocument.SaveAs "Plain Memo2", XMLSaveMode:=wdFormatXML
This section will show you a little more about how to work with Word's built-in schema validation. After completing the steps above, your document should be valid according to the schema. You will know your document is valid because there will be no red icons in the XML Structure pane. If you have a schema validation error, it will show up in the tree view of the XML Structure pane.
Let's make this document invalid to see what an invalid document looks like. The memo schema has a few restrictions set on it. The <priority> element only allows three possible values: "Low"; "Medium"; and "High."
Select the content of the <priority> element ("High") by clicking on the <priority> element in the tree view of the XML Structure pane. When you click on the <priority> element in the tree view, "High" should be selected in the document.
Delete the current selection, and type "Urgent" instead. "Urgent" should now be the contents of the <priority> tag.
Notice in the tree view in the XML Structure pane that <priority> now has a red icon to its left. Hover over that icon and you will see the warning: This must be one of the following: Low Medium High. This error comes directly from the schema file.
Select the contents of the <priority> tag and change it to "Low" (this value is case sensitive). The error should now be gone.
You can validate a document against a schema programmatically by using the following:
There are a couple of additional things you can do to make this template easier for people to use. This section will show you how to only allow editing within certain XML tags, and also how to create placeholder text.
For many of the people using your template, XML will not be familiar, and for some, the tags might be intimidating. That is why you will probably want to have the tag view turned off when people are filling out this document. Doing this can lead to problems though:
What if the contents of a tag are deleted? How will the user know where to type? This problem can be solved using placeholder text. We will describe that below.
If the tags are off, how can you ensure that people won't accidentally delete them? This can be solved with the new document protection feature. We will also describe that below.
In the following steps, we'll define what placeholder text we want to use in the document when no data is displayed:
First, click on the XML Options link at the bottom of the XML Structure pane.
In the XML Options dialog box, find the option labeled Show placeholder text for all empty elements. Select this option.
To see how placeholder text works, delete all the contents of the <to> element, but don't delete the <to> element itself. You can do this by clicking on the <to> element in the document. The contents will be selected, but not the element itself. Now just press the DELETE key.
Now that the <to> element is empty, turning the tag view off would mean that nothing would show up in the area containing the element. Designating placeholder text allows the user to see where the insertion point is for the element. Turn the tag view off by either clearing the Show XML tags in the document option in the XML Structure pane, or you can also just use the shortcut: CTRL + Shift + X. That shortcut will toggle the tag view on and off.
Notice that when you turn the tag view off, there is still a visible field for the <to> element. You can click the placeholder text for the <to> element and start typing. The content that you type will be inside of the <to> element. If you now delete the content you typed, the placeholder text will be visible again.
You can also customize what is displayed in the placeholder text. To do this, right click on the <to> element in the tree view of the XML Structure pane, and choose Attributes.
You should now be in the Attributes dialog box for the <to> element. At the bottom of the dialog box, there is a text box where you can specify the placeholder text you want to use. Fill this in and click OK. The placeholder text in the document should now be updated.
The following statement is used to set the placeholder text, programmatically:
You to will need to insert the line Application.Options.ReplaceSelection = True in your code so that any text selected is overwritten by the new text. Otherwise, any new typing is inserted before the placeholder text.
Using the Show placeholder text for all empty elements option is not necessary to use placeholder text. Once you specify placeholder text for a particular element in that elements Attributes dialog box, that individual element will always use placeholder text, regardless of the Show placeholder text for all empty elements option.
Also be aware that specifying placeholder text in an elements Attributes dialog box will affect only that individual element and will not work for other elements of that same name throughout the document.
Now that you've given placeholder text to the elements in your document, let's lock it down so that only specific areas will be editable. On the Tools menu, select Protect Document. The Protect Document task pane is displayed.
Here you can lock down the formatting of a document, and you can lock down the editing of a document.
Formatting restrictions: This option allows you to lock the document down so that no direct formatting is allowed, and only styles that you specify can be used to format a document. We will not use this feature in this article.
Editing restrictions: Here you can specify what level of editing you want to allow on your document. For this article, we will make the entire document read only, and then unlock certain portions we want people to edit.
Select the Allow only this type of editing in the document checkbox and then select No changes (Read only) from the drop-down menu.
Select the contents of the <to> element and select the Everyone check box in the Protect Document pane. You have now given permission for everyone to edit the contents of the <to> element.
Now, let's start enforcing protection. Click Yes, Start Enforcing Protection at the bottom of the Protect Document pane.
You will be asked if you want to enter a password. This is optional so press OK.
You should now see that the contents of the <to> element are shaded yellow. This is the only area that you can currently edit. You will not be able to delete any of the XML tags, or edit any of the other content. This is a nice way to make sure that people don't accidentally delete the structure you have applied when they are filling out your template.
You can now examine the XML file that was saved.
Click Open on the File menu and browse to the location of the data-only XML file you saved in the Saving the XML Document section.
Open the XML file in Word. You will notice that the formatting that was originally applied to the file is now gone. The file is opened in the default Data Only view. This view will be used by Word when it opens any XML file it does not already have an XSL transformation for.
Let's choose a different view. In the XML Document pane, click Browse and then browse to the location where you saved the sample file (probably: "C:\Program Files\Microsoft Office Beta Documentation\Microsoft Word XML Content Development Kit Beta 2\Sample"). Select any one of the three transforms (elegant.xsl, professional.xsl, or contemporary.xsl).
You can see that Word now opens the XML file through a transformation, and the file displays in a much nicer way. Let's choose a different view.
Click on the Browse option in the XML Document pane, and in the XSL Transformation dialog box, browse to one of the XSL transformation files located at the location where you saved the sample file.
Select one of the three transforms that you haven't already used (elegant.xsl, professional.xsl, or contemporary.xsl). You can see that Word now opens the XML file through a transformation, and the file displays in a much nicer way.
Now, let's use the Schema Library to teach Word to always use that transform when it opens files of this type (Memo).
Word allows you to associate different resources with namespaces. Namespaces are the way in which XML files can identify what type they are. Word will look at the root namespace of any XML file it opens, and then look to the schema library to see what XSL transformations are available, as well as the location of the XML schema file, so that it can validate the document.
To add an XSL transform to the Schema Library:
On the Tools menu, click Templates and Add-Ins, and then click the XML Schema tab.
On the XML Schema tab, click Schema Library.
Click the Memo Example. Note that if you didn't give the schema an alias when you first added it, it will be listed by its namespace rather than its alias.
Make sure that Word is selected in the Use solution with drop-down box. This specifies that the solution you are about to specify is for Microsoft Word.
Click Add Solution to add a solution — in this case, the transformations for the memo sample.
Browse to the location where you saved the sample files, and select any of the three XSL files (elegant.xsl, professional.xsl, or contemporary.xsl), and then click Open.
In the Solution Settings dialog box, enter a name for the transform in the Alias box.
Click OK. The solution is added to the Select a schema list box on the XML Schema tab.
Repeat these steps for the other two transforms located in the same folder.
You can also specify which XSL transformation you want to be used by default. You can do this by selecting the transformation you want from the Default solution dropdown.
To do this programmatically:
Application.XMLNamespaces.Add Path:="C:\temp\sales_order.xsd", _ Alias:="Sales", InstallForAllUsers:=True
You have now made it so that anytime and XML file in the memo namespace is opened in Word, there will be three nice transforms available to use. Let's try opening the document again.
Click Open in Word and browse to the location of the data-only XML file you saved.
Open the XML file in Word.
On the right side of the screen, the XML Document task pane displays the different transformations available.
Click the different transforms, and see how Word reformats the document automatically.
The process of setting up XSL transformations described above is meant for people working directly with the XSL files, and who are familiar with XML. There is a very easy way to automatically configure a user's Schema Library without requiring them to use the Schema library dialog box. To find out more about this, read the section on manifests in the Smart Document Software Development Kit.
In this article, we looked at several of the new and improved XML-related features in Word 2003. We saw that these features are integrated in new task panes, menu options, and additions to the object model. We examined these features both from the perspective of the user interface and programmatically. After working though the samples in this article and further exploring on your own, it should become clear that Word is becoming the authoring platform of choice for regular text and XML.