Solprovider Apache Lenya


		Definition of DocTypes

<< Apache Lenya >>
Start
Basics
Contents
Document
XMAPs (Sitemaps)
Nesting
Breakpoints
Usecase Sitemaps
Lenya Process
DocTypes
Variables
Language
Site Design
XSP
Advanced
Search
Flow
CMS GUI
Kupu
Suggestions
Other
Sitemap

The phrase "doctypes" has 2 definitions within Lenya. The first is data formats, referred to as "Custom Doctypes" or "Resource Types". The second allows different displays of data by overloading the "doctype parameter".

"Custom Doctypes" are used when you want different fields than the standard Lenya document. If you want to display information about products, you could create a Custom Doctype with fields, such as:
ProductId
ProductName
ProductDescription
ProductPrice

Deciding the Doctype

Doctype is decided in "{pub}/parameter-doctype.xmap". This value is decided first by URL matching. The default is for "*.html" to use the "sourcetype" Action, which translates the root element of the target XML document. So you can decide the doctype by either the URL or the XML of the target.

WARNING: Lenya decides the doctype once for each document, and then caches it. If you want to use different stylesheets for the same target, see Using Multiple Stylesheets for the Same Content.

Deciding the Doctype from the XML of the target

If your Custom Doctype has a unique root element, you can set it by adding a namespace to the SourceTypeAction action:

      <map:action logger="sitemap.action.sourcetype" name="sourcetype" src="org.apache.cocoon.acting.sourcetype.SourceTypeAction">

...

        <sourcetype name="myDocType">

           <document-element local-name="myRootElement">

        </sourcetype>

      </map:action>ccccc



While the package name for the SourceTypeAction makes it appear to be from the Cocoon project, it is from the Forrest project.  To see the code and read some good documentation about its uses, download Forrest.  See the documentation to learn how to create rules for deciding doctype based on the "public id", the schema namespace, or a "processing instruction".  These allow great flexibility, and using one of them is required if you want multiple doctypes with the same root element.



      <map:action logger="sitemap.action.sourcetype" name="sourcetype" src="org.apache.cocoon.acting.sourcetype.SourceTypeAction">

        <sourcetype name="mySourceType1">

RULES

       </sourcetype>

        <sourcetype name="mySourceType2">

RULES

       </sourcetype>

...

      </map:action>



All rules must be satisified for a match.



The first sourcetype to match wins.  They should be processed in the order of the configuration.



The Rules are:

<document-declaration public-id="xxx">

This matches the string immediately after PUBLIC in a DOCTYPE tag.

<!DOCTYPE example PUBLIC "myPublicID" ...>



<processing-instruction target="targetName">

matches

<?targetName all this is data?>



<processing-instruction target="targetName" data="zzz">

matches

<?targetName zzz?>

I could not discover if the data is trimmed before comparison.  I assume the first space is ignored as the separator.



No tags after the first element are considered.  That means processing instructions are only considered if they are placed before the first element.  



<w3c-xml-schema schema-location="http://www.w3.org/1999/XSL/Transform">

matches:

<myTag xsi:schemaLocation="http://www.w3.org/1999/XSL/Transform">

xsi:schemaLocation may have multiple values separated by whitespace.  This rule matches using java.lang.String.equals(), so a variation in the whitepace would fail.



<w3c-xml-schema no-namespace-schema-location="zzz">

matches:

<myTag xsi:noNamespaceSchemaLocation="mySchema.xsd">



<w3c-xml-schema schema-location="xxx" no-namespace-schema-location="zzz">

Combines the last two rules.



xsi:schemaLocation and xsi:noNamespaceSchemaLocation may be placed on any tag, but may appear only once in a document.  No tags after the first element are used, so they will only be considered if they are attributes of the first element.



<document-element local-name="mytag"/>

Checks the local name is the first element of the document, so <myns:mytag>

would match.

<document-element namespace="http://www.w3.org/1999/xhtml"/>
Checks the xmlns attribute of the first element, so
<html xmlns="http://www.w3.org/1999/xhtml" ...>
would match.

<document-element local-name="xxx" namespace="http://www.w3.org/1999/xhtml"/>
Combines the last two rules.

Deciding the Doctype from the URL requested

The doctype can be overridden based on the URL. Lenya uses this to force {pub}/index_xx.html to be the "homepage"doctype. The XML for the homepage content is a standard Lenya document, but the XSL processing using different files.

      <map:match pattern="*/mySpecialArea/**.html">

        <map:generate type="serverpages" src="../../config/parameters/default.xsp">

          <map:parameter name="value" value="mySpecialDoctype"/>

        </map:generate>

        <map:serialize type="xml"/>

      </map:match>

XSL Transformation

An XML document with these fields requires different processing than a standard Lenya document, so you use the "doctype parameter" to specify different XSL. That value is then used by "{pub}/publication-sitemap.xmap" to choose the XSLT.

There are usually two stylesheets for a Custom Doctype:
1. "mydoctype2xtml.xsl" is used to convert non-standard XML to XHTML. Use it to turn your custom XML into displayable HTML. Lenya expects the content to be in an element <div id="body">.

2. "page2xhtml-mydoctype.xsl" is used to add the navigation elements. It is called after the content is aggregated with various navigation XHTML, such as menus and search. If the page layout is the same as your basic website, use:

<?xml version="1.0"?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:import href="page2xhtml.xsl"/>

</xsl:stylesheet>

Usage Instructions

1. (Optional) Create custom XML.
2. Modify {pub}/parameter-doctype.xmap to return a different value.
3. (Optional) Create file {pub}/xslt/{myDoctype}2xhtml.xsl to create XHTML with a <div id="body"> element.
4. Create file {pub}/xslt/page2xhtml-MyLayoutType.xsl to layout the content and navigation for display.

Usage Instructions

To see what doctype is being set, temporarily add this to the top of the pipelines in publication-sitemap.xml:

        <map:match pattern="**">

           <map:generate src="../../content/util/empty.xml"/>

           <map:transform src="variables.xsl">

          <map:parameter name="doctype" value="{page-envelope:document-type}"/>

           </map:transform>

           <map:serialize type="html"/>

       </map:match>

variables.xsl:

<?xml version="1.0" encoding="UTF-8" ?>

<xsl:stylesheet version="1.0"

   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

   xmlns="http://www.w3.org/1999/xhtml"

   xmlns:xhtml="http://www.w3.org/1999/xhtml">

<xsl:param name="doctype"/>

<xsl:template match="/">

<html><body>

DOCTYPE=<xsl:value-of select="$doctype"/>

</body></html>

</xsl:template>

<< Lenya Process

Content >>

Contact Solprovider

Definition of DocTypes

Deciding the Doctype

Deciding the Doctype from the XML of the target

Deciding the Doctype from the URL requested

XSL Transformation

Usage Instructions

Usage Instructions

Paul Ercolino