5.6 Other Files

A Smart Document solution is likely to contain numerous files help files, templates, XSL transformations, document fragments, and media clips, not to mention the actual .dll, manifest file, and schema. Each of these files should be listed in the manifest; when the expansion pack is attached to the document or template, the application will check to ensure that it can locate each referenced file.

It is important to note, however, that the references to these files in the .dll must be absolute pathnames or URLs. If the Smart Document solution cannot locate a referenced file, it will just ignore it. Building in some error checking to test that the files actually exist in the designated file locations is highly recommended.

One method for resolving the absolute pathname is to set a constant to the installation directory of the Smart Document solution in the SmartDocInitialize method. By prepending this constant to the specific directory and filename, the files can be located by the application and the developer does not have to worry about where they were actually installed.

If a specific installation directory is not given in the manifest file, the solution is loaded in the schema folder under the Application Data folder in the user's Documents and Settings folder (C:\Documents and Settings\<username>\Local Settings\Application Data\Microsoft\Schemas).

Subdirectories appear to be flattened when copied to the installation directory; that is, if you created subdirectories for components such as help files, images, and XML fragments, those subdirectories will not be created when the solution is installed on the user's system; instead the files will be aggregated into a single directory. Because of this behavior it is strongly recommended that filenames are unique across the entire solution set.

When building and testing Smart Document solutions, it is a good idea to continually delete temporary files. Common locations for these files are:

C:\Documents and Settings\username\Local Settings\Application Data\Microsoft\Schemas

C:\Documents and Settings\username\Local Settings\Application Data\Assembly

C:\Documents and Settings\username\Local Settings\Temp

5.6.1 Help files

Help files are created using a subset of XHTML. The most important thing to remember when creating help files is that the task pane is only a small percentage of the overall screen size, and there are numerous components to be displayed in this limited space. Keep help text clear and concise. In general, you will create one help file for each control included in the Smart Document solution. Table 5-7 lists the supported elements.

Table 5-7. Supported elements in help file XHTML

Element	Purpose
A	Anchor for hypertext links
B	Bold
BR	Break
CENTER	Centers text in task pane
FONT	Font characteristics
H1-H6	Headings
I	Italic
LI	List item
OL	Ordered (numbered) list
P	Paragraph
SPAN	Inline text block
U	Underline
UL	Unordered (bulleted) list

Here's a listing of the help file that's associated with the authoring templates control:

<p><b>Authoring Templates</b>: There are several types of content blocks  that can be inserted in an article:</p> <ul>   <li>paragraph</li>   <li>code block</li>   <li>numbered list</li>   <li>bulleted list</li>   <li>term / definition list</li>   <li>warning</li>   <li>note</li> </ul> <p>It is possible to have more than one entry for any type; that is,  you may have three authors and two editors. Click on the radio button  next to the desired selection.</p> <p><b>Logo</b>: Select the appropriate logo from the images below.</p> <p><b>Website</b>: For additional help, click on the link below.</p> <p><b>Required Warning</b>: The Warning below, if needed, must be  incorporated into your document without modification. Click on the  content and it will automatically be inserted into your document.</p>

5.6.2 Document Fragments

The world of structured document authoring has been using fragments for quite some time, either managed as file entities or as objects in a content management system. Smart Document technology opens this potential to Microsoft Word 2003 users.

Let's say that you work in a law firm. More likely than not, you have a library of document fragments that can be used to create contracts, wills and trusts, and other legal documents. Or maybe you have to search through existing documents to find the right pieces you need, and then cut and paste. You can now access those components directly through the task pane and can build in sufficient intelligence so that only relevant fragments are displayed. Or maybe your sales and marketing group struggles with the process of creating proposals for your products and services. By managing independent descriptions that are targeted to various types of customers (such as government, commercial, or industry-specific) your salespeople will be able to quickly assemble proposals that contain the most up-to-date, accurate information along with any boilerplate required by your legal department. Yet another common usage is in the area of technical documentation. Warnings, cautions, and notes have legal implications and must typically go through an approval process. Once approved, the text cannot be modified. By taking advantage of document fragments, the content can be automatically inserted into the document making sure that no errors occurred during a copy and paste operation, and the content can then be protected to prevent the end user from making any unauthorized changes.

By default, Word will display the first page of any document fragment in the task pane. For lengthy fragments this can be cumbersome. Another option is to create two versions of the fragment one that is displayed in the task pane and the other containing the complete dataset. Document fragments must be valid WordprocessingML instances. The easiest way to create such fragments is to use Microsoft Office Word 2003 with the Smart Document solution attached as described in the next section. This enables you to take advantage of the templates and styles to apply your schema-specific markup along with the necessary WordprocessingML markup and style information. When saving, save as XML. Fragments can also be created by taking existing XML components and running them through an XSL transform. Here's the listing for our Warning document fragment (with most of the heading information omitted). Note that it contains both WordprocessingML (prefixed by w) and our own schema elements (prefixed by ns0):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?mso-application prog?> <w:wordDocument  xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml" xmlns:v="urn:schemas- microsoft-com:vml"  xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:sl="http://schemas.microsoft. com/schemaLibrary/2003/core" xmlns:aml="http://schemas.microsoft.com/aml/2001/core"  xmlns:wx="http://schemas.microsoft.com/office/word/2003/auxHint" xmlns:o="urn: schemas-microsoft-com:office:office"  xmlns:dt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882"  xmlns:ns0="http://www.office-xml.com/ns/sdarticle"  w:macrosPresent="no" w:embeddedObjPresent="no"  w:ocxPresent="no" xml:space="preserve"> ... <w:body> <ns0:Warning> <ns0:Para> <w:p><w:pPr><w:pStyle w:val="Warning"/></w:pPr><w:r> <w:t>In order to run a Smart Document solution, the user will  need to have several components installed on their local system: </w:t></w:r></w:p></ns0:Para></ns0:Warning> <w:p/> </w:body> </w:wordDocument>