5.9 A Few Last Words on Smart Documents

Now that you've seen the parts involved, it's worth considering which aspects of Smart Documents need your focus.

5.9.1 Range and Selection Objects

The Word object model consists of hundreds of objects, yet no two are more powerful than range and selection. These two objects are used to identify the parts of the document that are to be manipulated by the accompanying code. What is confusing is that, for most cases, either object can be used. The main difference is that a range is not visible to the end user; that is, you can identify a range and manipulate it, and the end user's cursor location will not move. selection, on the other hand, does exactly what you'd expect literally highlighting the selection on the end user's screen. More often than not, range is preferred over selection for several reasons, not the least of which is performance.

Both the range and selection objects have dozens of properties and methods associated with them everything from cut, insert, and delete to XMLNodes. For a thorough explanation of range and selection, see Writing Word Macros by Steven Roman (O'Reilly).

5.9.2 Inserting Markup

One of the powerful features of Word is its ability to quickly change the "view" of any document on the screen. You can turn individual formatting markers on or off, change the overall look from outline to print layout, view field codes or placeholder text. What may not have been apparent in the past but now becomes clearly evident is what, if any, impact these changes have on the cursor position. When determining what elements are allowed in context, the context referred to is the current cursor location. When programming Smart Documents, you must determine the current view; otherwise your tests may yield undesired results.

5.9.3 Validation

The "Valid elements for insertion" list as displayed in the XML Structure task pane does not pay attention to sequence or occurrence. If the cursor is currently positioned within an element that has children, all of those child elements will be displayed. Word will, however, display an error once an invalid child has been inserted, via both squiggly lines in the document pane and symbols in the XML Structure view. The developer can take advantage of the XMLValidationError method to prevent the user from creating an invalid instance and to provide additional guidance. If the user does not use the XML Structure task pane to insert markup, this problem is avoided.

5.9.4 Inserting Styles

Microsoft Word has four types of styles: character, paragraph, list, and table. When applying styles to content, the surrounding WordprocessingML markup becomes very important. If applying a paragraph-level style to some text (paragraph styles and list styles), that content must be both preceded and followed by a paragraph marker. If the text is not preceded by a paragraph marker, then when the style is applied it will be applied to the entire block; that is, to all content until either a preceding paragraph marker is located or to the top of the document itself. Similarly, if the text following the content to be formatted is not separated by a paragraph marker, it too will take on the particular style characteristics meant to be associated with the content.

5.9.5 Stories or Streams

Word objects such as headers, footers, footnotes, endnotes, comments, and text frames are maintained separately from the main body of a document. They each have their own object model and are accessible programmatically, but if they contain XML markup, your resulting instance when saving the document will most likely result in errors. The best way to handle these separate streams is through direct use of the Word tools; capture them on save by making use of a transform that will convert the WordprocessingML to your specific markup and place the contents in the right location within the XML document instance.