The Foundry Theming Engine for LibreCCM

The Foundry Theme Engine for LibreCCM

Overview

About Foundry

Foundry is a theme engine for the LibreCCM family of Content Management systems, for example ScientificCMS and APLAWS+. Some parts of based on the Mandalay theme engine developed by Sören Bernstein for ScientificCMS.

With Foundry the designer has full control of the HTML created from the content managed by CCM. The templates for defining the HTML are almost plain HTML (in XML syntax) with some additional elements which provide the data to display.

This manual

This manual is separated into two parts. The first part is for designers and administrators (called users in the context of this manual). It describes the structure of the templates in Foundry, how CSS files are implemented and how Frameworks like Bootstrap, YAML or jQuery can be integrated into a Foundry theme. The first part also contains a reference part which describes all elements/tags which can be used in the templates. If you are viewing this documentation using an URL like /themes/foundry/doc/ this reference is created on the fly from the XSL files.

The second part is for developers which want to extend Foundry. It describes the structure of Foundry, how support for content types (the most common task) can be added, how the documentation system works and which XPath functions and XSL helper templates are available. Developers should also read the first part because the first part includes informations about the general structure of Foundry.

In the manual the following terms a used quite often:

context prefix
The context in which CCM is installed in the Servlet container. If CCM is installed in the root context the context prefix is empty.
theme prefix
The URL part of accessing resources inside the theme. For example for theme called foo the theme prefix is /themes/published-themedir/foo is published theme is used an if CCM is installed in the root context.
dispatcher prefix
The URL for creating links to other CCM resources like content items. Depends on the context in which CCM is installed and if development theme or the published theme is used.
data tree
The XML created by CCM containing all data of the current page.
Layout tree
The XML of layout template in processing.

User Manual

General structure

There some options for using Foundry. The easiest way is to use a version/package of LibreCCM which includes Foundry. In this case Foundry is installed in the /themes/foundry folder. There should also be a second folder named /themes/foundry-base which includes a basic child theme.

Foundry supports a an parent/child theme approach. This means that the logic part of Foundry (the XSL part) is only installed in /themes/foundry and is updated together with the normal upgrades of CCM. A child only contains the templates, CSS files, static texts and configurations files for a theme. Custom extensions are not supported yet.

A complete Foundry theme consists of the following top level folders and files:

conf
Contains configuration files for the theme
doc
Static parts of the documentation of Foundry, for example this text
fonts
Web fonts for the theme
foundry
This folder contains the logic parts (the XSL) of Foundry. The internal structure is described in the Developer Manual.
images
Static images for the theme
libs
Additional JavaScript libraries. jQuery and some other JavaScript libraries are provided by CCM itself, and can be included using special elements like the load-jquery element.
scripts
JavaScripts needed in the theme.
styles
The CSS styles for the theme. More information about them can be found in the CSS files section.
templates
The layout templates for the theme. A detailed description can be found in the Layout templates section.
texts
Static texts for the theme
user
Custom extensions (XSL) for theme. Not supported yet.

Foundry also supports a parent – child – grandchild structure. This is maybe useful when you have themes which only differ in details like logos but use the same general structure. Most tags which are used to include resources like images, CSS files etc. support the attribute origin which can have three values:

Not set
The resource is loaded from the current theme
master
If the current theme is a master/parent theme the resource is loaded from the current theme. If the current theme is a child theme the resource is loaded from the master theme.
internal
The file is loaded from the foundry. If the theme is a child theme is file is loaded from the Foundry master in /themes/foundry.

The recommend way for creating a team using Foundry is to create a new child theme:

  1. To do so create a new theme using the CCM Theme director.
  2. Copy the contents of the themes/foundry-base folder to the folder created by the new theme in themes/devel-themedir/.
  3. Customise the theme

Layout templates

The layout templates are used by the web designer to create the HTML of the web page. With Foundry the designer has almost complete control over the HTML. Despite the elements which correspond to HTML 5 elements most other elements which can be used in the templates do not create HTML. A complete list of the elements which can be used in the layout templates can be found in the Template Tags Reference.

Which template is used is decided by Foundry using the definitions in the conf/templates file. The top layer of templates which are parsed first are the application layouts. Which layout is used for a application is decided by Foundry using the application and class attributes of of bebop:page element in the data tree. The values of these attributes a set in the Java code or in the JSP templates used.

Application layout templates

How Foundry determines which application layout template to use

Which template is used for which application is determined using the applications section in the conf/templates.xml file. The applications element may contain any number of application elements. Each application element can have three attributes:

name (mandatatory)
The name of the application which is the value of the application attribute from the data tree. To associate applications which do not set the application attribute in the data tree the value none can be used.
class (optional)
The class of the application page shown. This is the value of the class attribute from the data tree.
origin (optional)
The origin of the template. In the default theme this is used to associate the backend applications which like the content center with the internal admin-layout.xml template provided by Foundry. It can also be used to associate an application with an layout template from the parent theme.

The applications element in the conf/templates.xml file should also contain a single single default element which defines which layout template should be used when no other matches.

Foundry tries to find the layout template to use as follows:

  • If there an application element where both name and class match the values from the data tree this template is used.
  • Otherwise Foundry checks if there is an application element without a class attribute where value of the name attribute matches the value from the data tree.
  • If this also fails and there is a default element the template from the default element is used.
  • If there is no default element the internal default layout template is used.

The structure of a application layout template

An layout template is a normal XML file. The root element is the page-layout element. The first child should be a head element. The head element is equivalent of the HTML head element. Inside the head element the title of (the string shown as title of the browser window) can be determined using the title element. Also the head is the place to load the CSS and JavaScript files and where to put meta informations.

After the head there should be a body element. Inside the body element the HTML structure is defined. At some point you may want to insert the content of a content item or of a Portlet. This is done using elements like content-item element or portal-grid-workspace-column-portlets. The layout of the individual content item or Portlet is defined in separate templates.

Content Item layout templates

The content layout templates which are found in the templates/content-items folder are used to create the HTML for content items in the list, link and detail views. Which template is used for which content item is determined using the content-items section in the conf/templates.xml file.

Selecting the Content Item layout template to use

The content-items element in the conf/templates.xml file has three sub elements: detail, link and list. The content-item elements in these elements are determining which template is used for which content type. There are several attributes for selecting the template. For a description of the available attributes please refer to the documentation of the content-item tag.

Structure of a Content Item layout template

Like the application layout templates a content item layout template is a XML file. The root element is the content-item-layout element. Inside this element all HTML producing elements can be used. For some content types there are special elements for outputting special properties. For example the for news item there is an elements news-date which outputs the date of a news. This element also provides an interface for designer to customise the format in which the date is shown. There is is also an general tag show-property which can be used to create a basic template for an unsupported content type.

Portlet templates

For Portlets the system is similar to the system for content items. Which template is used for a specific Portlet is determined using the child elements of the portlets element in the conf/templates.xml file. The portlet elements which contain the path of the template to use can have two child elements:

class
The class name of the Portlet.
workspace
The name of the workspace in which the Portlet is shown.

Foundry first tries to find a match for both class and workspace. If there is no matching portlet element in conf/templates.xml Foundry tries to find a match for the class name only. If this also fails it used the templates defined in portlets/default in the conf/templates.xml file.

The root element of a Portlet layout template is the portlet-layout element. Inside this element all HTML elements can be used. For each Portlet type there will be least on specific element which outputs the content of the Portlet.

CSS files

The system for loading CSS files is similar to the system for finding layout templates. Which CSS files are loaded for a page is determined by the conf/css-files.xml. The root element of this file is an css-files element. This element has multiple application child elements. Each application has an mandatory attribute name which contains the name of the application for which the CSS files named in the element are loaded. To further distinguish between pages provided by the same application the optional attribute class can be used. There should be also an default element which determines the CSS files to load when no matching application element is found.

Some pages have no application name in the data tree XML. In this cases to name of the application is set to none.

Each application element and the default element in css-files.xml can contain multiple css-file element. Each of the css-file elements defines a single XML to load.

The css-file element has two optional attributes:

media
The media type, for example screen or print for which the CSS file is used. The value of this attribute will appear in the media attribute of the link element which is generated in the HTML to load the CSS file.
origin
The origin of the CSS file. If not set the file is loaded from the current theme. If set to master the file is loaded from the master theme if the current theme is a child theme. If set to internal the file is loaded from the internal directory for CSS files, either from the current theme (if the current theme is a master theme) or from the Foundry master theme installed at /themes/foundry.

Templates Tags Reference

Root template tags

These tags are the root elements of a layout template.

fragment-layout

Root element for generating a HTML fragment instead of a complete HTML document.

include

This element allows it to include template fragments into a template. The element has two attributes. The file attribute is mandatory and contains the path the fragment to include, relative to the template directory. The internal attribute is optional. If set to true the fragment is loaded from the internal template directory.

For example <include file="fragments/footer.xml"< will include the file templates/fragments/footer.xml. If the internal attribute is set to true the file foundry/templates/fragments/footer.xml would be included.

An fragment template file included using this element using this element must contain a fragment-layout element as root.

Attributes

file

Path of the file to include, relative to the templates directory.

internal

If set to true the template fragment file is loaded from the internal template directory.

insert-block

The element is used in a master layout to insert a block from an extending template.

page-layout[./@extends]

Root element of an extending template. The extends attribute is required and points to the template which is extended by the layout. Only the block elements in the layout are processed. The master layout must contain matching insert-block elements.

Technically the master template is processed first and the extending layout is passed as parameter. The master layout

See also

    page-layout[not(./@extends)]

    Root element of a template. Generates the <html> root element.

    Tags for displaying Content Items

    These tags are common tags for displaying Content Items. For most Content Types there are special tags provided by other files.

    Tags for ccm-cms-types-article

    The tags in these file are used to display the content elements of ccm-cms-types-article.

    /content-item-layout//lead-text

    Outputs the lead text of a article.

    /content-item-layout//main-text

    Outputs the main text of a article.

    Tags for displaying a Decisiontree item

    The tags are used to configure the output of the decisiontree item. For technical reasons it is not yet possible to customise the HTML for the decisiontree completely.

    For title and description of the decisiontree the standard tags can be used.

    /content-item-layout//decisiontree-current-section

    Root element for outputting the current section of a decisiontree.

    Outputs the options for the current section of a decisiontree. This tag outputs a complete HTML form because the current implementation of the decisiontree does not provide enough information in the XML to support a fully customisable HTML. Nevertheless this it is possible to customise the classes set on various of the HTML in the created form using subelements: class-form Classes for the form itself. class-formgroup Classes to set on the div surrouding each pair of a label and an input element. class-label Classes to set on each label. class-input Classes to set on each input element. class-buttons Classes to set on the div surrounding the submit and cancel button. class-cancel Classes to set on the cancel button. class-submit Classes to set on the submit button.

    decisiontree-current-section//section-instructions

    Outputs the instructions for the current section of a decisiontree.

    decisiontree-current-section//section-title

    Outputs the title of the current section of a decisiontree.

    Tags for displaying the properties of ccm-cms-types-image

    The file provides tags for displaying the special properties of ccm-cms-types-image.

    /content-item-layout//image-artist

    Outputs the value of the artist property.

    /content-item-layout//image-description

    Outputs the value of the description property. This is equivalent to the lead text of an article.

    /content-item-layout//image-height

    Outputs the height in pixel of the image.

    /content-item-layout//image-license

    Outputs the value of the license property.

    /content-item-layout//image-maintext

    Outputs the long description (the main text) of the image.

    /content-item-layout//image-material

    Outputs the value of the material property.

    /content-item-layout//image-origin

    Outputs the value of the origin property.

    /content-item-layout//image-originalsize

    Outputs the value of the origSize property.

    /content-item-layout//image-publishdate

    Outputs the value of the publishdate property. The date can be formatted using the date format tags.

    /content-item-layout//image-site

    Outputs the value of the site property.

    /content-item-layout//image-source

    Outputs the value of the source property.

    /content-item-layout//image-technique

    Outputs the value of the technique property.

    /content-item-layout//image-width

    Outputs the width in pixels of the image.

    /content-item-layout//show-image

    Puts the necessary informations for showing the image on into the environment.

    /content-item-layout//show-thumbnail

    Puts the necessary informations for showing the thumbnail on into the environment.

    /content-item-layout//mpa-current-sections

    Root element for outputting the current sections of a MPA.

    /content-item-layout//mpa-current-sections//mpa-current-section

    Root element for outputting a current section of a MPA.

    /content-item-layout//mpa-current-sections//mpa-current-section//mpa-current-section-content

    Outputs the content of a current section of a MPA.

    /content-item-layout//mpa-current-sections//mpa-current-section//mpa-current-section-title

    Outputs the title of a current section of a MPA.

    /content-item-layout//mpa-next-page-link

    Provides the parameters (URL via the href parameter) for the link to the next page of a MPA if there is a next page.

    /content-item-layout//mpa-prev-page-link

    Provides the parameters (URL via the href parameter) for the link to the previous page of a MPA if there is a previous page.

    /content-item-layout//mpa-sections

    Root element for outputting the list of sections of a MPA.

    /content-item-layout//mpa-sections//mpa-section

    Root for rendering a link to a section of a MPA in the list of sections.

    /content-item-layout//mpa-sections//mpa-section//mpa-section-title

    Output the name a section of MPA in the list of sections.

    /content-item-layout//mpa-summary

    Outputs the summary of the multi part article.

    /content-item-layout//news-date

    Outputs the the date of a news. The news-date must contain at least one format element. The format element encloses the format definition for the specific language or the default format. The language for which a format is used is provided using the lang attribute at the format element. The default format has a default attribute with the value true. An example: 

                    <news-date>
                    <format default="true">
                        <iso-date/>
                    </format>
                    <format lang="de">
                        <day zero="true"/>.<month zero="true"/>.<year/>
                    </format>
                </news-date>

    In this example a visitor with a browser using German as default locale will see the news date in the date format that common in Germany (dd.mm.yyyy). For all other languages, the default format is used. In this case the iso-format is used.

    /content-item-layout//siteproxy-content

    Processes the proxied XML of a SiteProxy using xsl:apply-templates. Your theme must provide XSL to transform the proxied XML into HTML.

    content-item-layout//content-item-link

    Provides a link to content item itself. Useful if a content item is shown using a portlet and you want to create a link to the normal detail view of the item.

    content-item-layout//edit-link | fragment-layout//edit-link

    Provides the href for creating a link to edit the current item in the content centre if the current user is logged in and has the permission to edit the item.

    To use this feature put the following snippet like the following into the templates for the content items in your theme: 

                    <edit-link>
                    <div class="edit-link">
                        <a>
                            <a>
                                &#x270e;
                            </a>
                        </a>
                    </div>
                </edit-link>

    The example uses an UTF-8 character from the Dingbats block (a pencil). You can of course use another character, text or an image. To reduce the amount of code needed you may add a fragment template and include this template using the include tag.

    You also have to include styles for the edit link into your theme. The foundry-base theme, for example, puts the edit link the top right corner of the area which shows the content item. This is done by the following styles: 

                    /* Sets the reference point for position: absolute 
                to the main element block */
                main {
                position: relative;
                }

                /* Don't show the edit link on a first glance */
                main .edit-link {
                display: none;
                }

                /* Display the edit link in the top right corner 
                of the content item area if the cursor is in 
                the content item area */
                main:hover .edit-link {
                display: block; 
                position: absolute;
                right: 0;
                top: 0;
                font-size: 30px;
                color: #0776a0;
                /* Blue border around the link */
                border: 1px solid #0776a0; 
                /* Make the link 32px in width and height */
                width: 32px; 
                height: 32px;
                text-align: center;
                }

                /* Remove default decoration for links */
                main:hover .edit-link a:link,
                main:hover .edit-link a:hover,
                main:hover .edit-link a:active, 
                main:hover .edit-link a:visited {
                color: #0776a0;
                text-decoration: none;
                }

    content-item[@mode = 'detail' or not(@mode)]

    The content-item element with the attribute mode set to detail or without the attribute inserts the HTML representation of the detail view of the current content item. The content item can either be the greeting item or normal item.

    The HTML representation of a content item is defined using special templates with the contentitem-layout element as root. Usually these templates are located in the templates/content-items folder. Which template is used for a particular content item is defined by the conf/templates.xml file. In this file there is a content-items element below the templates element. The association between templates and content items is described by the content-item elements in the content-items element. The content-item has four optional attributes (at least on must be present) which are used to limit the content items for which a template is used. The four attributes are:

    oid
    Limit the use of the template to a specific content item, identified by its OID (the OID of the master version). Can't be used in combination with the other attributes.
    content-section
    The name of the content section to which the item belongs. Can be used in combination with the category and content-type attributes.
    category
    The template is only used for the content item if the item is viewed as item of the category. The category is set as a path containing the names the categories.
    content-type
    The content-type of the item.

    content-item[@mode = 'link']

    The content-item with the mode attribute set to link insert the HTML representation of a content item. In this case the content item to show is provided using by a XSL parameter which has to be provided by a surrounding tag like related-link.

    content-item[@mode = 'list']

    The content-item element with the mode attribute set to list inserts the HTML representation of the the list view of a content item. The list view is primarily used in object lists.

    As for the detail view, the HTML representation of the list view of a conten item is defined using special templates with the contentitem-layout element as root. Usually these templates are located in the templates/content-items folder. Which is used for a particular content item is defined in the conf/templates.xml file. In this file there is a content-items element below the templates element.

    There three attributes which can be used to define in which cases a specific template is used:

    style
    Used to select a specific style for the list view of the item. To select a style add a style attribute to the content-item attribute in the application layout file.
    content-type
    The content-type of the item.
    category
    The template is only used for the content item if the item is viewed as item of the category. The category is set as a path contains the names the categories.

    Data tags

    These tags can be used to display several informations from the XML provided by CCM.

    show-page-title

    foundry:title

    See also

    show-text

    textsmoduletexts/global.xmlidclasswith-colorsetspan

    Attributes

    id

    An unique id for the text.

    class

    One or more classes to format the text per CSS.

    module

    The module (file) from the text is retrieved. The name of the file should be provided without file extension.

    with-colorset

    Add the classes for using the Colorset feature to the span element the text is wrapped in.

    HTML tags

    These tags are generating the equivalent HTML tags. In most cases the tags have the same name and same attributes as their HTML counterparts, but some work in a slightly different way, for example by using values provided by other surrounding tags which are passed to them as XSL parameters.

    a

    Generates a HTML a element. There are some differences to the a element in HTML. First, there two attribute for the URL:

    href-property
    The name of a property of the current object which contains the URL for the link.
    href-static
    A static URL.

    The third variant for providing an URL is to call the template with a href parameter in the XSL.

    Values for some other attributes can also be passed to the this template as XSL parameters:

    hreflang
    Language of the resource the link is pointing to.
    title
    Value for the title attribute of the link. Usally this should a very brief description of the target of the link
    type
    The media type of the link target.

    Attributes

    download

    Value for the HTML5 download attribute.

    href-property

    The name of a property (aka the name of an XML element in the data-tree) containing the URL of the link.

    href

    A static URL for the link.

    rel

    The relationship of the linking document with the target document.

    title-static

    A key which identifies the translated title in lang/global.xml.

    title

    Static, not translated title of the link.

    abbr

    Generates a HTML abbr element used to tag abbreviations.

    address

    Generates a address element in the HTML output. The address elements represents the contact information of the responsible author of article or body it appears in.

    article

    Generates the HTML5 article element.

    aside

    Generates a HTML5 aside element.

    audio

    Generates a HTML5 audio element. The source URL of the audio file can be provided by a surrounding element, statically in the theme or by an property in the data tree.

    Attributes

    src-static

    A static URL for the source of the audio file

    src-property

    Name of property in the data tree containing the source URL.

    b

    Generates a HTML b element. Use this element only with semantics defined in the HTML5 specification. Originally, in the early incarnations of HTML, this element marked text as bold. In HTML5 the semantics of this element as been redefined. For more information please refer to the HTML5 specification.

    blockquote

    Generates a blockquote element.

    body

    Generates the HTML body element.

    button

    Generates a button element.

    canvas

    Generates a canvas element.

    cite

    Generates a cite element.

    code

    Generates a code element.

    dd

    A definition of term in a definition list.

    dfn

    Generates a dfn element.

    div

    div

    divIfNotEmpty

    div

    See also

    dl

    Generates a definition list.

    dt

    A term in a definition list.

    h1

    Generates a h1 element.

    h2

    Generates a h2 element.

    h3

    Generates a h3 element.

    h4

    Generates a h4 element.

    h5

    Generates a h5 element.

    h6

    Generates a h6 element.

    hr

    Generates a hr element. This element has no content.

    i

    Generates an i element.

    input

    Generates a input element. A preset value can be provided using a XSL parameter by a surrounding element. The HTML5 placeholder attribute has been split into two attributes. The placeholder-module attribute contains the name of module parameter (the name of the file in the texts directory) in which the text for the placeholder is stored. If omitted the global.xml file is used. The placeholder attribute itself contains the ID of the text to show as placeholder.

    Attributes

    placeholder-module

    The name of the file in the texts directory which contains the text to use as placeholder. If omitted the global.xml file is used.

    placeholder

    The ID of the text to use as placeholder.

    ins

    Generates a ins element

    kbd

    Generates a kbd element

    label

    Generates a label element.

    legend

    Generates a legend element inside a form element.

    li

    Generates a li element inside an ul or ol.

    main

    main

    meta

    head

    noscript

    Generates a noscript element

    ol

    Generates an ol element.

    optgroup

    Generates an optgroup element. The label for the option group must be provided by a surrounding element as XSL parameter.

    option

    Generates a option element for use in select box. Several values for attributes have to be provided by a surrounding element using XSL parameters, for example the value of the value attribute.

    p

    Generates a p element.

    pre

    Generates a pre element.

    q

    Generates a q element.

    s

    Generates a s element.

    samp

    Generates a samp element.

    script

    Used to include a script (usally a JavaScript). The script is either provided a content of the element or as an external file. Embedded scripts should only be used for small parts of code, like the code for activating jQuery plugins for some elements. Everything which is longer than five or six lines should be put into a external file in the scripts directory of the theme.

    Attributes

    origin

    As usual origin attribute determines the how the path provided in the src attribute is interpreted. The following values are interpreted. In addition to the common values internal, master and the default value the script element also support the value absolute. If origin is set to absolute the provided source path is processed by Foundry and is used as it is provided.

    src

    The path of the script to include. If the origin attribute is not set (or not set to absolute the path is interpreted relative to the theme directory. For example the path of a script included using 

                    <script type="text/javascript" src="scripts/example.js"/>

    in the a theme named my-theme at the server http://www.example.org is altered to the absolute path http://www.example.org/themes/published-themedir/itb/scripts/example.js. If the absolute attribute is set to true the path is not altered. One usecase for an absolute path is to load an script from a content delivery network.

    type

    The type of the script. Usally this is text/javascript. If the attribute is not set in the layout template, it is automatically set to text/javascript.

    section

    section

    select

    Generates a select box in a form. The name of the select box and the status for the disabled attribute can be provided by a surrounding element via XSL parameters.

    small

    Generates a small element.

    source

    Generates a source element for use in audio and video elements. The source URL (value of the src attribute) can either provided by a surrounding element as XSL parameter or via the src-static or src-property attribute.

    Attributes

    src-static

    An URL to an static resource.

    src-property

    Name of an XML node in the data-tree providing the URL of the resource.

    span

    span

    spanIfNotEmpty

    span

    strong

    Generates a strong element.

    sub

    Generates a sub element.

    sup

    Generates a sup element.

    table

    Generates a table element.

    table//caption

    Generates a caption element representing the caption of a table.

    tbody

    Generates a tbody element.

    td

    Generates a td element.

    textarea

    Generates a textarea. The value may be provided as XSL parameter by a surrounding tag.

    Attributes

    placeholder-module

    The name of the file in the texts directory which contains the text to use as placeholder. If omitted the global.xml file is used.

    placeholder

    The ID of the text to use as placeholder.

    tfoot

    Generates a tfoot element.

    th

    Generates a th element.

    thead

    Generates a thead element.

    time

    Generates a time element.

    title

    Generates the title in the HTML head. The other elements are allowed in the <title> tag:

    • show-text
    • show-page-title

    tr

    Generates a tr element.

    track

    Generates a track element.

    u

    Generates a u element.

    ul

    Generates an ul element.

    var

    Generates an var element.

    video

    Generates a HTML5 video element. The source URL and the URL of preview image (poster) can be provided by a surrounding element, statically in the theme or by an property in the data tree.

    Attributes

    src-static

    A static URL for the source of the video file

    src-property

    Name of property in the data tree containing the source URL.

    poster-static

    A static URL for the source of the preview image

    poster-property

    Name of property in the data tree containing the poster URL.

    wbr

    Generates a wbr element.

    Loaders

    This tags are used to load resources required by the generated HTML documents, for example CSS files and JavaScript files.

    load-css-files

    conf/css-files.xml<link>CSS files section

    load-html5shiv

    Loads the html5shiv JavaScript library which fixes a bug of old Internet Explorers (up to version 8) with elements unknown by the Internet Explorer. You need this library if you want to use HTML 5 elements like article or nav in your templates. All other browser thread unknown elements like div or span. The Internet Explorer to version 8 however adds a closing elements to the DOM tree directly after the unknown opening element, effectively removing the element from the DOM. The html5shiv library fixes the DOM tree using JavaScript.

    This tag adds a conditional comment to load the html5shiv library only for old Internet Explorers

    load-jquery

    Loads the jQuery JavaScript library provided by CCM.

    load-jquery-ui

    Loads the jQuery UI JavaScript library provided by CCM.

    load-mathjax

    Loads the MathJAX JavaScript library which can render mathematical formulas written in MathML or LaTeX syntax.

    Tags for ccm-navigation

    These tags are used to output data provided by the ccm-navigation module. More exactly the navigation menu(s) and the breadcrumbs on a site are generated using these tags.

    object-list//paginator

    Root element for creating the paginator for an object list. Provides the paginator data for the elements enclosed by this element via XSL parameters. The content is of this element is only processed if the number of pages is greater than one or if the show attribute is set to always.

    Attributes

    show

    If set to always the paginator is shown even if there is only one page.

    object-list//paginator//current-page

    Outputs the number of the current page.

    object-list//paginator//first-page-link

    Provides the URL to the first page of the list for an enclosed a element.

    object-list//paginator//last-page-link

    Provides the URL to the last page of the list for an enclosed a element.

    object-list//paginator//next-page-link

    Provides the URL to the next page of the list for an enclosed a element.

    object-list//paginator//object-begin

    Outputs the index of the first object shown on the current page. The value is provided by the surrounding paginator element via a XSL parameter.

    object-list//paginator//object-count

    Outputs the number of elements in list.

    object-list//paginator//object-end

    Outputs the index of the last object shown on the current page. The value is provided by the surrounding paginator element via a XSL parameter.

    object-list//paginator//page-count

    Outputs the number of pages.

    object-list//paginator//page-size

    Outputs the size of page (the number of items on each page).

    object-list//paginator//prev-page-link

    Provides the URL to the previous page of the list for an enclosed a element.

    Developer Manual

    The structure of Foundry

    Top level structure

    Foundry supports two kinds of themes: Parent themes and child themes. Parent themes are also called master themes. Normally there should be only one parent theme in a CCM installation at /themes/foundry. All other themes should be child themes. An example for a child theme should also be installed at /themes/foundry-base.

    A complete Foundry theme (a parent theme) contains of the following directories:

    conf
    Configuration files for the theme.
    doc
    The documentation of Foundry. The document you reading at the moment is generated using these files.
    fonts
    Webfonts used in the theme.
    foundry
    The directory contains the XSL files which contain the logic part of Foundry.
    images
    Static images for the theme.
    libs
    Additional JavaScript libraries, for example jQuery plugins.
    scripts
    Custom JavaScripts
    styles
    CSS files
    templates
    The layout templates
    texts
    Static texts for the theme
    user
    Custom extensions. Not supported yet.

    A child theme has only the directories which contain files which the designer needs to change. These are:

    • conf
    • fonts
    • images
    • libs
    • scripts
    • styles
    • templates
    • texts

    The foundry directory contains the following files and directories:

    fonts
    Webfonts used internally, for example for the Content Center.
    images
    Images used internally.
    lib
    The XSL files from Foundry.
    scripts
    Java Scripts used internally.
    styles
    CSS files for internal templates like the Content Center
    templates
    Internal templates for example for the Content Center.
    texts
    Internal texts
    main.xsl
    Entry point. The start.xsl in the base directory acts only as entry point for the XSL processor and delegates all work to the main.xsl.
    lib.xsl
    A simple import file which imports the XSL files from the lib directory.

    The main.xsl file contains the xsl:output element which tells the XSL processor that we want to create HTML. There is only two XSL templates in the main.xsl file along with some helper functions. This first template is the entry point for CCM and matches the bebop:page element which is the root element of the data tree XML created by CCM. The template processes the conf/templates.xsl file calls the XSL templates for parsing the layout templates.

    The second templates is the entry point for the documentation system Foundry.

    The lib directory

    The lib is the core part of Foundry and contains the following sub directories and files:

    bebop
    XSL files for creating the backend UI. The XSL files were taken from Mandalay and have only been adapted to work inside Foundry.
    search
    XSL files for the various search applications.
    template-tags
    XSL files implementing the tags which can be used in the templates.
    template-tags
    This directory contains the XSL files which implement the tags which can be used in the layout templates.
    bebop.xsl
    Imports the files from the bebop directory.
    global-vars.xsl
    These file is very important. It defines various global variables like the theme-prefix or the context-prefix variables. A complete list can be found in the reference part.
    search.xsl
    Import file for the XSL files in the search directory.
    template-parser.xsl
    This file contains the XSL templates for parsing the layout templates.
    template-tags.xsl
    Import file for the XSL files in the template-tags directory.
    utils.xsl
    Helper functions. A complete list is available in the reference part.

    Template tags

    The template-tags directory contains the XSL file which are implementing the tags which can be used in the layout templates. For a complete list please refer to the Template Tags Reference in the user manual.

    Coding style

    This document describes the coding conventions for the Foundry theming engine.

    Naming

    The naming rules described here apply to all names: Names of layout elements, XSL template names, XSL functions, files, ids and classes (in the class attribute).

    Use the dash "-" to separate parts of a name instead of camel case or the underscore. For example: get-setting instead of getSetting or set_setting.

    Names should be lowercase.

    Namespace declarations

    In the XSL files, XML namespaces are only defined at the <xsl:stylesheet> element. The XSL namespace is the first one is declared first. The other namespace follow in alphabetic order (ordered by their prefix).

    Indention, line length and formating

    Indention is done using spaces. Indention depth is four (4) spaces per level.

    Try to keep the line length below 100 characters per line. Because of some restrictions of XML this will be possible in every case.

    Insert a line break after each attribute of an XML element. The first attribute is on the same line as the element. For example write 

    <xsl:param name=example-param"
           select="'example'"/>

    instead of 

    <xsl:param name=example-param" select="'example'"/>

    Adding support for content types

    To enable Foundry to output a Content Item of specific content type two things must be available: One or more layout template associated with the content type and appropriate template tags to display to informations of the content item from the data tree.

    Foundry provides a general tag show-property which can be used to output properties of a content type. For simple types this maybe sufficent. The name of the property can be found out from the XML output which can be viewed by adding the parameter output=xml to an URL.

    For more complex types or if the value of the property should be formatted in a special way it is maybe necessary to implement some new template tags. Tags which part of the official distribution of Foundry are found in the foundry/lib/template-tags/content-items directory. Custom extensions can be put into the user directory (not supported yet).

    For each content type there should be a separate file named after the content type. A relatively simple example is the NewsItem type. In this case the date of the news needs some formatting. The news.xsl file provides the tag news-date which allows the template author to choose the format of the date.

    A more complex example is the MultiPartArticle type. The type needs some templates for creating the menu with the sections etc. The tags for are evaluating the data tree and creating the menu.

    One important rule is that the template tags should not create any HTML. They should only provided the necessary informations and output the values of properties. HTML is only generated by the HTML tags provided by Foundry. A template tag for a content type may enclose several HTML elements which are used to define the HTML output.

    The documentation system of Foundry

    Overview

    Foundry comes with a documentation system which creates the reference documentations for template tags and helper functions on the fly. The documentation system – which you using at the moment by the way – consists of three parts:

    • An index.jsp file in the doc directory which invokes the XSL transformer. Using an JSP here has the advantage that the behaviour is similar to an index.html.
    • Some XSL templates.
    • And the documentation itself which consists of some XML files, some static texts and the documentation in the other templates.

    The general structure of the documentation is defined by the doc/foundry-documentation.xml file. This file is the entry point for the XSL processor. The chapters of the documentation are defined by the foundry:doc-chapter elements. The sections of the chapters are defined using foundry:doc-section elements. The section which use static texts have a static. The value of the static attribute is the name of the file to include from the doc/static-texts directory. These files are normal HTML files in XML syntax. They must have a main element. Only the content of the main element is included into the documentation.

    Sections which are generated on the fly from the XSL files of Foundry have a generate attribute. The generate attribute controls which documentations appear in the section.

    Documentation inside XSL templates

    Templates, functions and global variables are documented using the foundry:doc element which is placed in the XSL directly before the element to document. The foundry:doc element has two mandatory attributes. The section elements is used to control in which section the documentation appears. The second attribute is the type attribute. This attribute is used to format the documentation. The possible values are:

    template-tag
    The following XSL template is a tag which can be used in the layout templates.
    env-var
    The following xsl:variable or xsl:param defines a global variable.
    function
    The following xsl:function is a helper function which can be used in the implementation of template tags.
    function-template
    The following xsl:template is a helper template.

    A foundry:doc element can have to following child elements:

    foundry:doc-desc
    A text describing the template, function or variable. The must be structured using HTML elements like p, even it is only a single paragraph. Otherwise the text is not copied into the documentation. Look at one of the XSL files of Foundry for an example.
    foundry:doc-attributes
    Surrounds the documentation for attributes which can be used on a template tag. The individual attributes are documented by foundry:doc-attribute elements. The foundry:doc-attribute has a mandatory attribute name which contains the name of the attribute. The documentation of the attribute must be enclosed in HTML elements. Look at one of the XSL files of Foundry for an example.
    foundry:doc-parameters
    Surrounds the documentation for parameters which can be used on a function. The individual parameters are documented by foundry:doc-parameter elements. The foundry:doc-parameter has a mandatory parameter name which contains the name of the parameter. The documentation of the parameter must be enclosed in HTML elements. Look at one of the XSL files of Foundry for an example.
    foundry:doc-see-also
    Contains links to other parts of the documentation or the external resources. The links are defined using foundry:doc-link attributes. Each foundry:doc-link has a href attribute which the link. The description of the link is the content of the element.

    XSL Templates and Function references

    Global/environment variables

    Global variables either provided by the calling CCM instance or by Foundry itself.

    foundry-version

    The version of Foundry. Kept in sync with the version of CCM, so the first version was be 2.2.3.

    theme-mode

    The mode of the theme. If the theme is standalone theme, the value is master. If the theme is a child theme the value is child.

    master-theme

    The master theme of the current if the theme is a child theme. if theme is direct child of the Foundry base theme the value is foundry. Otherwise it is the name of master theme.

    theme-prefix

    The path the to theme file. This path is used at several points to load files which are part of the theme, like CSS files, images and fonts.

    context-prefix

    The context prefix in which CCM is installed. If CCM is installed into the ROOT context of the servlet container, this variable will be empty.

    dispatcher-prefix

    The path on which the CCM dispatcher Servlet is mounted. Usually this is CCM.

    username

    The name of user currently login in CCM.

    data-tree

    This variable stores the XML created by CCM for later access.

    This variables stores the XML definition of the Foundry documentation. Activate double click protection on buttons? Activate double click protection on links?

    The language negotiated between CCM and the user agent.

    The language to use as negotiated by CCM.

    supported-languages

    The languages supported by this theme. They are configured in conf/global.xml using the <supported-languages> element. Example for german and english: 

                    <?xml version="1.0"?>
                <foundry:configuration>
                    …
                    <supported-languages default="de">
                        <language locale=de">
                        <language locale=en">
                    </supported-languages>
                    …
                </foundry:configuration>

    The language to use by theme engine for static texts etc. The language is determined as follows:

    • If the negotiated language is also in the supported-languages
    • If not the language which set by the default attribute of the <supported-languages> is used, but only if this language is in the supported languages.
    • Otherwise the first of the supported languages is used.

    Root template tags

    These tags are the root elements of a layout template.

    Function foundry:gen-src-url

    Variant of foundry:gen-src-url without the parameters string parameter.

    Result

    Result type

    any

    Description

    Function foundry:gen-src-url

    Processes a given URL for use in the src attribute of an audio, img or video element. The function distigushes between this cases:

    The URL starts with http:// or https://
    In this case the URL is threated as an absolute URL pointing to a resource outside of CCM. If any parameters are passed to the function they are appended to the URL.
    The URL starts with a slash (/)
    In this case the URL points to a resource managed by the CCM which also manages the theme. In this case the URL is prefixed with the dispatcher-prefix and the parameters, if any, are appended.
    Other cases
    If none of the two other cases match the URL points to a URL in the theme. In this case the URL is processed by the gen-path function. The parameters, if any are appended.

    If parameters are passed to this function they are appended to the URL. The parameters are passed as string formatted as URL parameters, for example foo=hello&bar=world. A leading ? or & is removed before adding the string the URL. If the URL already contains parameters (if the URL contains a ?) the paramters string is added with a leading ampersand (&). If not the parameters are appended using a ? character.

    Parameters

    Name Mandatory Type Description
    src-raw yes string

    The raw URL to process.

    parameters yes string

    Parameters to append to the URL.

    Result

    Result type

    string

    Description

    The processed URL.

    Loaders

    This tags are used to load resources required by the generated HTML documents, for example CSS files and JavaScript files.

    A helper template for generating the <link rel="stylesheet" href="..."/> elements for loading the CSS files. The name of the CSS file to load. If the filename contains slashes the filename is used as it is provided. If there are not slashes in the filename the filename is prefixed with styles/. The media for which the file should be loaded. If no set, the CSS file is used for all media types. The origin of the CSS file. If not set or the parameter is empty, the CSS file is loaded from current theme. There also some values with a special meaning: master File is loaded from the master/parent theme. Please read the section about parent and child themes for more details. internal The file is loaded from the internal directories If the current theme is a child theme, the file is loaded from the internal directories of the parent theme. Some examples: <css-file>public.css</css-file> The CSS file public.css is loaded from styles directory in the current theme. <css-file>bootstrap/css/bootstrap.min.css</css-file> The CSS file bootstrap.min.css is loaded from the directory bootstrap/css in the current theme. <css-file origin="internal">admin.css</code> If the current theme is a master theme, the CSS file admin.css is loaded from the directory foundry/styles in the current theme. If the current theme is child theme the CSS file admin.css is loaded from the directory foundry/styles of the Foundry theme installed at /themes/foundry.

    Utility functions

    This file provides several utility functions and templates.

    Function foundry:boolean

    A helper function for evaluating certain string values to boolean. This function has two purposes. First it simplifies some expressions. for example if you have a template tag with a attribute containing a (pseudo) boolean value (attribute values are always treated as strings) you would have to write something like: 

                    ...
                <xsl:if test="./@attr = 'true'">
                ...
                </xsl:if>
                ...

    Using foundry:boolean this can be simplified to 

                    ...
                <xsl:if test="foundry:boolean(./@attr)">
                ...
                </xsl:if>
                ...

    The more important purpose is to make the usage of boolean values more user friendly, especially in the templates. Using foundry:boolean no only true is evaluated to boolean true. A number of other strings is also evaluated to true:

    • true
    • TRUE
    • yes
    • YES
    • t
    • T
    • y
    • Y

    All other values are evaluated to false.

    Parameters

    Name Mandatory Type Description
    value yes string

    The value to evaluate.

    Result

    Result type

    boolean

    Description

    The evaluated boolean value.

    Function foundry:gen-path

    Helper function for generating paths to theme resources like CSS files etc. Use this function instead of concatenating paths yourself. For example, instead of 

                    document(concat($theme-prefix, 'path/to/resource/file')

    use foundry:gen-path: 

                    document(foundry:gen-path('path/to/resource/file'))

    path/to/resource/file is meant as a placeholder here. A real world example is a settings file, for example conf/global.xml. For this file a usage of the foundry:gen-path function would look like this 

                    document(foundry:gen-path('conf/global.xml')

    The advantage of this function is the encapsulation of the path generation process. foundry:gen-path.

    Result

    Result type

    string

    Description

    The absolute path for the file.

    Function foundry:gen-path

    Variant of gen-path with an additional origin parameter. This parameter can have three values: If set to true the file is loaded from the foundry directory.

    empty string ('')
    The path points to a resource in the theme directory. The return value is the concatenation of the theme-prefix, a slash and the path provided as first parameter. In XPath Syntax: concat($theme-prefix, '/', $path.
    master
    If the theme mode (which is set in conf/global.xml) is set to master the result is the same as for the empty string. If the the theme mode is set to child the generated path points to the parent/master theme. More exactly the result is the concatenation of the context-prefix environment variable, the string /themes/, the name of the master theme (set in conf/global.xml, usally foundry), a slash the the path provided as first parameter. Or in XPath syntax: concat($content-prefix, '/themes/', $master-theme, '/', $path.).
    internal
    The path points to an internal resource which is provided by Foundry. If the theme mode is master the generated path is the concatenation of the theme prefix, the string /foundry/ and the path provided as first parameter (XPath: concat($theme-prefix, '/foundry/', $path). If the theme mode is child the generated path is the concatenation of the context prefix, the string /themes/foundry/foundry/ and the path provided as first parameter (XPath: concat($context-prefix, '/themes/foundry/foundry/', $path)).

    Result

    Result type

    any

    Description

    Function foundry:log-level

    Helper function to generate an info message. This function be used together with <xsl:message> to output a message in the CCM log warning the administrator about some things in the theme, for example a missing configuration file. Example: 

                    ...
                <xsl:message>
                    <xsl:message select="foundry:message-info('Something is strange...')" />
                </xsl:message>

    Parameters

    Name Mandatory Type Description
    message yes any

    Result

    Result type

    xs:string

    Description

    A message string of the form [Foundry WARNING] $message with $message replaced by the value of the parameter.

    Function foundry:log-level

    Helper function to generate an info message. This function be used together with <xsl:message> to output a message in the CCM log when something goes wrong in the theme, for example when a layout file has a wrong structure. Example: 

                    ...
                <xsl:message>
                    <xsl:message select="foundry:message-info('Some error has occurred...')" />
                </xsl:message>
                ...

    Parameters

    Name Mandatory Type Description
    message yes any

    Result

    Result type

    xs:string

    Description

    A message string of the form [Foundry ERROR] $message with $message replaced by the value of the parameter.

    Function foundry:get-attribute-value

    A helper function for retrieving an attribute value from an element. If the attribute is set on the current element the value of the attribute is used as result. If the attribute is not set the default-value is used. This method is used by several layout tags with optional attributes. A common use pattern looks like this: 

                    <xsl:template match="example">
                    <xsl:variable name="width" 
                select="foundry:get-attribute-value(current(), 'width', '640')" />
                    <xsl:variable name="height" 
                select="foundry:get-attribute-value(current(), 'height', '480')" />
                /<xsl:template>

    In this example, the element example has two optional attributes: with and height. If the attribute is set in processed XML, the value set there is used. Otherwise the default value (640 respectively 480) is used. Without this function a code block like the one in the xsl:choose block of this function would be necessary for each of the variables.

    Parameters

    Name Mandatory Type Description
    node any
    attribute-name any
    default-value any

    Result

    Result type

    any

    Description

    The value of the attribute if it is set on the current element, the default-value otherwise.

    Function foundry:get-setting

    Convenient function for calling foundry:get-setting with only the module name and setting name.

    Parameters

    Name Mandatory Type Description
    module yes string

    The module of the settings. May be an empty string ('').

    setting yes string

    The name of the setting to retrieve.

    Result

    Result type

    string

    Description

    The value of the setting.

    Function foundry:get-setting

    Convenient function for calling foundry:get-setting with only the module name, the setting name and an default value.

    Parameters

    Name Mandatory Type Description
    module yes string

    The module of the settings. May be an empty string ('').

    setting yes string

    The name of the setting to retrieve.

    default yes string

    A default value which is used when the setting is not configured.

    Result

    Result type

    string

    Description

    The value of the setting or the default value if the setting is not configured.

    The module of the settings. At the moment this corresponds to the name of the file in the conf directory. The empty string as value corresponds to the global.xml file. The name of the setting to retrieve. The value to use if there is no entry for the setting in the settings file. A node from the layout template which overrides the value from the configuration. The value of the requested setting or if no value has been set the provided default value. If no default value has been provided the result is an empty string. This function retrieves the value of a setting from the theme configuration. For more informations about the configuration system of Foundry please refer to the configuration section of the Foundry documentation.

    Function foundry:get-static-text

    Retrieves at static text. For more informations about static texts in Foundry please refer to the static texts section in the Foundry documentation.

    Parameters

    Name Mandatory Type Description
    module yes string

    The module of the settings. At the moment this corresponds to the name of the file in the texts directory. The empty string as value corresponds to the global.xml file.

    id yes string

    The name of the text to retrieve.

    lang no string

    The language to retrieve. Normally there is no need to set this parameter because it is determined automatically.

    Result

    Result type

    string

    Description

    The requested static text. If there is no value for the requested static text in the module provided by the module parameter the value depends if the debug mode is enabled or not. If the debug mode is not not enabled the result is an empty string. If the debug mode is enabled, a identifier of the text (the value of the id parameter) is displayed. If you point the mouse pointer of the placeholder, the complete path of the text is shown as hovering box.

    Function foundry:debug-enabled

    A helper function to determine if the debug mode should be enabled. The debug mode of foundry is automatically enabled if the theme is viewed as development theme.

    Result

    Result type

    any

    Description

    true if the debug mode if active, false otherwise.

    Function foundry:read-current-category

    Result

    Result type

    any

    Description

    The path of the current category.