5.3 Coding the Smart Document

Now that you have the XML foundation laid, it's time to integrate the data with code for manipulating it.

5.3.1 Required Document Actions

For our Smart Document solution, several actions will be required:

  • Apply markup and style to inline components (superscript, subscript, bold, italic, underscore, and code).

  • Insert block-level components (paragraphs, code blocks, lists, notes, and warnings).

  • Insert additional entries into lists.

  • Insert boilerplate warnings.

  • Add a graphic.

  • Create a hyperlink to a specific location.

Each action will contain a caption, a description, and help information for the end user. Upon selection, the appropriate markup will be inserted and styles applied. Pay careful attention to the Notes and Warnings; Microsoft Word, in this first release of Smart Document functionality, doesn't always behave as expected.

In general, beware of the cursor location. The values returned by your code may not be what you anticipated; this might be due to the current setting of the tag display.

Also, paragraph styles can only be applied to objects that look like a paragraph. If your markup runs in with another style, it will either inherit the current style characteristics or change the entire block to the new style.

5.3.2 Designing the Document Actions Task Pane

You have created, tested, tweaked, and refined your schemas. Your stylesheets are elegant, sophisticated, funky, or whatever other look is suited to the task at hand. The XSL transformations take your existing XML instances and magically convert them into documents any Word user would love. Unfortunately, the end users will never see most of this work. Instead, they will use a very simple interface that masks the complexities buried deep inside the solution. They will use it to add content, to manipulate the markup, and to serve as a guide throughout the document creation and revision cycles.

Remember it's all about end users. If your solution does not make users' jobs easier, increase their productivity, raise the quality of the final products they produce, and provide other clearly visible benefits, end users will not use it. Or they will not use it properly. The XML that comes out of the backend will be useless or at least in need of some help. The reason knowledge workers have been anxiously awaiting the time when they could work with their structured content in Microsoft Word is because of Word's familiar interface. The goal of the UI designer is to ensure that the Document Actions task pane meets their expectations.

Achieving this goal may not be easy. The Document Actions task pane is the end user's interface to the Smart Document solution. It would be nice if the Microsoft Word developers had created a method by which you could associate actions with a specific element, or even better yet, an element in context (such as title when its parent element is table versus title when its parent element is chapter), but that isn't how it works. Actions are associated with elements, but rather than limit the action to the confines of the element boundaries, the actions instead are inherited by child and descendent elements as well. This means that if your structure contains five levels <document><section><procedure><step><paragraph> and the cursor is positioned somewhere within paragraph, any actions associated with the document, section, procedure, step, and paragraph elements will be visible in the task pane.

The Document Actions task pane refreshes each time the location of the insertion point within the document instance changes. Be sure to design the interface with this in mind, eliminating lengthy re-draws whenever possible.

The task pane, shown in Figure 5-6, appears by default on the right-hand side of the application window. It automatically displays any available document actions whenever a Smart Document solution is attached. As it takes up only about 20% of the available real estate, it's important that the content associated with each of the actions is clear and concise, taking maximum advantage of the limited space.

Figure 5-6. Authoring template and Document Actions task pane

For each Smart Document element defined, the task pane will display one or more controls associated with the element (as long as the element is an ancestor of the current insertion point). There are only a few options available to help format the display. In order to make the task pane as user-friendly as possible, each control group should begin with a caption and possibly some very brief explanatory text indicating how the actual control(s) should be used, followed by the controls themselves, and some help text that provides additional details about their usage.

Good user interface design principles call for consistent usage of display elements. While it is possible to use all 15 control types within a single Smart Document solution, selecting the best control for the task at hand and then using that same control for similar tasks will shorten training time and help ensure proper usage.

5.3.3 The Word Object Model

If you've ever written Word macros or done Visual Basic for Applications (VBA) programming, you've probably encountered the Word Object Model. An interactive map of the model can be found in Microsoft Office Word 2003 Help Microsoft Word Visual Basic Reference Microsoft Word Object Model. Unfortunately, all of the sample code contained in the help files is written in VBA rather than VB.NET or any of the other languages used for creating Smart Documents. All is not lost, however; there's a section in the Visual Studio Tools for Office help system that discusses converting code from VBA to VB.NET.

The two most commonly used objects are Range and Selection. The Selection object represents the area currently selected, or the current insertion point. The Range object can be either manually set or created from a Selection object. In most of our code samples, we begin by determining the current cursor location and setting a Range object equivalent to an XML element and its content (XML Node); that is, everything between a start and end element tag, including the tags themselves. We then typically collapse the node so we can insert a new element, assign the appropriate style, and then add placeholder text so the end user will know exactly where to enter the new content.

The Word object model is covered in depth in the Microsoft Word Visual Basic Reference included in the Microsoft Office Word 2003 help files, and in Writing Word Macros by Steven Roman (O'Reilly). There are a number of additions to the Word Object Model in Word 2003; a few are detailed below. They are the objects and methods most likely to be referenced in a Smart Document application since they deal specifically with XML. XML additions to the Word object model

The Word 2003 object model includes five new objects and collections as well as enhancements to the Application, Document, Range, and Selection objects. These are documented in the Microsoft Office Word 2003 help files under "What's New" as well as under their respective group headings. Some of the key pieces that you'll need for Smart Documents development include:


The InsertXML method applies to both Range and Selection objects and is used to insert either WordprocessingML or customer-specific schema elements and associated content. It can also be used in conjunction with transformations, taking some minimal source data, running through a transform to apply styles, and then inserting the results into the document instance.

Use caution when using the InsertXML method as it will replace any existing text in the Range or Selection object.


The XMLNodes collection represents each of the XML elements within a document. The XMLNode object is the workhorse of a Smart Document and allows XML elements to be selected, added, deleted, or validated. It is also used to add placeholder text. Numerous tests can be performed against an XMLNode, and it can be used to access first child, last child, parent, previous sibling, and other objects.


The XMLParentNode property is used, as the name suggests, to return the parent node of the current XML node. It is used in conjunction with ranges and selections:

Dim oParagraphNode As Word.XMLNode oParagraphNode = Selection.XMLParentNode

In addition to being able to guide the information worker through the process of creating, revising, and updating documents, most XML-related events can be captured and cause code to be executed:


Any time that new XML markup is inserted in the document, the XMLAfterInsert event will be accessible. If the end user is inserting markup through the XML Structure task pane, this event could be used to add appropriate style information or other WordprocessingML markup. It could also be used to populate required child elements, mimicking some of the types of functions that could be programmed into the Document Actions task pane.


While the Smart Document solution described in this chapter will handle the creation of an XML instance, making modifications to that document could easily result in an instance that is no longer valid. This is particularly true if the user tries to perform cut and paste operations. By trapping the XMLBeforeDelete event, the developer can ensure that the content to be deleted will not result in breaking the document structure by preventing the deletion of any elements that would result in an invalid instance. Instead, additional actions could be triggered that would guide the author through the editorial process.


Any time a validation error occurs within a document instance, the XMLValidationError event will be activated. It returns the XML node that is invalid, and can be used to either remove the offending node or add the necessary components to return the instance to a valid state.


Each time the parent node of the current cursor position changes, the XMLSelectionChange event is initiated. Both the previous and new nodes can be evaluated, along with the reason:

  • Delete the previous selection was deleted

  • Insert text has been inserted

  • Move the insertion point has been moved

Office 2003 XML
Office 2003 XML
ISBN: 0596005385
EAN: 2147483647
Year: 2003
Pages: 135

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net