5.1 What s a Smart Document?

5.1 What's a Smart Document?

A Smart Document has built-in intelligence that assists the information worker in the process of creating and updating documents and spreadsheets. Smart Documents can query a web service for the latest financial information about a company and automatically insert the returned data into the document. They can access a corporate database and retrieve client information necessary to complete a contract. They can connect to a document repository or portal site and retrieve reusable fragments, such as standard legal notices and disclaimers, or product and service descriptions, and add them to a new or existing document. They can validate that a user has supplied all of the necessary information before saving and forwarding it on to the next step in the workflow. Providing quick and easy access to accurate, up-to-date information and eliminating the need for re-keying or copying from one application to another, Smart Documents can be of tremendous benefit to the end user, especially for editing XML documents.

Word 2003's core XML support provides no method for associating elements in context with Word styles. This is standard functionality in the market-leading XML-for-documents applications and is typically accomplished through some type of stylesheet (DSSSL, FOSI, CSS, or proprietary solutions). As we saw in Chapter 4, an onload XSLT stylesheet can apply styles to an existing XML instance when it is first opened in Microsoft Word. However, once any changes have been made to the document, the XML Document task pane (which is used to select an onload stylesheet) is no longer available. Without a Smart Document solution, not only would the end user have to manually select each of the appropriate elements to be inserted into the document (using the XML Structure task pane or selecting "Apply XML Element" from the pop-up menu), they would also need to manually associate formatting information with each text fragment created.

Unlike traditional XML authoring applications such as Arbortext's Epic Editor or Adobe's FrameMaker, Smart Documents are capable of keeping the markup under the covers; users can peek if they wish, but there is no requirement for them to learn all about XML schemas and the particular vocabulary and grammar associated with their documents.

Smart Document technology is new in Office 2003 and designed to work with Word and Excel. An extension of the Smart Tags API introduced in Office XP, Smart Documents extend the programmability of these desktop tools to support development of solutions. A solution is dedicated to a particular task, such as writing a technical manual, a sales proposal, a quarterly SEC filing, or an expense report, and incorporates functionality designed to make the information worker's job easier. Smart Documents require an XML framework, and can include all of the features and functionality of the applications themselves through the use of the Word or Excel Object Models. Smart Documents can also be extended through the use of Web Services, SharePoint Services, and other database connectivity methods to dynamically populate and update content. Smart Documents can also incorporate workflow capabilities, such as checking on save that all required components have been supplied and then forwarding the document to a manager for approval. Microsoft provides support for Smart Document development in several languages: Visual Basic 6.0, Visual C++ 6.0, Visual Basic .NET, and Visual C# .NET.

The Smart Document SDK (sdocsdk.msi) can be downloaded from the Microsoft web site. Since the location is subject to change, the best way to locate the file is to go to: http://www.microsoft.com and search for sdocsdk.msi. The SDK includes documentation, help files, and several sample applications (including source code) developed in each of the four supported languages.

While it has been possible for quite some time to automate certain functions within the Microsoft Office Suite, a Smart Document raises the art to a new level. The Microsoft Office 2003 "System" provides a robust software development environment for building custom applications within no-longer-ordinary desktop tools. Rather than macros residing in individual template or document files, Smart Document code is distributed via a .dll that is associated with the document or spreadsheet through a manifest file. The developer is given access to the Task Pane where numerous actions are displayed for the end user along with help content. New protection functionality means that user access can be controlled on a granular level. You can restrict the use of styles, allowing you, rather than the end user, to control the formatting through the Smart Document application. Sections of the document can be protected, ensuring that required content is not accidentally removed. The document appears to have some level of intelligence about what it is and how it works.

5.1.1 Smart Document Solutions

A solution, also referred to as an "expansion pack," consists of several components. At a minimum, an expansion pack contains the following:

A .dll
A schema
A manifest file

In addition, it most likely will also include one or more templates and help files, XSLT files, and potentially media files (images, audio or video clips, etc.). Microsoft Word solutions might also include document fragments.

While Smart Document solutions can be built for either Word or Excel, this chapter focuses on the intricacies of developing solutions for Microsoft Office Word 2003.

5.1.2 Smart Document Components

Each component of a Smart Document plays an integral part in the overall solution. Care must be taken to ensure that each component is synchronized with the others; if an element name has been modified in the schema and is the subject of a Smart Document control, it must also be updated in the programming code and any XSLT files. Since pointers to fragments are to absolute paths, care must be taken to ensure that each file is included in the installation and placed in the appropriate location. The Smart Document components are as follows:

Schemas: Schemas are the foundation of any structured markup implementation. A schema defines a vocabulary and grammar for a specific purpose, such as the creation of semiconductor datasheets, legal contracts, or user manuals. "Vocabulary" refers to the unique identifiers assigned to each of the components of the information set (i.e., elements), and "grammar" refers to the rules of how the words can be put together to form larger groups. Careful analysis of the information set is required to ensure that the schema to be used will provide the necessary support.
Styles and templates: Templates are, for the most part, empty documents that contain all the necessary information about a particular document type to allow new document instances to be created. In particular, this includes page layouts, styles, header/footer information, and fonts. There are four style categories in Word: paragraph, character, list, and table. Each named style is based on one of these four types and contains numerous settings that define the placement and appearance of any content associated with that specific style. For a Smart Document solution, there is another critical component: a shell XML instance with placeholder text. Boilerplate content may also be included.
XSL transformations: XSL transformations play a vital role in a Word Smart Document solution. As described in Chapter 4, transformations can be called when either opening or saving a document, manipulating the source or resulting data as necessary. Transformations can also be incorporated into the solution itself to apply styles and other formatting characteristics, or otherwise affect the result of an action.
.dll files: The functionality of a Smart Document solution operates through the ISmartDocument interface. The properties and methods of ISmartDocument, in conjunction with the objects, properties, and methods of the Word or Excel Object Model, are the workhorses of the solution.
Manifest file: The manifest file is an XML instance that defines each of the expansion pack components and their locations. It also contains other valuable information about the solution that can be used to automatically trigger updates.
Miscellaneous files: There can be numerous files associated with a Smart Document solution, including image, sound and video files, document fragments, help files, Access database files, other XML files, and just about anything else that may be necessary (or useful) for your particular application.