XSLT views

A page's XML document, built from its components, becomes HTML through XSLT 1.0 stylesheets run by PHP's XSLTProcessor (libxslt). The stylesheets use the EXSLT functions set:distinct and dyn:evaluate; PHP functions are not available in them.

The main stylesheet

The configuration key document.transformer — main.xslt in the starter — names the main stylesheet in site/modules/main/transformers/. The starter's includes the views of every module, then the site's own:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:output method="html" doctype-system="about:legacy-compat"/>
    <xsl:include href="../../../../core/modules/share/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/user/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/calendar/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/apps/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/forms/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/comments/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/mail/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/ads/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/blog/transformers/include.xslt"/>
    <xsl:include href="../../../../core/modules/shop/transformers/include.xslt"/>
    <xsl:include href="include.xslt"/>
</xsl:stylesheet>

The site's include.xslt includes energine.xslt, the site's page: its match="/" builds <html> with the head and the body, and match="document" places the layout's components and the content. Stylesheets are read where they lie — they are not linked into htdocs, so an edit needs no setup run — and they are compiled on every request: there is no stylesheet cache.

What a stylesheet receives

The page's XML has the root <document> with the attributes debug and editable, and inside it:

  • <properties> — the page's title, keywords, description, robots and template, the site's address (base, with the addresses of static files, media and the resizer) and the language;
  • <layout> and <content> — the components and containers of the templates;
  • <translations> — the interface strings the components registered;
  • <javascript> — the scripts the components need.

document.xslt gives them global variables: $DOC_PROPS, $COMPONENTS, $TRANSLATION, $BASE, $LANG_ID, $LANG_ABBR, $STATIC_URL, $MEDIA_URL, $RESIZER_URL and others.

How a component is matched

A component's element carries name, class — the short class name — componentAction — its state — and properties such as type (list or form), exttype (grid for grids) and sample. Templates match on them:

  • component[@type='list'] and component[@type='form'] are the generic views of lists and forms;
  • component[@sample='TextBlock'] shows every text block;
  • a class of your own is matched by component[@class='Hello'].

The text block's view:

<xsl:template match="component[@sample='TextBlock']">
    <xsl:if test="@editable or recordset/record/field != ''">
        <div class="textblock">
            <xsl:apply-templates/>
        </div>
    </xsl:if>
</xsl:template>

Two classes with one short name match alike: Energine\apps\components\Ads and Energine\ads\components\Ads are both Ads, and the starter's layout tells them apart by name. XML that no template matches is copied into the page as it is.

Changing a view

Put your templates into a file in site/modules/main/transformers/ and include it from the site's include.xslt. It comes after the core's, so a template with the same pattern replaces the core one; a more specific pattern or an explicit priority makes the choice certain.

The head, styles and scripts

document.xslt builds the head: the title (the page's own HTML title, or the breadcrumbs), <base>, stylesheets/energine.css, the site's stylesheets/main/main.css and print.css, and the meta tags. Then come MooTools 1.5.2 and scripts/Energine.js. The behaviours that components name in their configs are loaded through the script map htdocs/system.jsmap.php, which php index.php setup scriptMap writes; without the map no page is built. jQuery 2.1.4 comes from Google's CDN, and only for behaviours that need it; see Known risks. The empty template match="/" mode="scripts" in document.xslt is the place for your own scripts.

Seeing the XML

With debug on in the configuration, ?debug after a page's address returns the page's XML document instead of HTML, and error pages show the file and the line. Keep debug off on a live site.

Other stylesheets are chosen in code: error_page.xslt for errors, the seo module's ones for robots.txt and the sitemap, rss.xslt for the news feed and the shop's single_*.xslt windows.