# 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.

#

# related-link//internal//target-item-title

Outputs the title of the target item of an internal related link.

# related-link//related-link-desc

Outputs the description of a related link.

# related-link//related-link-title

Outputs the title of a related link.

# related-links

Root element to create the list of related links assigned to an content item

# related-links//related-link

This tag wraps the HTML to display a single related link. The tag also adds the parameters required to create the link into the environment, for example the URL (href) of the related link.

# 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-copyright

Outputs the value of the `copyright` 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-all-sections-link

Provides the parameters (URL via the `href` parameter) for the link to show all section of a MPA on one page.

# /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.

## See also

- The template system

# 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.

## See also

- The template system

# Data tags

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

# show-page-title

`foundry:title`

## See also

- foundry:title

# show-text

`texts` `module` `texts/global.xml` `id` `class` `with-colorset` `span`

## 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.

## See also

- Description of the a element in the HTML5 specification.

# abbr

Generates a HTML `abbr` element used to tag abbreviations.

## See also

- Description of the abbr element in the HTML 5 specification.

# 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.

## See also

- Description of the address element in the HTML5 specification

# article

Generates the HTML5 `article` element.

## See also

- Description of the article element in the HTML5 specification

# aside

Generates a HTML5 `aside` element.

## See also

- Description of the aside element in the HTML5 specification.

# 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.

## See also

- Description of the audio element in the HTML5 specification.

# 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.

## See also

- Description of the b element in the HTML5 specification.

# blockquote

Generates a `blockquote` element.

## See also

- Description of the blockquote element in the HTML5 specification.

# body

Generates the HTML `body` element.

## See also

- Description of the body element in the HTML5 specification.

# button

Generates a button element.

## See also

- Description of the button element in the HTML5 specification.

# canvas

Generates a `canvas` element.

## See also

- Description of the canvas element in the HTML5 specification.

# cite

Generates a `cite` element.

## See also

- Description of the cite element in the HTML5 specification.

# code

Generates a `code` element.

## See also

- Description of the code element in the HTML5 specification.

# dd

A definition of term in a definition list.

## See also

- http://www.w3.org/TR/html5/grouping-content.html#the-dd-element

# dfn

Generates a `dfn` element.

## See also

- Description of the dfn element in the HTML5 specification.

# div

`div`

## See also

- Description of the div element in the HTML5 specification.

# divIfNotEmpty

`div`

## See also

- #div

# dl

Generates a definition list.

## See also

- http://www.w3.org/TR/html5/grouping-content.html#the-dl-element

# dt

A term in a definition list.

## See also

- http://www.w3.org/TR/html5/grouping-content.html#the-dt-element

# footer

## See also

- http://www.w3.org/TR/html5/sections.html#the-footer-element

# h1

Generates a `h1` element.

## See also

- Description of the h1, h2, h3, h4, h5 and h6 elements in the HTML5 specification.

# h2

Generates a `h2` element.

## See also

- Description of the h1, h2, h3, h4, h5 and h6 elements in the HTML5 specification.

# h3

Generates a `h3` element.

## See also

- Description of the h1, h2, h3, h4, h5 and h6 elements in the HTML5 specification.

# h4

Generates a `h4` element.

## See also

- Description of the h1, h2, h3, h4, h5 and h6 elements in the HTML5 specification.

# h5

Generates a `h5` element.

## See also

- Description of the h1, h2, h3, h4, h5 and h6 elements in the HTML5 specification.

# h6

Generates a `h6` element.

## See also

- Description of the h1, h2, h3, h4, h5 and h6 elements in the HTML5 specification.

# head

`head`

## See also

- Description of the head element in the HTML5 specification.

# header

`header`

## See also

- Description of the header element in the HTML5 specification.

# hr

Generates a `hr` element. This element has no content.

## See also

- Description of the hr element in the HTML5 specification.

# i

Generates an `i` element.

## See also

- Description of the i element in the HTML5 specification.

# 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.

## See also

- Description of the input element in the HTML5 specification.

# ins

Generates a `ins` element

## See also

- Description of the ins element in the HTML5 specification.

# kbd

Generates a `kbd` element

## See also

- Description of the kbd element in the HTML5 specification.

# label

Generates a `label` element.

## See also

- Description of the label element in the HTML5 specification.

# legend

Generates a `legend` element inside a form element.

## See also

- Description of the legend element in the HTML5 specification.

# li

Generates a `li` element inside an `ul` or `ol`.

## See also

- Description of the li element in the HTML5 specification.

# main

`main`

## See also

- Description of the main element in the HTML5 specification.

# meta

`head`

## See also

- #head
- Description of the meta element in the HTML5 specification.

# nav

Generates a HTML5 `nav` element.

## See also

- Description of the nav element in the HTML5 specification.

# noscript

Generates a `noscript` element

## See also

- Description of the noscript element in the HTML5 specification.

# ol

Generates an `ol` element.

## See also

- Description of the ol element in the HTML5 specification.

# optgroup

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

## See also

- Description oft the optgroup element in the HTML5 specification.

# 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.

## See also

- Description of the option element in the HTML5 specification.

# p

Generates a `p` element.

## See also

- Description of the p element in the HTML5 specification

# pre

Generates a `pre` element.

## See also

- Description of the pre in the HTML5 specification.

# q

Generates a `q` element.

## See also

- Description of the q element in the HTML5 specification.

# s

Generates a `s` element.

## See also

- Description of the s element in the HTML5 specification.

# samp

Generates a `samp` element.

## See also

- Description of the samp element in the HTML5 specification.

# 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`.

## See also

- http://www.w3.org/TR/html5/scripting-1.html#the-script-element

# section

`section`

## See also

- http://www.w3.org/TR/html5/text-level-semantics.html#the-section-element

# 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.

## See also

- Description of the select element in the HTML5 specification.

# small

Generates a `small` element.

## See also

- Description of the small element in the HTML5 specification.

# 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`

## See also

- http://www.w3.org/TR/html5/text-level-semantics.html#the-span-element

# spanIfNotEmpty

`span`

## See also

- http://www.w3.org/TR/html5/text-level-semantics.html#the-span-element

# strong

Generates a `strong` element.

## See also

- http://www.w3.org/TR/html5/text-level-semantics.html#the-strong-element

# sub

Generates a `sub` element.

## See also

- Description of the sub element in the HTML5 specification.

# sup

Generates a `sup` element.

## See also

- Description of the sup element in the HTML5 specification.

# table

Generates a `table` element.

## See also

- Description of the table element in the HTML5 specification.

# table//caption

Generates a `caption` element representing the caption of a table.

## See also

- Description of the caption element in the HTML5 specification.

# tbody

Generates a `tbody` element.

## See also

- Description of the tbody element in the HTML5 specification.

# td

Generates a `td` element.

## See also

- Description of the td element in the HTML5 specification.

# 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.

## See also

- Description of the textarea element in the HTML5 specification.

# tfoot

Generates a `tfoot` element.

## See also

- Description of the tfoot element in the HTML5 specification.

# th

Generates a `th` element.

## See also

- Description of the th element in the HTML5 specification.

# thead

Generates a `thead` element.

## See also

- Description of the thead element in the HTML5 specification.

# time

Generates a `time` element.

## See also

- Description of the time element in the HTML5 specification.

# title

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

- `show-text`
- `show-page-title`

## See also

- http://www.w3.org/TR/html5/document-metadata.html#the-title-element
- #show-text
- #show-page-title

# tr

Generates a `tr` element.

## See also

- Description of the tr element in the HTML5 specification.

# track

Generates a `track` element.

## See also

- Description of the track element in the HTML5 specification.

# u

Generates a `u` element.

## See also

- Description of the u element in the HTML5 specification.

# ul

Generates an `ul` element.

## See also

- Description of the ul element in the HTML5 specification.

# var

Generates an `var` element.

## See also

- Description of the var element in the HTML5 specification.

# 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.

## See also

- Description of the video element in the HTML5 specification.

# wbr

Generates a `wbr` element.

## See also

- Description of the wbr element in the HTML5 specification.

# 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.

# breadcrumbs

Show the breadcrumbs for the current page. The separator between each breadcrumb is provided by the child element `breakcrumb-separator`. The contents of this element is used a separator between the breadcrumbs. This allows it to use simple characters of more complex HTML.

## Attributes

omit-root

  If set the `yes`, the breadcrumb for the root level is omitted.

omit-last

  If set the `yes`, the breadcrumb for last entry (the current category) is omitted.

# navigation

Root element for rendering a navigation menu. This element has several attributes which control some aspects of the rendering.

## Attributes

navigation-id

  The ID of the navigation/category system to use for the menu. If not set the default value `categoryMenu` is used which should be sufficent in most use cases.

with-colorset

  Decides if the navigation elements gets colorset classes. Default value is `false`

min-level

  The minimum level to render. If set to a value higher than `1` all levels below this value will be skipped. Use this if you want to split your navigation menu. For example: First level as horizontal menu at the top, other levels as horizontal menu on the left. Default value is `1`.

max-level

  The maximum level to render. Only levels below and including this level will be used for the menu.. Use this if you want to split your navigation menu. For example: First level as horizontal menu at the top, other levels as horizontal menu on the left. Default value is `999`.

show-description-text

  Decides if the description of each category is passed to the link (`a` element) for the `title` attribute. Default value is `true`.

# navigation-home-link//navigation-title

Outputs the title of the current navigation inside a `navigation-home-link`.

#

# 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:parse-link`

Helper template to adjust links. (Copied from Mandalay)

## Result

### Result type

`any`

### Description

The adjusted link.

# Function `foundry:read-current-category`

## Result

### Result type

`any`

### Description

The path of the current category.