Theme XML reference

This section provides a concise reference to the XML used to define themes.

The XML is held either:

  • As the value of the Theme manifest (system.THEME_MANIFEST) member of the theme node.
  • As the manifest.xml entry within a theme zip file.

<Manifest>

A theme is represented by an XML document with a high-level <Manifest> element, inside which are any number of <include>, <Resource> and <Property> elements, which can appear in any order.

<Manifest>
  <include>..</include>
  <Resource>
    :
  </Resource>
  <Property>
    :
  </Property>
</Manifest>

<include>

Each <include> element contains the node version reference or node reference of a theme, the definition of which should included in this theme such as that this theme extends the included one. Resources and properties in this theme that appear after the include will override like-named resources and properties in the included theme.

Multiple themes can be included. Resources and properties in included themes will override like-named resource and properties in previously-included themes.

<Resource>

A resource describes <head> content that should be included under certain conditions.

Resources have the form:

<Resource>
  <reference>..</reference>
  <requires>..</requires>
  <requiredBy>..</requiredBy>
  <follows>..</follows>
  <precedes>..</precedes>
  <section>..</section>
  <filter>..</filter>
  <content>..</content>
</Resource>

<reference>

Each resource must have a single <reference> element. This identifies:

  • A CSS class the presence of which triggers the inclusion of this resource
  • An arbitrary string used to identify this resource, which is included from <requires> clauses on other resources
  • The string "head", which indicates a top-level resource which is always included.

<requires>

A resource may have one or more <requires> elements, each of which contains a reference that identifies a resource that should be included whenever this resource is included.

It is not an error to require a resource that is not defined.

<requires> does not imply order. <requires> must often be used in conjunction with <follows> or <precedes>.

<requiredBy>

A resource may have on or more <requiredBy> elements, each of which contains a reference that identifies a resource the inclusion of which should trigger the inclusion of this resource. Having <requiredBy>X</requiredBy> in resource Y has exactly the same as <requires>Y</requires> in resource X. <requiredBy> is optional, and is used to add further dependencies to a resource without changing the resource.

Use <requiredBy>head</requiredBy> to include a resource in all cases.

<follows>

A resource may have one or more <follows> elements, each of which contains a reference that identifies a resource which, if present, this resource should follow.

It is not an error to follow a resource that is not defined.

<precedes>

A resource may have one or more <follows> elements, each of which contains the reference of another resource which, if present, should follow this resource.

It is not an error to precede a resource that is not defined.

<section>

A resource may have one or more <section> elements, each of which contains a string containing a section reference, and the effect of which is exactly the same as:

<requires>section-start</requires>
<follows>section-start</follows>
<requires>section-end</required>
<precedes>section-end</precedes>

The effect of this is to place the content of the resource within the given section. The built-in theme defines the following sections.

  • css-framework – CSS frameworks, such as Bootstrap, which should go first.
  • css-standard – standard CSS components, such as Metrici's own CSS.
  • css-theme – CSS that is specific to this theme.
  • js-framework – JavaScript frameworks, such as jQuery, which should go first.
  • js-standard – standard JavaScript components, such as Metrici's own JavaScript and jQuery plug-ins.
  • js-theme – JavaScript that is specific to this theme.

<filter>

Each resource may have a single <filter> element to provide fine control over whether resource content is written out.

The filter element lists one or more other resources all of which must be present for the content to be written out. For example <filter>nodeedit</filter> can be used to only show the content when the node edit form is present.

The elements <or>, <not> and <and> can be used within the filter element to express more complicated conditions:

  • <or> encloses a list of one or more resources at least one of which must be present to trigger the filter.
  • <and> encloses a list of one or more resources all of which must be present to trigger the filter. (In effect, <filter> acts as an <and>.)
  • <not> reverses a condition.

<or>, <not> and <and> can be nested. For example, the following filter can be used to only show the content for resource foo when not on the node edit form, or when foo-show is also present.

<Resource>
  <reference>foo</reference>
  <filter>
    <or>
      <not>nodeedit</not>
      foo-show
    </or>
  </filter>
  <content>
    .. Shown when not on the node edit form, or when foo-show is present ..
  </content>
</Resource>

Filters only apply to writing out the content. They do not stop dependencies from being brought in.

If no <filter> element is present, the content is always written out for the resource.

<content>

Each resource may have a single <content> element which contains the content to be written to the <head> area of the output page.

The content may use the placeholder ${rootPath} to identify the current server.

Content must be properly escaped, as in the following examples:

<content>&lt;script type="text/javascript" src="${rootPath}files/infoboard/infoboard.js"&gt;&lt;/script&gt;</content>
<content>&lt;link rel="STYLESHEET" href="${rootPath}files/infoboard/infoboard.css" type="text/css"/&gt;</content>

<Property>

Each <Property> element identifies a branding property for the theme. It has the form:

<Property>
  <reference>property reference</reference>
  <value>value</value>
</Property>

Property references match references of nodes that define the meaning of the properties. The following are used within the core Metrici application:

  • Application Name (system.PROPERTIES.applicationName) – the name of the application shown to the user.
  • Logo (system.PROPERTIES.logo) – HTML markup used in the top left of the page, intended to contain an icon or similar branding. Defaults to showing the application name with a link to the home page.
  • Small Logo (system.PROPERTIES.smallLogo) – HTML markup used at the top of the page when the page is narrow, intended to contain a small icon or similar branding. Defaults to the Logo property.
  • Footer (system.PROPERTIES.footer) – HTML markup for the footer.
  • Custom CSS (system.PROPERTIES.customCSS) – CSS to be added to the head area.

Property values are filtered to ensure that all HTML and CSS is clean and safe.