Contao is an open-source web content management system with a constantly growing fan base. Recently toxA has published an extension for Contao to use LESS CSS, an extension to CSS language. In addition that extension enables control of variables defined in LESS to have customizable themes.
Theme configuration manager providing access to a single LESS file's variables
As of today, May 6th 2011, the extension tx_less is available as an alpha-release. Though it has been tested by developer it’s considered to show up errors in selected setups due to its complexity in code. Installation is done by repository manager of Contao. Once installed, it’s starting to capture any rendered page for transparently embedding LESS parser on demand. Therefore it’s searching folders of a page’s theme for containing any LESS definition files. Found and enabled files are then processed on server for updating contained variable definitions according to separately managed registration in database. In conjunction with the original client-side processor of lesscss.org updated LESS files are finally integrated in page for live processing.
Controlling LESS files is completely integrated in Contao’s theme manager. By extending its page layout module it is possible to select a subset of LESS files to be used. Controlling variables in LESS files becomes available by introducing another module next to page layout and style sheet managers. That module is parsing all LESS files of a theme for contained variable definitions and some special internal comments used to document LESS file, its structure and contained variables.
Using LESS in a Theme
In Contao every theme is optionally associated with one or more folders of File Manager. All these folders may contain LESS files and are recognized by tx_less. A very relaxed LESS parser included with tx_less is detecting contained variable definitions preparing for updating them in-place. Additionally it’s processing special internal comments starting with three instead of two leading slashes for documentation purposes.
Writing Documenting Comments
All internal comments starting with three leading slashes are processed for containing documentation. Such documentation pieces may refer to the current scope, to the file as a whole in “top-level” scope or to any variable defined in one of those scopes. On listing files and on grouping variable definitions of a file for controlling its values related documentation is presented to user e.g. for explaining affected elements of theme. Documentation of variables is rendered next to every variable’s control in tx_less’ theme configuration manager.
Documenting comments differ in whether they include a variable’s name or not. If you want to provide documentation on a variable you need to insert its name including leading @ right before the comment’s content. After optional variable name, but before any actual content a locale tag enclosed in brackets may be inserted to select association of succeeding text with that locale. Omitting that locale selector english locale is preselected by default. That way it’s possible to have localized theme documentation. Here are some examples:
/// The following variables control colours used in whole theme. /// [de] Die folgenden Variablen steuern die Farben, welche im /// [de] gesamten Theme zum Einsatz kommen. /// @pageBGColour controls background colour of whole page /// @pageBGColour [de] legt die Hintergrundfarbe der Seite fest
In lines 2-3 this example illustrates opportunity to put longer documentations into separate lines. All documenting comments related to same locale and scope or variable are collected and assigned together.
Special Widgets
Theme configuration manager introduced by tx_less is providing interface for adjusting all defined variables in a LESS file. This is basically consisting of a single-line text input control per variable. On detecting special variables names or values in parsed LESS file some special widgets may be added to provide more convenient control.
- All variables with names ending in size, width, height, dim or extent are optionally controlled using widget providing separate unit selector and amount input supporting cursor-key control.
- Variables with names ending in color or colour are accompanied by color picker control.
- Finally, variables with names ending in url, image or file are extended by file picker for selecting file from Contao’s file manager.
If name isn’t matching, another detection stage is trying to match certain value formats.
- Numeric values optionally including unit are detected as extent information, e.g. -4.5em.
- Colour selections in hex format are detected as such, e.g. #ffdd44.
- url(…)-values are detected as file selections.
Every such extended control is optional. Users may choose to hide them for using original single line text input control instead. This is as required since LESS always supports calculations, invoking methods and referring to other LESS variables. If detecting type of variable succeeded before because of a proper name ending it’s still possible to have value not conforming with format related with detected type. Then, extended widget is hidden by default and must be selected explicitly.
