|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.|
Using XML to Write a Trip Report
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: Are you a salesperson who spends time on the road visiting customers? Are you part of a marketing team that tracks sales visits? Find out how you can make creating trip reports easier with Word XML features. (7 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
Paul Cornell, Microsoft Corporation
Lisa Wollin, Microsoft Corporation
Published: June 2003
Revised: October 2006
Applies to: Microsoft Office Word 2003
The fictitious company Alpine Ski House makes winter sports gear like skis, snowboards, and snowshoes. Next year, they plan to add a winter clothing line. To prepare, salespeople are visiting clothing stores and gift shops at ski resorts. During these visits, they note their findings in daily trip reports. In the evening, they send the reports to the head office. There, the marketing team combines the reports into daily, weekly, and monthly summaries. At the end of the winter season, they plan to create a final report.
The current solution provides salespeople with a lot of flexibility. Salespeople can write trip reports in the program of their choice. However, it causes problems for marketing because data is inconsistent. Because there is no set format, important data is often missing. To fill in the gaps, marketing must call the sales people to obtain the missing data. Plus, compiling the various reports into summaries is time-consuming. Marketing must copy the data from the different source files into the summary reports. This process wastes time for both marketing and sales.
Alpine Ski House knows that an XML solution is their best choice. With a custom XML schema, salespeople can submit trip reports that include all the data that marketing needs. By using an Extensible Stylesheet Language Transformation (XSLT), marketing can compile multiple trip reports into a single summary report. This reduces the time spent compiling the summary reports. To reach these goals, this solution must:
Reference the correct schema and XSLT with little or no user input.
Enable users to save trip reports as XML data only.
Enable users to add new sections during the current trip or during a later trip.
Enable users to add new contact information.
There are many possible solutions. The solution proposed in this article uses the XML features in Microsoft Office Word 2003. Salespeople write their trip report into a Word template. The template has sections that salespeople can use to enter the data that marketing needs. This solution includes the following items:
An XML schema
A Word template
An XML transform
If you have not already, you may want to take a moment to download the trip report solution files from the link at the beginning of this article. The following sections give details about each file.
The Trip Report Schema
The marketing team needs the following items to create the summary reports:
Name and e-mail address of the salesperson.
Date of the visit.
A summary of all visits on that date.
A list of all visits within an area. This includes sites, summaries, addresses, and contacts.
Contact information for each site visited. This includes contact names, e-mail addresses and street addresses, phone numbers, fax numbers, mobile phone numbers, pager numbers, start and end times, and other notes.
To meet these needs, they design a schema that has elements for each of these items. For the full schema code, see the file named trip_report_sales.xsd in the download.
The purpose of this article is not to explain how to create a schema. Nor is it designed as a reference for the XML Schema Definition language. For a complete explanation of the XML Schema Definition language, see XML Schema on the W3C Web site. You can also search the Internet for additional sources.
The Trip Report Template
Templates in Word enable you to create a structure that people can use to create documents. Templates can include text, formatting, styles, autotext, macros, and other Word features. All of these are useful for creating documents that have a consistent look and feel.
XML enables you to identify the data that you want to include in a file. The trip report schema includes elements that have information about the salesperson and details about trip visits.
When you combine templates and XML, you create a structure for users to provide the data that you need. You can add text and formatting along with XML elements to show users what information to enter. When finished, users can save the XML data without the formatting.
Inserting Trip Report Data
When you open the document template, Word creates a custom toolbar. Users can insert XML elements by clicking the buttons. These buttons run commands in a Microsoft Visual Basic for Applications (VBA) code project. The VBA code prevents users from putting child elements in the wrong places.
The following example shows the code that runs when you open the template. This code uses the Open event for the Document object. If you want the toolbar to display when users create documents by using the template, you can copy the code between the Sub and EndSub statements into a New event.
This code calls the CreateToolbar subroutine. The CreateToolbar subroutine uses the Microsoft Office CommandBar objects to create a toolbar and buttons, and then attaches each button to other commands in the solution.
When a user closes the trip report template, Word removes the toolbar. The following code shows the Close event for the Document object.
This code calls the DeleteToolbar subroutine. The DeleteToolbar subroutine searches through all toolbars in Word. If it finds the "Trip Report Actions" toolbar created in the CreateToolbar subroutine, it deletes the toolbar.
As mentioned previously, each of the toolbar buttons map to VBA commands. These commands stop users from adding elements where they do not belong. For example, you do not want users to insert a visit element inside a placeContactName element. This would cause the document to be invalid according to the schema and make the data unusable.
If a user wants to insert the data for a new visit, they click New Visit. The New Visit button maps to the InsertNewVisit subroutine. The following example shows that the InsertNewVisit subroutine calls the InsertNewVisitHandler2 subroutine.
Public Sub InsertNewVisit() On Error Resume Next Call InsertNewVisitHandler2(Selection.XMLParentNode) End Sub
The InsertNewVisitHandler2 subroutine requires an XMLNode object. By using the Selection object, the code accesses the element at the cursor. If the cursor is outside the root element, the subroutine passes an empty object. Because the cursor may be inside an element that does not allow the visit element, the InsertNewVisitHandler2 subroutine handles all errors. The On Error Resume Next line is necessary to force the call to the InsertNewVisitHandler2 subroutine. The following code shows the InsertNewVisitHandler2 subroutine.
Public Sub InsertNewVisitHandler2(ByRef objNode As Word.XMLNode) On Error Resume Next Dim objVisitedPlacesNode As Word.XMLNode Dim objVisitedPlaceNode As Word.XMLNode Dim objPlaceContactNode As Word.XMLNode If objNode.BaseName = "visits" Then Dim objPlaceNode As Word.XMLNode objNode.ChildNodeSuggestions(1).Insert ' visit objNode.ChildNodes(1).ChildNodeSuggestions(1).Insert ' visitLocation Selection.MoveRight objNode.ChildNodes(1).ChildNodeSuggestions(2).Insert ' visitSummary Selection.MoveRight objNode.ChildNodes(1).ChildNodeSuggestions(3).Insert ' visitedPlaces Set objVisitedPlacesNode = objNode.ChildNodes(1).ChildNodes(3) ' visitedPlaces Set objVisitedPlaceNode = InsertNewPlaceHandler2(objVisitedPlacesNode) Set objPlaceContactNode = InsertNewContactHandler2(objVisitedPlaceNode) Else MsgBox "You must click inside a visits element first." End If End Sub
The previous code verifies the name of the element by using the BaseName property of the XMLNode object. If the name of the element is "visits", the code inserts the visit element and its child elements. If it is not, the code displays an error message. The On Error Resume Next line is necessary to run the code that displays the error message.
All of the toolbar buttons are set up in this same way. For a complete listing of the code for the toolbar, see the TripReportTemplate.dot file included in the download.
Saving Files with XML Data Only
The trip report template in the download includes additional text and formatting. If you do not want to include this in the XML files, you need to save the documents without it. You do this by selecting the Ignore Mixed Content check box in the XML Options dialog box (XML Structure task pane). After you check this option in the template, users can save the XML without the added text or formatting.
The Trip Report Actions toolbar has a Save as XML button. When a user clicks this button, the SaveDocAsXML subroutine runs. This subroutine saves the document with the XML data only (XMLSaveDataOnly property). The following example shows the SaveDocAsXml subroutine.
Public Sub SaveDocAsXML() On Error GoTo SaveDocAsXML_Err ActiveDocument.XMLSaveDataOnly = True ActiveDocument.SaveAs , wdFormatXML SaveDocAsXML_End: Exit Sub SaveDocAsXML_Err: Select Case Err.Number Case 6119 ' XML not valid. MsgBox Err.Description & ". Please correct the " & _ "document and try again." GoTo SaveDocAsXML_End Case Else MsgBox Err.Number & " " & Err.Description GoTo SaveDocAsXML_End End Select End Sub
This code ensures that Word does not save the XML if it is invalid. Invalid elements display in the XML Structure task pane with a yellow caution symbol next to them. For example, the trip report schema requires that the reportDate element follow a specific pattern. If dates do not follow this pattern, the data is invalid. In that case, Word does not save the XML data, and users see an error message.
The Trip Report Transform
One benefit of XML is that you can transform all or part of an XML file into other formats. For example, you can transform an XML file into HTML, PDF, a Word document, or any other format that you want. This is one reason why the marketing team at Alpine Ski House chose an XML solution. When marketing compiles the trip reports for their board of directors, they do not want to include all of the data in the trip report. Instead, they want to expose only the following information:
The salesperson's name and the date of each visit
A summary of all visits
A summary of trips by geographical area
The names and summaries of places visited within each geographical area
The contact names and notes for each place visited
To transform XML data into other formats, you need an XSLT file. The download for this article includes an XSLT file named odc_wdalpine.xsl. You can use this file to transform trip reports that you create with the trip report template.
To apply the transform to a trip report
Open the XML file for the trip report.
On the File menu, click Save As.
Check Apply Transform.
Locate and select the transform.
Word applies the transform when it saves the XML file.
This article shows how Alpine Ski House created a solution that both the sales team and the marketing team can use. All they needed was a custom XML schema and the XML features of Word. Now, their salespeople can write trip reports that include all the data that marketing needs. In addition, marketing can compile their reports in a fraction of the time that was previously required.
Alpine Ski House is a fictitious company, but your company and your needs are real. This article shows you one possible solution. Other Microsoft Office system applications, including Microsoft Office InfoPath, also let you save data as XML. By using the XML features in Microsoft Office system applications, you can create your own custom solutions to help you work smarter.
For more information, see the following resources: