Commit 0e70503a authored by Wolfgang's avatar Wolfgang

Add documentation section about embedding TEI Publisher webcomponents

parent 9ee49231
......@@ -2551,6 +2551,62 @@ declare function pmf:code($config as map(*), $node as element(), $class as xs:st
</section>
</section>
</section>
<section>
<title>Embedding TEI Publisher Output</title>
<para>Sometimes you may already have a website based on a CMS like WordPress, Drupal etc. into which you would like to embed HTML output generated by TEI
Publisher. This is done easily in a number of ways. For sure it requires that you have a TEI Publisher instance running somewhere, into which you can
upload TEI documents. It does not need to be on the same server though.</para>
<section>
<title>Retrieving a whole document as HTML</title>
<para>The simplest case would be to retrieve the entire content of a TEI document as HTML, transformed through an ODD with processing instructions. Behind
the scenes, TEI Publisher has two parts: a library part, which is essentially an implementation of the TEI processing model, and the application part,
which adds user interface elements and other functionality around the library. The library part can be used independently. All you need is a small
XQuery which calls the library modules, setting the correct source document and ODD. Fortunately, TEI Publisher already contains a boilerplate XQuery
script for this job, which you can call as follows in your browser:</para>
<para><link xlink:href="https://teipublisher.com/exist/apps/tei-publisher/modules/lib/transform.xql?doc=test/F-rom.xml&amp;odd=shakespeare.odd">https://teipublisher.com/exist/apps/tei-publisher/modules/lib/transform.xql?doc=test/F-rom.xml&amp;odd=shakespeare.odd</link></para>
<para>This will retrieve the content of Shakespeare's <citetitle>Romeo and Juliet</citetitle> as an HTML page, transformed through the odd
<filename>shakespeare.odd</filename>. For embedding an entire document in an iframe or similar, this should already be enough.</para>
</section>
<section>
<title>Embedding webcomponents for navigation</title>
<para>For longer documents, embedding the entire content in a page may not be too user-friendly. A better way is to use the library of webcomponents
provided by TEI Publisher. This way, we can show the content page by page or division by division, allowing the reader to navigate between
sections.</para>
<para>Because webcomponents are part of the HTML5 standard and supported natively by most modern browsers, we can easily import the component library
which is at the core of the TEI Publisher app and reuse the components it provides in other contexts. They should work in any HTML5 page, no matter if
it was written by hand, is generated by PHP, Python or a CMS.</para>
<para>For a start, the page should import two things in its header:</para>
<programlisting language="html" xml:space="preserve"><![CDATA[<script src="https://teipublisher.com/exist/apps/tei-publisher/components/bower_components/webcomponentsjs/webcomponents-loader.js"></script>
<link rel="import" href="https://teipublisher.com/exist/apps/tei-publisher/components/dependencies-dev.html"/>]]></programlisting>
<para>The <tag>script</tag> tag should come first. It loads a thin compatibility layer for those browsers which do not fully support the webcomponents
standard. The <tag>link</tag> tag then imports all the components provided by TEI Publisher and their dependencies.</para>
<para>In the example we're loading both from the TEI Publisher website. If you have set up your own instance of eXist-db and TEI Publisher, you should
change the URL <emphasis>to point to your instance</emphasis>. This is important because the components will expect the documents you want to display to
be stored in the same instance.</para>
<para>Now let's actually use the components to display Shakespeare's <citetitle>Romeo and Juliet</citetitle>: in the HTML <tag>body</tag>, include the
following snippet: </para>
<programlisting language="html" xml:space="preserve">&lt;pb-document id="document1" path="test/F-rom.xml" odd="shakespeare">&lt;/pb-document>
&lt;!-- Navigate to previous page -->
&lt;pb-navigation direction="backward" unit="page" keyboard="left">
&lt;paper-fab icon="icons:chevron-left">&lt;/paper-fab>
&lt;/pb-navigation>
&lt;pb-view id="view1" src="document1" view="page">&lt;/pb-view>
&lt;!-- Navigate to next page -->
&lt;pb-navigation direction="forward" unit="page" keyboard="right">
&lt;paper-fab icon="icons:chevron-right">&lt;/paper-fab>
&lt;/pb-navigation></programlisting>
<para><tag>pb-document</tag> defines the document to be displayed. The path is relative to the data root of the TEI Publisher instance. It also specifies
the ODD to be used for the transformation.</para>
<para><tag>pb-view</tag> is the main component for displaying the transformed content. It references the <tag>pb-document</tag> to use as source in its
<option>src</option> attribute. The Shakespeare does tag page breaks, so we switch to page-by-page view via the <option>view</option> attribute to
show the user only one page at a time. The default would be to use a division-by-division view (<code>view="div"</code>), but you could also request the
entire content at once using <code>view="single"</code>.</para>
<para><tag>pb-navigation</tag> adds forward/backward navigation buttons to the page, allowing the user to switch to the next/previous page of the
document. You can use various types of buttons, but in this case we're choosing a <tag>paper-fab</tag> element, which creates a rounded, floating button
(<tag>paper-fab</tag> is part of the standard <link xlink:href="https://www.webcomponents.org/element/@polymer/paper-fab">components library</link>).</para>
<para>Please have a look at the <link xlink:href="../embed.html">working example page</link> to see everything in action and read through its <link xlink:href="embed.html" role="source">source code</link>.</para>
</section>
</section>
......
......@@ -6,32 +6,32 @@
<title>Embedding pb-view</title>
<script src="http://localhost:8080/exist/apps/tei-publisher/components/bower_components/webcomponentsjs/webcomponents-loader.js"></script>
<link rel="import" href="http://localhost:8080/exist/apps/tei-publisher/components/dependencies-dev.html"/>
<custom-style>
<style is="custom-style" include="pb-common-styles">
body {
margin: 60px 20px;
}
main {
display: flex;
justify-content: space-between;
}
pb-navigation {
margin-top: 50vh;
}
#toc h1 {
font-size: 16px;
}
</style>
</custom-style>
<style>
body {
margin: 0 20px;
}
main {
display: flex;
justify-content: space-between;
}
pb-navigation {
margin-top: 50vh;
}
#toc h1 {
font-size: 16px;
}
#toc ul {
list-style: none;
padding-left: 0;
}
</style>
</head>
<body>
<pb-document id="document1" path="test/F-rom.xml" odd="shakespeare"></pb-document>
<h1>Embedding TEI Publisher Output</h1>
<p>This page demonstrates how to embed TEI Publisher webcomponents into a standalone HTML page to display
pages of a TEI document. For this to work, TEI Publisher needs to run somewhere on a server, so we can load
the components from there.</p>
pages of a TEI document.</p>
<main>
<pb-load id="toc" auto url="../templates/toc.html" src="document1" load-once="load-once">Loading ...</pb-load>
<!-- Navigate to previous page -->
<pb-navigation direction="backward" unit="page" keyboard="left">
<paper-fab icon="icons:chevron-left"></paper-fab>
......@@ -41,6 +41,10 @@
<pb-navigation direction="forward" unit="page" keyboard="right">
<paper-fab icon="icons:chevron-right"></paper-fab>
</pb-navigation>
<div id="toc">
<h3>Table of Contents</h3>
<pb-load auto="auto" url="../templates/toc.html" src="document1" load-once="load-once">Loading ...</pb-load>
</div>
</main>
</body>
</html>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment