templates.pod

LIXUZ TEMPLATE MANUAL - INTRODUCTION

This is the Lixuz template manual. It serves as an introduction and reference for the Lixuz template system.

The version described here is version 1 of the Lixuz template API.

Conventions used

Whenever the word "{as}" (without the quotes) appear, what is meant is the value supplied to the as= parameter to a needinfo source.

BASIC FORMAT

At the base of the Liuxz template format lies Mason (HTML::Mason) and Catalyst. Anything you can do with mason, you can do with a Lixuz template, and you also have access to the $c catalyst object. Lixuz leaves all of the actual code parsing to Mason, but requires an additional data block to be present in all templates that lets Lixuz know things about the template.

A block can look like this (all options are not required, see the section on INFOBLOCK DATA for more information on the various settings):

<%perl>
# BEGIN LIXUZ_INFOBLOCK
# TEMPLATE_VERSION=0.1
# TEMPLATE_NAME=Lixuz basic article page
# TEMPLATE_LICENSE=Proprietary
# TEMPLATE_APIVERSION=1
# TEMPLATE_TYPE=article
# TEMPLATE_NEEDSINFO=article_get_[artid=url,as=article,includeRelations=1,includeComments=1,handleComments=1]
# TEMPLATE_FILESPOT=[type=image,name=Primary image,as=primaryImage,id=1]
# TEMPLATE_INCLUDES=no.lixuz.header no.lixuz.footer no.lixuz.subscribeNewsletter
# TEMPLATE_UNIQUEID=no.lixuz.basicArticle
# END LIXUZ_INFOBLOCK
</%perl>

Any template can only have one infoblock and Lixuz will stop processing the file when it hits the first END LIXUZ_INFOBLOCK. You can have comments inside an infoblock by using ## at the start of the line instead of just #.

VALIDATION AND DEBUGGING

As Lixuz templates are primarily mason templates, the first thing you should do if you experience issues is to try to validate that the Mason template is valid. This can for instance be done with the ./tools/masontest.pl file included with Lixuz. This program is an approximate equivalent to 'perl -c' for mason templates.

Secondly, consult the list of required infoblock data above. If you have forgotten an entry, it will not render the template.

Thirdly, check the Lixuz logfile. If something goes wrong while rendering the template, that's where the error information will be available.

UPDATING LIVE TEMPLATES MANUALLY

Lixuz has a builtin template replacement function, but for quick updates it is often much easier to upload it manually (ie. using rsync or scp) to the server than to enter the Lixuz web UI. The templates can be found in the directory defined by LIXUZ:template_path in the Lixuz config file. Here the files are named with both their template_id (at the beginning of the filename) and their uniqueid, so it should be simple to find the one you want to replace. Once you have found it you can simply overwrite it with your new version. If you did not change the infoblock then you can just reload the page that is not working to see if your changes are now working (checking the logfile for whining). If you did change the infoblock then you will have to empty memcached. It's not recommended that you do that on a live server so you ought to have a debugging server. Emptying memcached can be done either from within the Lixuz web UI on the templates page, or by restarting memcached.

MORE INFORMATION

You can get more information on the various template formats by reading the associated documentation:

docs/templates/EmailTemplates.pod

Contains documentation on the format for templates used to render e-mails sent by Lixuz.

docs/templates/WebTemplates.pod

Contains documentation on the format for templates that are used to render the live website that is running under Lixuz.

docs/templates/MediaTemplates.pod

Contains documentation on the special templates that are used to render certain media content to the live website that is running under Lixuz. These are similar to the web templates, but as they are used to render specific components, they have some special limitations (and functions).