An Introduction to customising the layout
Before you start - this may help
The HTML output generated by the pulse web application framework is based on layout templates. We will introduce you the templates as they are used to generate the "demo layout" as it always comes by default with the current binary distribution of the framework.
Understanding how the HTML output is being genereated
The layout templates for pulse are written in XSLT (a declarative, XML-based language used for the transformation of XML documents into other XML documents such as XHTML).
The framework generates XML-output upon request which is then being transformed using XSL-templates to the resulting HTML-output. For a better understanding of the pulse framework you may also refer to the chapters of the documentation dealing with the configuration.
We recommend - turning on the debug area
Before you start we highly recommend turning on the debug area. The debug area will
add the current XML-output which is being for the transformation to the bottom
of the page of the "demo layout". This can be done easily by changing the following
setting to true in "WEB-INF/xsl/globals.xsl":
<!-- debug area in demo layout --> <xsl:variable name="debug.site">false</xsl:variable>
We tried to keep it simple - the layout of the pulse demo
The pulse demo from the binary release already comes with a basic layout implemented for demonstration and testing purposes. Therefore we tried to keep them rather simple. We will give a quick overview of how the templates are organised and where all the other layout specific resources are located. Most templates do contain further explanatory inline comments.
Where? - location of the templates
All the XSL-templates used for generating the demo layout are located in the following folders and their sub-folders:
- /WEB-INF/xsl/... (main.xsl and global templates)
- /WEB-INF/components/.../xsl/... (component specific templates)
Where? - location of the CSS, JavaScript and the images
All the other resources used for generating the demo layout are located in the following folders and their sub-folders:
- /css/... (main and global CSS-files)
- /lib-js/... (global JavaScript resources)
- /resources/Bundles/... (further bundle-specific resources)
- /resources/components/... (further component-specific resources)
Continue reading about components and bundles.
The point of entry - description of the main.xsl
The main.xsl is the main point of entry for the transformation which generates the HTML-output. Besides the default templates it does include the main.xsl-templates of the used components (which provide the component-specific XSL-templates). Furthermore it defines the output-encoding.
The main.xsl builds the HTML-frame for the page to be generated by the transformation. It holds the side-bar and the footer of the demo-layout.
Via the main.xsl the follwing global resources are included:
- main and global CSS-files
- global JavaScript resources
Utility and global templates included by main.xsl
The "WEB-INF/xsl/main.xsl" includes the following main and global XSL-templates:
- WEB-INF/xsl/globals.xsl - includes global XSL-variables for usage throughout all the XSL-templates
- WEB-INF/xsl/error-templates.xsl - templats for displaying server-errors
- WEB-INF/xsl/debug.xsl - when enabled, displays the generated XML which can be for debugguing during XSL-template developement
Settings in WEB-INF/xsl/globals.xsl
The globals globals.xsl provides the following settings and global variables:
- settings regarding the debug-area
- settings regarding the recording of statistics
- the versioning prefix
- path-constants, which define default resource locations
- "
$locale", globally defines the current request-locale - includes "
xhtml.xsl" - used for tranforming XML to XHTML
i18n - localisation of templates
For template localisation we use a concept we refer to as babelfish.xsl. The main idea behind the babelfish.xsl templates is to provide a set of re-usable XSL-templates, where localasations and other locale-specific templates can be easliy retrieved from by simply passing parameters. The localisation templates are usually located in ".../i18n/..."-folders within the ".../xsl/..."-folders.
The main.xsl of a component - all the other templates
The component-specific main XSL-templates - as located in "/WEB-INF/components/.../xsl/main.xsl" - do provide the global component-specifc XSL-templates as well as they include further comonent-specific XSL-templates for the demo-layout.