How An Xml Book Works
<h3 class="heading-h6"><a name="THLToolboxhomegtDevelopersZonegtWebDevelopmentgtXMLBooksgtHowanXMLBookWorks" class="anchorpoint"></a><a href="/tools/wiki/home.html">THL Toolbox</a> > <a href="/tools/wiki/Developers%27%20Zone.html">Developers' Zone</a> > <a href="/tools/wiki/Web%20Development.html">Web Development</a> > <a href="/tools/wiki/XML%20Books.html">XML Books</a> > How an XML Book Works</h3><p class="paragraph">
</p><h3 class="heading-h1"><a name="HowanXMLBookWorks" class="anchorpoint"></a>How an XML Book Works</h3><p class="paragraph"><strong class="bold">Contributor(s)</strong>: Than Grove</p><p class="paragraph">A typical URL to a page of an XML book in THL uses the hash value to trigger an AJAX call to a PHP script that pipes in the output of a Cocoon transformation into a specific portion of the page. The two major types of calls are for a page of the book that goes in the main content body of the html page and for the TOC of the book which goes into the side column.</p><p class="paragraph">An example URL is: <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/bellezza/#!book=/bellezza/wb/b1-1-4/" target="rwikiexternal">http://www.thlib.org/bellezza/#!book=/bellezza/wb/b1-1-4/</a></span></p><p class="paragraph">This goes through a three step process:</p><ol><li>Javascript files interpret the hash value and convert that into two calls, one for the body of the page and one for the TOC. These are respectively:<ul class="star"><li><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/global/php/book_reader.php?url=/bellezza/wb/b1-1-4/" target="rwikiexternal">http://www.thlib.org/global/php/book_reader.php?url=/bellezza/wb/b1-1-4/</a></span></li>
<li><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/global/php/book_reader.php?url=/bellezza/toc/b1-1" target="rwikiexternal">http://www.thlib.org/global/php/book_reader.php?url=/bellezza/toc/b1-1</a></span></li></ul>
</li>
<li>The PHP book reader converts the url parameter into a cocoon call on the localhost (i.e. whatever machine the php script is on) and loads that document from cocoon returning it as the result of the respective ajax call. The Cocoon calls/urls are respectively:<ul class="star"><li><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost:8080/cocoon/texts/books/bellezza/wb/b1-1-4/?v=p" target="rwikiexternal">http://localhost:8080/cocoon/texts/books/bellezza/wb/b1-1-4/?v=p</a></span></li>
<li><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost:8080/cocoon/texts/books/bellezza/toc/b1-1/?v=p" target="rwikiexternal">http://localhost:8080/cocoon/texts/books/bellezza/toc/b1-1/?v=p</a></span></li></ul>
</li>
<li>Cocoon directs the call through a specific pipeline interprets it to determine a source XML file and a XSL transformation to apply. It returns the result usually xhtml.</li></ol><p class="paragraph">
</p><h3 class="heading-h2"><a name="JavascriptFiles" class="anchorpoint"></a>Javascript Files</h3><p class="paragraph">THL uses JQuery as its core JS library and all the custom THL scripts rely on JQuery. The main javascript file for Ajax calls in THL is /global/js/class_external.js. This is used by JIATS, essays, wikis, books, and catalogs. Each of these components also has their own specific JS file. In this case, it is book.js. When a call is made to #!book, these two JS files determine that it is a call for the "Book" component and call the appropriate reader with AJAX calls. The results returned from the PHP reader are inserted in the appropriate place in the page and various formatting/JS manipulation is applied to them after insertion.
</p><h3 class="heading-h2"><a name="PHP" class="anchorpoint"></a>PHP</h3><p class="paragraph">As demonstrated by the urls above the PHP reader for books is /global/php/book_reader.php. The param sent to this script is called "url". It contains the pipeline call for Cocoon. Because Cocoon is a servlet in Tomcat, its URL would normally be <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org:8080/cocoon…" target="rwikiexternal">http://www.thlib.org:8080/cocoon…</a></span> or with an alias <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://texts.thlib.org/." target="rwikiexternal">http://texts.thlib.org/.</a></span> In either case, JS in browsers interpret this as a different server from the host page, <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/…" target="rwikiexternal">http://www.thlib.org/…</a></span> So, any AJAx call to a cocoon page is considered a cross-domain call, which are prohibited for security reasons. AJAX is only allowed to read pages from the same domain as the main page. For this reason, we have created a class of PHP scripts that reside on the same server as the THL pages, in this case <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/global/php/book_reader.php." target="rwikiexternal">http://www.thlib.org/global/php/book_reader.php.</a></span> Using PHP file_get_contents, the Cocoon pipeline can be read and output from the PHP script, thus making it be on the same server as the including page. So, the PHP file acts as an intermediary between the AJAX calls and the Cocoon Transformations.
</p><h3 class="heading-h2"><a name="Cocoon" class="anchorpoint"></a>Cocoon</h3><p class="paragraph">Cocoon works on the model of pipelines. A pipeline is a action defined by a url. Pipelines are defined in a project specific document with the name sitemap.xmp that resides at the top level of the project. In THL's version of Cocoon, sitemaps have been set up to be cascading. That is, there is an overall general Cocoon sitemap at <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost:8080/cocoon/texts/sitemap.xmap" target="rwikiexternal">http://localhost:8080/cocoon/texts/sitemap.xmap</a></span> that defines general pipelines. Then, each THL Cocoon project has it's own subfolder so that the sitemap for books is at <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost:8080/cocoon/texts/books/sitemap.xmap." target="rwikiexternal">http://localhost:8080/cocoon/texts/books/sitemap.xmap.</a></span> The more specific sitemap takes precedent over the more general one. In the present example of book, the call for the body of the page is <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost:8080/cocoon/texts/books/bellezza/wb/b1-1-4/." target="rwikiexternal">http://localhost:8080/cocoon/texts/books/bellezza/wb/b1-1-4/.</a></span> The beginning of the URL up to and including /books/ determines that it is in the book project and invokes the /books/sitemap.xmap. The rest of the URL triggers the following pipeline in that sitemap.xmap file:</p><div class="code"><pre><!-- Chapter <span class="java-keyword">for</span> wholebook texts where all book is in one file -->
<map:match pattern=<span class="java-quote">"*/wb/*/"</span>>
<map:generate src=<span class="java-quote">"xml/{1}/main.xml"</span>/>
<map:transform src=<span class="java-quote">"xsl/book-chapter.xsl"</span>>
<map:parameter name=<span class="java-quote">"bkid"</span> value=<span class="java-quote">"{1}"</span>/>
<map:parameter name=<span class="java-quote">"cid"</span> value=<span class="java-quote">"{2}"</span>/>
</map:transform>
<map:serialize type=<span class="java-quote">"html"</span>/>
</map:match></pre></div><p class="paragraph">In this pipeline, the first asterisk (*) in the pattern becomes {1} in the src and value attributes, while the second becomes {2}. So, in our example call, the XML file "generated" would be /books/xml/bellezza/main.xml. There are two type of books in THL, books where the main.xml file is only a structural TOC of the book and contains no contents but instead has links to separate files that contain each of the individual sections and books where the "whole book" is contained in a single document. Pipelines with /wb/ in them are for the later type of book. (An example of the first type would be the Tibetan Literary Genres book.) To this XML file, the XSL file at books/xsl/book-chapter.xsl is applied and the results are "serlialized" as html.
</p><h3 class="heading-h6"><a name="ProvidedforunrestrictedusebythespanclassnobrimgsrcsakairwikitoolimagesicklearrowgifaltexternallinktitleexternallinkahrefhttpwwwthliborgtargetrwikiexternalTibetanandHimalayanLibraryaspan" class="anchorpoint"></a><em class="italic">Provided for unrestricted use by the <span class="nobr"><img src="/" alt="external link: " title="external link"/><a href="http://www.thlib.org" target="rwikiexternal">Tibetan and Himalayan Library</a></span></em></h3>