[Inso Home Page] [Home] [Collection] [Book] [Expand] [Collapse] [Search Forms] [Previous Section with Hits] [Next Section with Hits] [Clear Search] [Preferences] [Print] [Help]

 inside  Expand Search


   Creating a Publisher's Thesaurus   [Table of Contents]    Printing From DynaWeb

DynaWeb Publishers Guide

[-] 3. Overview of DynaWeb Configuration Files
[-] Exporting XML in DynaWeb

Exporting XML in DynaWeb

The Extensible Markup Language (XML) is a language that supports a subset of SGML features. XML supports stylesheets and optionally, DTDs. DTDs are required for "valid" XML, but "well-formed" XML does not require a DTD. This section assumes that you are familiar with the rules and syntax of XML. This section explains how publishers can integrate basic XML support into their DynaText books using stylesheets and a new PVF - xmlpointer.

How does DynaWeb serve XML?

Publishers can allow users to export any displayed content of a DynaText book as well-formed XML through DynaWeb. DynaWeb serves XML in the same manner as HTML; through a combination of stylesheets and scripts that assigns a mimetype of text/xml to the content and sends the data to the client. The user adds a parameter (xml=[0|1|2]) to the URL of the currently displayed section. This parameter tells DynaWeb how the user wants to view the XML version of the current content. DynaWeb uses a Tcl script located in the configuration files (bookview.dwc) to assign a suitable mimetype, then reconstructs the SGML tags of the source to conform to the XML tag syntax. Once this is accomplished, DynaWeb sends the XML version of the source to the browser. The following sections describe in greater detail how DynaWeb handles a request for XML-compliant content.

Specifying an XML Request

DynaWeb 4.1 uses a new URL parameter to control the rendering of XML. The xml parameter allows the browser to display XML as plain text inside the content frame, or return the current section as XML (with a mimetype of text/xml) to the browser. DynaWeb does not serve out the TOC in XML. Only the content frame is exported to XML. The xml parameter is separated from the rest of the URL with a semi-colon (;), as shown below.

http://server:port/collection/book/@Generic__BookView/2768;xml=2

The xml Parameter

The xml parameter informs DynaWeb if the data in the content frame should be rendered in XML or plain text. This is useful for viewing the currently displayed section of the document as XML, or previewing the section as XML without attempting to parse the generated tags.

The value of xml can be either 0, 1, or 2. If the xml URL parameter is not present, it defaults to 0. A value of 0 means that the data in the content frame is assigned a mimetype of text/html and is handled normally by DynaWeb. A value of 1 assigns a mimetype of text/xml and causes the data in the content frame to be handled by the Tcl script XML__BookTextView. This renders XML tags in place of the HTML tags and sends the data to the browser. A value of 2 assigns a mimetype of text/plain and causes the tags inside the content to be rendered in the content frame as plain text.

Value

Mimetype

Stylesheet

Result

0

text/html

dynaweb.wv

Contents of section are displayed as HTML.

1

text/xml

tags.wv

Content is handled by browser; most browsers will prompt for application or save to disk.

2

text/plain

tags.wv

Content (with SGML tags) is displayed as ASCII in content window.

XML Stylesheets

In order to successfully serve out XML from DynaText books, a stylesheet named tags.wv must be added to the styles directory of the book or collection. This stylesheet applies XML style syntax to the existing SGML tags. The tags.wv stylesheet can be located in the styles directories of any of the books included with DynaWeb. The location of one styles directory is under your DynaWeb installation in the ebooks/client/books/client/styles directory. The tags.wv stylesheet passes through the tags from your document using the following four styles:

The tags.wv Stylesheet

The first entry sets the #DEFAULT style to render the tag name and any attributes in text-before and closes the tag in the text-after attribute. This replicates the tag around the contents of the element and allows the tag to be passed on to the XML parser.

<style name="#DEFAULT">
	<text-before>join('<',tag(),if(attrs(),join(' ',attrs()),),'>')</>
	<text-after>join('</',tag(),'>')</>
</style>

The second style takes the #ROOT element (if one exists) and places any attributes it might have as a comment at the top of the output.

<style name="#ROOT">
	<text-before>join('<','!--',if(attrs(), join(' ',attrs()),)) -->
                          char(10)</>
	<text-after> </>
</style>

The last two styles handle the system data (SDATA) and non-character data (NDATA) by converting them to their entity representations.

<style name="#SDATA">
	<text-before>join('&', attr(name), ';') </>
	<text-after> </>
</style>
<style name="#NDATA">
	<text-before>join('&', attr(name), ';') </>
	<text-after> </>
</style>
</sheet>

The xmlpointer PVF

The new PVF, called xmlpointer, handles the transformation of Xpointers into element identifiers (EIDs). The xmlpointer PVF can be used in a DynaWeb URL to specify a position inside a DynaText book.

The syntax of the xmlpointer PVF is:

xmlpointer(Xpointer)

When an Xpointer is given, the xmlpointer PVF returns the EID associated with the Xpointer's target. As a result, DynaWeb serves the nearest significant element (as determined by the TOC stylesheet.) DynaWeb places a named anchor on the specified element in order to display it in the web browser using a fragment-id in the URL.

If the Xpointer would normally return a range of values, xmlpointer will only return the first value in that range. Additionally, if an offset value is returned, the xmlpointer PVF will ignore it and return only the EID of the element. This is a basic limitation of PVF implementation and is also the behavior of other link-related PVFs.

DynaWeb supports the XML conventions for allowing the ID type identifier in an Xpointer, as well as the shorthand notation that assumes an attribute of type ID. Therefore, in DynaWeb, the following three URLs are equivalent.

http://.../book/@Generic__BookView/xmlpointer(ID(Section1))
http://.../book/@Generic__BookView/xmlpointer(Section1)
http://.../book/@Generic__BookView?XML-XPTR=ID(Section1)

For additional information on the XML specification and Xpointers, try the World Wide Web Consortium (http://www.w3.org).

DynaWeb XML Scripts and Templates

DynaWeb uses two scripts to serve out XML from DynaText books. These two scripts are Xml__BookTextView and Xml__GeneratePageText. Essentially, these scripts assign the correct mimetype to the requested data and use the tags.wv stylesheet to format the data using XML syntax.

The preproc.dwc configuration file parses for the xml parameter.

dwSet State_XmlExport [dwGetUrlParam xml [dwGetParam Default_XmlExport]]

It uses the xml parameter's value to generate HTML, XML as plain text, or XML as text/xml.

The script Xml_BookTextView, located in the booktext.dwc configuration file, assigns the appropriate mimetype and sets the current stylesheet to tags.wv. Then the Xml_GeneratePageText script is called. This script passes along all of the data from the currently selected section to the browser until either an end-of-page marker is hit, or dwMaxPageSizeHint is exceeded.

Disabling XML Export in DynaWeb

If you will not be exporting XML from DynaWeb, and you don't want users to be able to specify XML exporting in the URL, you can comment out the line that checks for the xml parameter in the preproc.dwc configuration file. Find the following line in preproc.dwc and comment it out.

dwSet State_XmlExport [dwGetUrlParam xml [dwGetParam Default_XmlExport]]

This will prevent DynaWeb from checking for the xml parameter.


   Creating a Publisher's Thesaurus   [Table of Contents]    Printing From DynaWeb