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)

Important

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

Download odc_wdalpine.exe.

Contents

  • About the Business

  • The Business Problem

  • The Solution

  • The Trip Report Schema

  • The Trip Report Template

  • The Trip Report Transform

  • Conclusion

  • Additional Resources

About the Business

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 Business Problem

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.

The Solution

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

Note

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.

Note

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.

Private Sub Document_Open()
    Set gwdApp = Word.Application
    Call CreateToolbar
End Sub

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.

Private Sub Document_Close()
    Call Toolbar.DeleteToolbar
    Set wdApp = Nothing
End Sub

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

  1. Start Word.

  2. Open the XML file for the trip report.

  3. On the File menu, click Save As.

  4. Check Apply Transform.

  5. Click Transform.

  6. Locate and select the transform.

  7. Click Open.

  8. Click Save.

  9. Word applies the transform when it saves the XML file.

Conclusion

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.

Additional Resources

For more information, see the following resources: