CSS Templates

CSS templates are special kinds of templates designed to bring the flexibility of Aria Templates to your style declarations. CSS templates benefit from all the advantages of the template engine, such as variables, macros, control statements or scripts.

Definition and use

CSS Templates are defined using the CSSTemplate statement and stored with the .tpl.css extension:

As shown above, in its simplest form, a CSS template really is a template file in which styles declarations are defined directly inside the main macro.

To use these declarations from an HTML template, you just need to reference the classpath in the $css configuration property:

Note that $css expects an array since you might want to include more than just one CSS template.

Similarities and differences with HTML templates

Of course, if CSS templates were just about embedding styles inside a template declaration they wouldn't be very useful. Their interest obviously resides in the features offered by the templating engine.

Syntax and allowed statements

You write CSS templates the same way you would write an HTML template. The main difference is that you don't need to escape the curly brackets characters ({ and }). Contrary to basic CSS files, both comments formats (// and /*...*/) are accepted.

Most of the AT statements can be used in CSS templates and irrelevant ones (id, on, section, checkDefault, and createView) are noted as such in the Writing Templates article.

As illustrated in the example below, CSS templates really come in handy when conditional processing or repetitive declarations are concerned.

Special variables

Because they are meant to be shared among different modules, CSS templates do not have access to external data by design. They do however provide access to two special variables besides those explicitly declared in the template itself using var. They are:

  • cssPath: the complete classpath of the CSS Template file, using folder notation, e.g. ariadoc/snippets/templates/cssTemplates/MyCssTemplate.

  • cssFolderPath: the URL of the CSS template location, relative to the Aria.rootFolderPath.

The latter in particular is quite useful to define URLs of images located in the same folder as your CSS files. Note that it takes into account the rootMap (not the urlMap) defined through the download manager.

Both of these properties are inherited from the CSSTemplate class.

Declaration and configuration

CSS Templates can use inheritance. Using $extends and the classpath of another CSS template, it makes it easy to reuse styles defined in other templates (see the [article about template inheritance](template inheritance).)

CSS Templates also support scripts when the $hasScript property is true. The script has to be defined in the same way as for HTML Templates.) This mechanism is particularly useful when complex logic has to be used.

Here's how a script method would be declared:

...and then used in a CSS template:
Note: At the moment, macro libraries cannot be used in CSS Templates.

Using CSS templates

The framework provides automatic scoping for style rules defined in CSS templates in order to avoid collisions. This is done transparently by prefixing all the definitions with a unique global class selector assigned to the HTML element in which the template is rendered.

For instance, an application may include two different templates with their own css style for the main header:

h1 {
    color: red;


h1 {
    color: green;

These 2 rules will be translated as follow by AT:

.CSS1 h1 {
    color: red;
.CSS2 h1 {
    color: green;

This definition is ultimately injected in a < style > statement inside the < head > of the page. The HTML container of the respective templates are then assigned the CSS1 and CSS2 classes.

In some cases, for example for CSS3 @font-face/@keyframes rules, if users do not want to have a prefix generated from Aria Template they can set $prefix as false in CSS Template and below is the snippet for the same.

Note that it is also possible to include a CSS template as dependency in a normal class, using the $css property. This is mainly used when defining custom widgets.

CSS Template code sample

A few remarks on this example:

  • Two macros are defined inside the css template (opacity and roundedCorners). Macros and control statements can be useful for generating CSS rules that depend on the browser.

  • The cssFolderPath has been used in order to specify the path of the background pattern image.

  • The cssClass and type configuration properties of sections have been used in order to style them in the CSS template.

  • The getClassName and setClassName methods of the aria.templates.DomElementWrapper class are used in the template script in order to change the appearance of each item after clicking on it.

Processing urls inside CSS Templates

It is possible to set at application level a method that process all the urls specified inside css templates. The property to use is imgUrlMapping that specifies the name of the method to call.

The property's type is json:FunctionRef and its default value is null.

When the method is set, the framework calls it and waits for a string to use to replace all the urls inside all the CSS templates.

One use case is url prefixing for media defined inside CSS rules. Using this feature the framework prefixes all the images, font-faces and basically every CSS property that accepts url. So the feature gives the possibility to the users to easily add medias without useless worries about paths and use a specific method to handle them.

For example, let's say the user wants to add a background image using CSS, but he doesn't where the static files will be finally deployed, so he writes something like this:

using this property the final result is something like this: