Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Help! An interesting XML application

A review of a how-to article on using XML to generate help pages.

XML Developer Tip
(Receive this column in your inbox,
click Edit your Profile to subscribe.)

Help! An interesting XML application

One of my favorite sources for XML information--particularly developer news, information, how-tos, and other useful details--occurs in the XML corner on the Web Developer's Exchange (DevX). For example, Philip Dickerson's recent article for the WebDev Zone entitled "Build Generic Page-Specific Help with XML in ASP" is a great case in point.

Dickerson makes the following assertion in his article about building context sensitive help systems for Web pages (something nearly every Web developer needs to do at some time or another):
"The technical design goals for context-specific help are that the help pages should:

  • Open and display very rapidly.
  • Allow easy style changes (visual appearance, layout, etc).
  • Facilitate translation into other languages.
  • Provide flexible capabilities.
  • Allow help authors to concentrate on the help text, not the presentation details."
He also goes on to point out four possible ways to implement such a system, including:
  • "Build Static Web Pages
  • Send Code for Static HTML Pages to Client
  • Create Help Pages on Client Dynamically
  • Pre-Generate Help Pages from XML Source"

His explanation and reasoning in discussing these options is pretty informative, and squares rather nicely with my own view on the subject. He explains how to implement static Web pages, quickly, then dismisses this approach (quite properly) because of the continued manual labor involved in maintaining and updating this kind of implementation. I can attest from experience that even for small Web sites or Web-based applications, building and managing supporting help pages by hand is more trouble than it's worth.

The next approach (and the others covered here) all assume that some sort of servlet environment is available, so that help information can be grabbed and processed as part of accessing a primary ASP, JSP, or PHP based document or page. In this approach, the entire help set-up is grabbed and passed to the client whenever a page is accessed, so that all help documents are local and ready for immediate access. Unfortunately, this approach still requires building and maintaining static help pages, so it's only faster than the previous option, offering no improvement on the developer side.

If you elect option 3, and create help pages on a client dynamically, this means writing a Java Script that not only opens a help window, but that also generates the HTML for the help information. This permits developers to separate help text from other HTML markup completely and maintain it separately. This makes global search-and-replace operations more feasible, permits separate presentation controls, and moves in the direction of more conventional help systems (rather than a collection of static HTML documents).

The option of choice is, of course, to use XML to pre-generate help pages. That way, the calling Web page can pass a help request to a database or some other environment where data stored in XML may be transformed using XSLT to create output on demand (or in advance, as the application may dictate). In this case the process consists of the following 3 steps:

  • Reading XML help text data from a database or source document as the result of processing a help link request
  • Using XSLT to transform the XML help text data into an HTML or XHTML document for output
  • Passing the resulting HTML document into the separate help window for display in the client browser environment

This approach meets all the original design goals quoted earlier here, so that pages open and display rapidly, so that appearance is easy to change by altering the supporting XSLT, and where data is stored in a canonical XML form and is easy to translate. Because a database- or document-driven XML/XSLT combination is extremely flexible (data can change separate from presentation, and vice-versa), and because it stores the help text by itself, it's also much easier for developers to set up and manage such an environment.

The real value of Dickerson's article is that he not only explains these approaches well, but that he also provides sample and mock-up code that shows how to build related implementations. Of course, the deck is stacked in XML's favor--but only because an XML/XSLT combination works best to meet the stated design goals.

About the Author

Ed Tittel is a principal at LANWrights, Inc., a network-oriented writing, training, and consulting firm based in Austin, Texas. He is the creator of the Exam Cram series and has worked on over 30 certification-related books on Microsoft, Novell, and Sun related topics. Ed teaches in the Certified Webmaster Program at Austin Community College and consults. He a member of the NetWorld + Interop faculty, where he specializes in Windows 2000 related courses and presentations.

For More Information:

  • Looking for free research? Browse our comprehensive White Papers section by topic, author or keyword.
  • Are you tired of technospeak? The Web Services Advisor column uses plain talk without the hype.
  • For insightful opinion and commentary from today's industry leaders, read our Guest Commentary columns.
  • Hey Codeheads! Start benefiting from other time-saving XML Developer Tips and .NET Developer Tips.
  • Visit our huge Best Web Links for Web Services collection for the freshest editor-selected resources.
  • Choking on the alphabet soup of industry acronyms? Visit our helpful Glossary for the latest lingo.
  • Visit Ask the Experts for answers to your Web services, SOAP, WSDL, XML, .NET, Java and EAI questions.
  • Discuss this issue, voice your opinion or just talk with your peers in the SearchWebServices Discussion Forums.

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.