Tags

Tags provide a way of adding functionality to your templates. While they do add some logical elements to the view layer, they enable you to completely perform operations in the view without ever writing PHP.

Syntax: {% tag_name 'tag parameter 1' 'tag parameter 2' tag_parameter_variable_3 #tag_config_parameter_4# %}

You can have any number of parameters – this is defined in the documentation of each tag. Some tags will have an opening and closing tag (if tags, foreach tags, block tags).

Outlast Framwork supports all of the tags of the Django template system. These are not documented here yet so please read them on Django’s site.

You can also add your own custom tags or use any of Outlast Framework’s extended tag set, the documentation for which is available below.

{% if %}

Tag: if, elseif, endif – Identical to Django’s if tags, but elseif also supports parameters (see example below).

{% if products.total < 5 %}
You have less then 5 products
{% elseif products.total = 5 %}
You have 5 products.
{% else %}
You have more than 5 products
{% endif %}

1. conditionals You can pass conditional statements. Unlike php, = can be used to test equality (it will not set the variable). You can also use these operators: < lt > gt <= lteq >= gteq = == eq !=. You can combine your statements with and or or. You can also negate with not. The ordering is the same as in php.

{% foreach %}

Tag: foreach – Identical to Django’s for loop tag, but this adds a syntax similar to php’s foreach.

{% foreach users as user %}{% endforeach %}
1. list_field – The first parameter is the list of items to run through. It must be an array, a fetcher object, or another object with iterative capabilities.
2. as_field – This will be the variable name of the item within the tag each time it runs.

While the for loop is running, you have access to the following special variables:
forloop.counter The current iteration of the loop (1-indexed)
forloop.counter0 The current iteration of the loop (0-indexed)
forloop.revcounter The number of iterations from the end of the loop (1-indexed)
forloop.revcounter0 The number of iterations from the end of the loop (0-indexed)
forloop.first True if this is the first time through the loop
forloop.last True if this is the last time through the loop
forloop.odd True if the current iteration count is odd number (rows 1, 3, 5, etc.).
forloop.even True if the current iteration count is even number (rows 2, 4, 6, etc.).
forloop.key The key of the for loop. This is useful typically for stdClass objects or associative arrays.
forloop.value The current value of the for loop. This is the same as the variable specified after “as”.
forloop.previous The value of the for loop in the previous iteration. During the first iteration it wil be false.
forloop.parentloop For nested loops, this is the forloop object of the loop above the current one
forloop.depth The number of nested forloops above me (including myself, so starts at 1).
forloop.totalcounter The current iteration of all nested loops (1-indexed)
forloop.totalcounter0 The current iteration of all nested loops (0-indexed)

Tip In design, you often need to display something every nth row. For example, you can use {% if forloop.counter0|divisibleby:3 %}{% endif %} to display something every third row.

Tip If you want to use the {% foreach %} tag with pagination you should check out the available pagination variables as well.

{% input %}

Tag: input – Generates an input field based on the input defined in the model. So, a field of type photo will generate a photo upload box.

{% input user.avatar user.data.avatar %}
1. model_field – The field name defined in the model. The format is model_name.field_name.
2. default_value – The default value. This will usually be the existing data of the model object.
{% input user.password user.data.password 'custom.field.html' %}
3. custom_html – If you want to use a custom HTML to generate your own field editor then you can specify the html relative to any of the view directories. You should use input editor variables within your HTML.

{% inputlocale %}

Tag: inputlocale – Generates a locale-enabled input field based on the input defined in the model. This must be supported by the model and field type.

{% inputlocale user.avatar user.data.avatar 'sk_SK' %}
1. model_field – The field name defined in the model. The format is model_name.field_name.
2. default_value – The default value. This will usually be the existing data of the model object.
3. locale – The locale name to use. If left empty, the current locale will be used.
4. custom_html – If you want to use a custom HTML to generate your own field editor then you can specify the html relative to any of the view directories.

{% inputfilter %}

Tag: inputfilter – Generates a filter input for the given field which you can then apply on server side using the filter_query() method (see docs) on any zajFetcher list.

{% inputfilter contentpage.featured 'custom_filter.html' %}

1. model_field – The field name defined in the model. The format is model_name.field_name.
2. custom_html – optional – If you want to use a custom HTML to generate your own field filter then you can specify the html relative to any of the view directories.

You should check out the detailed documentation on generating and applying list filters.

{% parentblock %}

Tag: parentblock – Inserts code from the block of the same name in the parent template. Useful for extending block contents instead of replacing it.

See this link for more details.

{% include %}

Tag: include – Reroute request to an app controller by request url (relative to base url).

{% include '/path/to/reroute/to/' parameter1 'parameter value 2' %}

1. request – The request which will be routed as any other such URL request to a controller method.
2. optional parameters – zero, one, or more optional parameters, passed as parameters to the controller method.

{% insert %}

Tag: insert – Inserts another template at this location. The template is treated as if it were inline.

{% insert '/admin/news_edit.html' 'block_name' %}

1. template_file – The template file to insert.
2. block_section – If you only want to insert the block section from the file. (optional)

{% insertlocale %}

Tag: insertlocale – Same as {@link insert} except that this also checks for localized versions of the HTML file before including. Localized files can be stored with the locale before the extension, as in filename.en_US.html.

{% insertlocale '/section/news.html' 'block_name' %}

1. template_file – The template file to insert.
2. block_section – If you only want to insert the block section from the file. (optional)

This example will check to see if there is a localized version at /section/news.en_US.html (assuming the current locale is en_US). If one is not found for the current locale, it will attempt to load the default, locale-free version at /section/news.html.

As with insert, the block_section is optional! The tag was previously known as {% insertlocal %} (without the e) but that is now deprecated.

{% lorem %}

Tag: lorem – Generates a lorem ipsum text.

{% debug %}

Tag: debug – Outputs some exciting debug information.

{% time %}

Tag: time – Generates a unix time stamp

{% dump %}

Tag: dump – Dump the value of the variable to output.

{% dump forum.messages %}

1. variable – The variable to dump.

{% count %}

Tag: count – Loop which counts from the first value to the second and places it in the third param.

{% count '1' '10' as counter %}{{counter}}. Commandment!{% endcount %}
{% count from '10' to '1' as counter %}{{counter}}. Countdown!{% endcount %}

1. from – Count from this number.
2. to – Count to this number.
3. counter – Use this variable to store the current counter value.

{% literal %}

Tag: literal – The section in between is taken as literal, meaning it is not compiled.

{% config %}

Tag: config – Loads a configuration file in full or just a specified section

{% config 'file_name.conf.ini' 'section_name' %}

1. file_name – A filename of the configuration file relative to the conf directory.
2. section_name – The name of the section to load. If omitted, the entire file will be loaded.
3. force_set – If set to true, the variables will be set even if the file was already loaded previously.

{% configjs %}

Tag: configjs – Loads a specific section of a configuration file in to ofw.config (and ofw.lang) object

{% configjs 'file_name' 'section_name' %}

1. file_name – A filename of the config file relative to the conf directory.
2. section_name – The name of the section to load. Required for configjs.

See detailed docs on using config variables in Javascript.

{% lang %}

Tag: lang – Loads a language file in full or just a specified section

{% lang 'file_name' 'section_name' %}

1. file_name – A filename of the language file relative to the lang directory. The preferred way is to exclude .lang.ini.
2. section_name – The name of the section to load. If omitted, the entire file will be loaded.
3. force_set – If set to true, the variables will be set even if the file was already loaded previously.

For more on language files see

{% langjs %}

Tag: langjs – Loads a specific section of a language file in to ofw.lang (or ofw.config) object

{% langjs 'file_name' 'section_name' %}

1. file_name – A filename of the language file relative to the lang directory.
2. section_name – The name of the section to load. Required for langjs.

See detailed docs on using language variables in Javascript.

{% unique %}

Tag: unique – Generates a random unique id using php’s uniqid(“”) and prints it or saves it to a variable.

{% unique as uid %}

1. variable – Variable which to save the unique id. If specified, no output will be generated. If not specified, uniqid will be echoed.

{% applyfilter %}

Tag: applyfilter – Applies the specified filters to the variable and sets it as the value. Similar to {% with %} except that applyfilter sets the value for the remainder of the document. If you don’t explicitly need this, we recommend using {% with %} as {% applyfilter %} can cause unexpected outcomes!

{% applyfilter counter|add:'1' as incremented %}

1. counter – In this example counter will be incremented by one each time it is encountered. The filtered value (incremented by one) is set back to the original.
2. incremented – The second variable specifies how the filtered value will be known from now on. You can use the original value if you want to modify the original.

{% cachebuster %}

Tag: cachebuster – Cache buster can be used to generate a random number (actually a shortened time stamp). If placed after the url of an asset file they will force the browser to load the latest version after each template cache reset. So in effect, after each deployment the local cache of users will be reset. This is not too efficient but useful when the file in question is changing quite often during development.

<link rel="stylesheet" type="text/css" href="style.css?{% cachebuster %}">

{% cycle %}

Tag: cycle – Cycle among the given strings or variables each time this tag is encountered.

{% cycle var1 'text' var3 %}

1. var1 – Use this the first time through.
2. var2 – Use this the second time through.
etc…

{% random %}

Tag: random – Randomly cycle among the given strings or variables each time this tag is encountered.

{% random var1 'text' var3 %}

1. var1 – Choose this randomly.
2. var2 – Choose this randomly.
etc.

{% with %}

Tag: with – Caches a variable value under a different name. This is useful when using widgets where a specific variable name is expected (see creating dynamic menus with DRY as a practical example) or when accessing an “expensive” smart or filtered variable (e.g., one that hits the database) multiple times.

You can specify multiple items within a single {% with %} tag. The old {% with complex as simple %} is also still supported, though deprecated.

{% with total=business.data.employees.total first=business.data.employees|first %}...{% endwith %}

1. some_complex_value – You can specify a variable or expression here that you want to cache.
2. variable_name – This is the variable name by which the value will be known until you reach endwith.

{% with photos=product.data.photos items=product.data.relatedproducts %}
  {% insert 'widgets/gallery' %}
{% endwith %}

The {% endwith %} tag will unset any variables you defined.