templates.xml

The templates.xml from the webproject defines which delivery templates are used for which document types.

Overview

URLs are interpreted by the delivery. An URL contains values for the document type, the channel and the template type.

The templates.xml from the webproject (location /WEB-INF/templates/sitename/templates.xml) defines which delivery templates are used for which document types. You can also define default templates as well as overwrite them. For each website there has to be at least one templates.xml file. It is possible to assign separate templates.xml files for different parts, e.g. structure nodes, of the website. For each delivery channel and each node type a template set can be configured which may be derived from a default template set.

Basics

Doctype of the templates.xml

<!DOCTYPE config [
    <!ELEMENT config (nodetypelist, templatesets, shortcutlist)>
    <!ATTLIST config     extending CDATA #IMPLIED
                extends CDATA #IMPLIED>
    <!ELEMENT templatesets (templateset*)>
    <!ELEMENT shortcutlist (shortcut*)>
    <!ELEMENT shortcut (path*)>
    <!ATTLIST shortcut   type CDATA #REQUIRED
                externalId CDATA #IMPLIED
                sophoraId CDATA #IMPLIED
                uuid CDATA #IMPLIED
                staticUrl CDATA #IMPLIED
                                structurePath CDATA #IMPLIED
                url CDATA #IMPLIED>
    <!ELEMENT path (#PCDATA)>
    <!ATTLIST path   regExp  CDATA #IMPLIED>
    <!ELEMENT nodetypelist (nodetype*)>
    <!ELEMENT nodetype (templateset*)>
    <!ATTLIST nodetype name CDATA #REQUIRED>
    <!ELEMENT templateset (template*)>
    <!ATTLIST templateset    extends CDATA #IMPLIED
                channel CDATA #IMPLIED
                name CDATA #IMPLIED>
    <!ELEMENT template (#PCDATA)>
    <!ATTLIST template   type CDATA #IMPLIED>
        <!ATTLIST template   suffix CDATA #IMPLIED>
]>

Description of the Tags

<config>
The root tag of the templates.xml

Attributes:

extends - Specifies from which other templates.xml this one inherits
extending - Determines whether an inheritance is to be made or not (default: true)

<nodetypelist>
Contains a list of all node types (<nodetype> elements) there are templates defined for.

Attributes:

[none]

<nodetype>
Contains all template sets (<templateset> elements) that are defined for this node type.

Attributes:

name - The node type's name.

<templateset>
Contains a list of actual templates (<template> elements).

Attributes:

name - The name of the template set.
channel - The name of the delivery channel for which this template set is valid. You can add several channel names separated by comma to make this template set apply to several channels.
extends - The name of the template set that this template set extends (inherits from).

The extends attribute might as well hold a comma separated list of base template set names. This allows a finer division into shared default template sets.

Multi-inheritance of template sets requires sophora delivery version 2.3.1, 2.4.0 or newer.

The extends attribute is without effect on default template sets thus <templateset> nodes not being child of a <nodetype> element.

<template>
A template contains the path to an according template JSP file.

Attributes:

type - The name of the template type.
suffix - The URL's suffix

<templatesets>
Contains a list of template sets (<templateset> elements) that are used as default.

Attributes:

[none]

<shortcutlist>
Contains the list of all shortcuts (<shortcut> elements).

Attributes:

[none]

<shortcut>
A shortcut path (<path>).

Attributes:

type - Valid values: ssi, metaRedirect, redirect, mapping
url - Target URL; e.g. http://www.sophoracms.com
staticUrl - Target template; e.g. /sitename/story.jsp
sophoraId - The Sophora ID of the document for which the URL is generated; e.g. "story100".
externalId - The external ID of a document for which the URL is generated; e.g. "extern-1234".
uuid - The UUID of a document for which the URL is generated; e.g. "aaee0dd8-4fd7-4f1a-ae0c-0dc445bd0dfc".
structurePath - Can be used to map old, non existent paths with existing structure paths. The file name is retained.

The definition of shortcuts in the templates.xml is disadvised, since shortcuts can also be maintained in the Deskclient. For further information see Redirects.

<path>
A path.

Attributes:

[none]

URL Schema

defaultSophoraCodec

<sitename>[~<channelname>]/[<structurenodename>/]*<sophora-id>[~[<type>][_<key>-<value>]*].html

If the optional attributes "channelname" and "type" are not given, the value "default" is assgined to both of them automatically.

Underscores in the value of a URL parameter will automatically be encoded/decoded as double-underscores in order to differentiate from the single underscore as parameter separator.

Implementation of a project specific URL Schema

To implement your own URL scheme, the following configurations must be done.

Enabling Function Usage

You need to add the sophora.delivery.function.packageNames key to your sophora.properties. Add the Java package names containing your function classes as a comma-separated list:sophora.delivery.function.packageNames=com.example.basicfunction, ...

Create your Url-Codec class

Below this package names you can create a Java class that extends from AbstractUrlCodec. Use the annotation UrlCodec for setting the name of your URL-Codec, and overwrite the String encode(SophoraUrl url) and SophoraUrl decode(String url) method.

@UrlCodec("exampleUrlCodec")
public final class ExampleSophoraUrlCodec extends AbstractUrlCodec {}

Now configuring the name of your URL-Codec in sophora.properties by setting the property sophora.delivery.urlCodec.name:
sophora.delivery.urlCodec.name=exampleUrlCodec

index.html

If a URL contains the string "index" within the Sophora ID, it will be checked whether there is a structure node according to the path. If that is the case, the node type is set to "sophora-nt:structureNode2". If no corresponding structure node exists, the shortcuts are checked whether there is an according reference and if a match was found, the node type is set to "sophora-nt:shortcut". At last, if no shortcut is defined, the delivery returns a 404 error.

An exemplary templates.xml

<config>
    <!-- Template sets for certain document types -->
    <nodetypelist>
        <nodetype name="sophora-content-nt:story">
            <templateset extends="default" channel="rss" />
            <templateset extends="default">
                <template type="default">/sitename/story.jsp</template>
                <template type="default" suffix="xml">/sitename/xml.jsp</template>
                <template type="teaser">/sitename/topteaser.jsp</template>
            </templateset>
        </nodetype>
        <nodetype name="sophora-content-nt:image">
            <templateset>
                <template type="default">/sitename/templates/media/image.jspx</template>
            </templateset>
        </nodetype>
    </nodetypelist>
    <!-- Default template sets-->
    <templatesets>
        <templateset name="default" channel="rss">
            <template type="default">/sitename/rss.jsp</template>
        </templateset>
        <templateset name="default">
            <template type="default">/sitename/index.jsp</template>
            <template type="content">/sitename/content.jsp</template>
            <template type="teaser">/sitename/teaser.jsp</template>
        </templateset>
    </templatesets>
    <!-- Shortcuts -->
    <shortcutlist>
    </shortcutlist>
</config>

In the example above the standard JSP templates for the types "default", "content" and "teaser" are defined for the delivery channel "default" within the <templatesets> element. For the channel "rss" has also been set a JSP for the type "default" (called "rss.jsp").

These default configurations are overwritten for the node type "sophora-content-nt:story" in the following way:

The default delivery channel should use the site's "story.jsp" as "default" type and the site's "topteaser.jsp" for the type "teaser".
The "rss" delivery channel retains the default configuration.

For the document type "sophora-content-nt:image" the "image.jspx" file from the templates/media/ directory is defined as default

Some exemplary URLs and the resulting operations are given below as they would occure when applying the configuration from the example above. Here, "story100" is the Sophora ID of a document of the type "sophora-content-nt:story". If the attributes "type" and "channel" are not given in the URL, both variables are set to "default".

URL: sitename/story100.html

For the document type "sophora-content-nt:story" it will be looked up in the templates.xml whether a template set for the default delivery channel exists for this node type.
Afterwards it will be checked whether this template set contains a template for the type "default".
If such a template exists, the sitename/story.jsp is called.

URL: sitename/story100-teaser.html

For the document type "sophora-content-nt:story" it will be looked up in the templates.xml whether a template set for the default delivery channel exists for this node type.
Afterwards it will be checked whether this template set contains a template for the type "teaser".
If such a template exists, the sitename/topteaser.jsp is called.

URL: sitename/story100-content.html

For the document type "sophora-content-nt:story" it will be looked up in the templates.xml whether a template set for the default delivery channel exists for this node type.
Afterwards it will be checked whether this template set contains a template for the type "content".
Since no template of the type "content" exists in the template set, it is checked whether this template set is derived from a default template set.
The template sets is indeed derived from the template set "default" for the default channel so that this template set is searched for a template of the type "content".
Finally, the default template sitename/content.jsp is called as specified in the superior template set.

URL: sitename~rss/story100.html

For the document type "sophora-content-nt:story" it will be looked up in the templates.xml whether a template set for the delivery channel "rss" exists for this node type.
Afterwards it will be checked whether this template set contains a template for the type "default".
Because no "default" template exists in the template set, it is checked whether this template set is derived from a default template set.
The template sets is indeed derived from the template set "default" for the "rss" channel so that this template set is searched for a template of the type "default".
Finally, the template sitename/rss.jsp is called as specified in the superior template set.

Overwriting Template Configurations on Structure Node Level

It is possible to overwrite the configuration of certain structure nodes.

Example:

All requests to strucutre nodes that are not located at "/structurenodename" for "sophora-content-nt:story"-documents (with the default template type) are redirected to the "/sitename/story.jsp" of the Website "website".

Structure nodes located at "/structurenodename" point to "/sitename/other_story.jsp" for the corresponding requests. Request for the template type "teaser" will still be redirected to /sitename/teaser.jsp, because only the template for template type "default" is defined in the overwriting definition. If you want to stop the inheritance for "/structurenodename", then please use the attribute extending="false" at config element in the file "/sitename/structurenodename/templates.xml".

File "/sitename/templates.xml":

<config>
    <!-- Template sets for certain document types -->
    <nodetypelist>
        <nodetype name="sophora-content-nt:story">
            <templateset>
                <template type="default">/sitename/story.jsp</template>
                <template type="teaser">/sitename/teaser.jsp</template>
            </templateset>
        <nodetype>
    </nodetypelist>
    <!-- Default template sets -->
    <templatesets>
    </templatesets>
     <!-- Shortcuts -->
    <shortcutlist>
    </shortcutlist>
</config>

File "/sitename/structurenodename/templates.xml":

<config>
    <!-- Template sets for certain document types -->
    <nodetypelist>
        <nodetype name="sophora-content-nt:story">
            <templateset>
                <template type="default">/sitename/other_story.jsp</template>
            </templateset>
        </nodetype>
    </nodetypelist>
    <!-- Default template sets -->
    <templatesets>
    </templatesets>
    <!-- Shortcuts -->
    <shortcutlist>
    </shortcutlist>
</config>

The same behaviour is possible with a root templates.xml put under "/templates.xml". Every templates.xml of a structure node or a site will overwrite and inherit from the root templates.xml.

Reusing Existing templates.xml Files in Other Sites

For a website, an entire templates.xml of a different site may be used. Therefore, the "extends" attribute of the config tag has to be filled in:

<config extends="/otherSitename">
    <!-- Template sets for certain document types -->
    <nodetypelist>
    </nodetypelist>
    <!-- Default template sets -->
    <templatesets>
    </templatesets>
    <!-- Shortcuts -->
    <shortcutlist>
    </shortcutlist>
</config>

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.