[Cocoon Lenya Wiki] New: PublicationTemplating

[le...@cocoon.apache.org]

   Date: 2004-09-08T01:48:16
   Editor: AndreasHartmann <an...@apache.org>
   Wiki: Cocoon Lenya Wiki
   Page: PublicationTemplating
   URL: http://wiki.apache.org/cocoon-lenya/PublicationTemplating

   no comment

New Page:

'''Note:''' This feature is available only in Lenya 1.4.

This document describes a mechanism of publication templating using the fallback concept.
Because it is included in the existing fallback mechanism, files delivered by the core
(e.g., usecase-*.xmap and the navigation framework) support publication templating out
of the box.


=== What is Publication Templating? ===

Imagine you are a company or organisation with some departments which want to edit their
content using a Lenya-based CMS. All departments use similar publications, sharing lots
of functionality. The layout is based on a common corporate identity, but some departments
want to use their own logo or tweak the navigation menu style.

If all departments develop their own publications, it will be very hard to keep them
consistent, to add changes to all publications or to update them to a newer Lenya version.
This can be simplified using publication templates. You define a base (template) publication
which all others are derived from.

{{{
                        +----------------------+
                        | Template Publication |
                        +----------------------+
                                    |
           +-----------------+------+---------------------+
           |                 |                            |
   +--------------+  +--------------+             +--------------+
   | Department A |  | Department B |     ...     | Department X |
   +--------------+  +--------------+             +--------------+
}}}

Multiple layers of templates are supported.

{{{
                    +--------------------------------+
                    | University Website Publication |
                    +--------------------------------+
                                    |
           +-----------------+------+------------------------+
           |                 |                               |
   +------------+  +--------------------+             +-------------+
   | Uni Zurich |  | Harvard University |     ...     | UC Berkeley |
   +------------+  +--------------------+             +-------------+
                             |
              +----------+---+-----------+
              |          |               |
        +----------+  +-----+       +---------+
        | Business |  | Law |  ...  | Medical |
        +----------+  +-----+       +---------+
}}}


=== The Concept of Publication Templating ===

 * There is a publication {{{my-pub}}}.
 * It depends on a template which is called {{{template(my-pub)}}}.
 * When a file is requested using the templating mechanism ({{{fallback:xslt/page2xhtml.xsl}}}), it is searched in a certain traversing order:
  * {{{context://lenya/pubs/my-pub/xslt/page2xhtml.xsl}}}
  * {{{context://lenya/pubs/template(my-pub)/xslt/page2xhtml.xsl}}}
  * {{{context://lenya/pubs/template(template(my-pub))/xslt/page2xhtml.xsl}}}
  * ...
  * {{{context://xslt/page2xhtml.xsl}}}

Note that, in contrast to the existing fallback mechanism, the prefix {{{lenya}}} is not used,
but the path is resolved relatively to the {{{context://}}} root.

=== Declaration of a Template ===

 * The template of a publication is declared in {{{my-pub/config/publication.xconf}}}:

 {{{
<publication>
  ...
  <templates>
    <template id="my-template"/>
  </templates>
  ...
</publication>
}}}

=== Usage ===

To invoke publication templating, it is necessary to apply the fallback module on all relevant files.
For an XSLT stylesheet, the according pipeline looks as follows:

 {{{
<map:transform src="{fallback:xslt/doctypes/doctype2xhtml.xsl}">
}}}

=== XSLT Include and Import ===

To leverage the publication templating concept, it is necessary to apply it to included or imported
stylesheets as well. Fortunately, we can make use of the {{{cocoon:/}}} protocol in XSLT stylesheets:

 {{{
<xsl:include href="cocoon:/xslt/common/header.xsl"/>
}}}

This requires a pipeline matching the {{{**.xsl}}} requests:

 {{{
<map:pipeline internal-only="true">
  <map:match pattern="**.xsl">
    <map:generate src="{fallback:{1}.xsl}"/>
    <map:serialize type="xml"/>
  </map:match>
</map:pipeline>
}}}

Actually, this pipeline could even be provided by the core and requested using
a {{{cocoon://}}} (with double slash) call:

 {{{
<xsl:include href="cocoon://xslt/common/header.xsl"/>
}}}

To simplify overriding of XSLT stylesheets, it would be useful to import
the template stylesheet. For this purpose, an additional {{{template}}}
input module could be used, which skips the current publication when
resolving the file:

 {{{
<xsl:import href="cocoon:/template/xslt/common/header.xsl"/>
}}}

 {{{
  <map:match pattern="template/**.xsl">
    <map:generate src="{template:{1}.xsl}"/>
    <map:serialize type="xml"/>
  </map:match>
}}}

=== Sitemaps ===

If a sitemap is loaded from a template publication, it is very important that the sitemap
is completely fallback-enabled. Otherwise, the source resolver will resolve sources relatively
to the template sitemap instead of using the overridden ones.

In {{{lenya/global-sitemap.xmap}}}, all publication sitemaps have to be mounted
using the fallback module, for instance

 {{{
<!-- Enter the actual publication -->
<map:match pattern="*/**">
  <map:mount uri-prefix="{1}" src="{fallback:sitemap.xmap}"/>
</map:match>
}}}

=== Usecases ===

The traversing order for usecase sitemaps is

 * {{{context://lenya/pubs/my-pub/usecase.xmap}}}
 * {{{context://lenya/pubs/template(my-pub)/usecase.xmap}}}
 * {{{context://lenya/pubs/template(template(my-pub))/usecase.xmap}}}
 * ...
 * {{{context://lenya/usecase.xmap}}}

This behaviour is achieved by the usecase fallback module
which is called in {{{global-sitemap.xmap}}}:

 {{{
<map:match type="usecase" pattern="*">
  <map:mount src="{usecase-fallback:{1}}" uri-prefix=""/>
</map:match>
}}}

The decision which {{{usecase.xmap}}} to choose is based on the
usecase configuration in {{{publication.xconf}}}. To declare a
usecase to be implemented by a publication, add the corresponding
entry:

 {{{
<publication>
  ...
  <usecases>
    <usecase name="create"/>
  </usecases>
  ...
</publication>
}}}


---------------------------------------------------------------------
To unsubscribe, e-mail: lenya-dev-unsubscribe@cocoon.apache.org
For additional commands, e-mail: lenya-dev-help@cocoon.apache.org