7.7. KT - Karrigell Templates

KT is a simple template engine intended for use with Karrigell Service (.ks) scripts and Python scripts. The goals of KT are to:
  • Provide a simple templating system with no programatic controls (logic and loops etc to be handled in python)
  • Support the in-built Karrigell translation system
  • Support variable substitutions
  • Support the inclusion of other templates

7.7.1 KT template language syntax

KT templates are saved as text files with a .kt extension. The language uses the following tags, which are intermingled with other text, typically HTML.

Inclusion Tag

   @[template_url]

Include the template specified by template_url. URLs are processed in the same way they are processed in the Import() function. Relative paths are supported, and are relative to the parent template. Inclusions are processed recursively, so child templates can include other templates.

Substitution Tag

   $identifier
   $object.attribute
   $dictionary.key

Substitute an identifier with its value. Indentifiers can be either simple variable names, or can be objects or dictionaries. If dictionaries are used, the key must have the form of a valid python identifier.

Translation Tag

   _[string to translate]

Translate the string using the in-built Karrigell translation system. This is the equivalent of the _() function in .ks and python scripts and the Python Inside HTML <%_ %> syntax.

Combining Tags

   @[$identifier]
   _[$identifier]

Inclusions can be controlled from the calling script by setting the value of identifier to a template URL. The $object.attribute and $dictionary.key styles can also be used. This gives a great deal of flexibility in how templates are included. For example, a master template can hold the basic design of a page, then different child templates included in it under the control of the calling script. If a $identifier is not defined, or is a False value, then no inclusion is performed. This allows an inclusion to be "turned-off" by the calling script.

In theory $identifiers can be placed within translation tags, but is not recommended. It is better to perform translations in the calling script using the _() function.

7.7.2 Calling KT from within a script

Values to be included in templates are passed to the script as named arguments: 

   print KT(template_url, var1=var1, var2=var2, data=dict, row=row, this=THIS, ...)

The template URL points to the KT template file. KT uses the same rules as the Karrigell Import function uses to locate Python scripts.

The **dict syntax is also supported: 

   print KT(template_url, **dict)

For convenience, the Python built-in locals() function can be assigned to a named argument, making locals available in the template: 

   print KT(template_url, data=locals())

7.7.3 Processing

Templates are processed as follows
  1. All inclusions are processed recursively, building up a consolidated template. $identifiers in @[] tags are expanded first. If the $identifier is not defined or is a False value, no inclusion is performed and no error is raised. This allows the calling script to "turn off" an inclusion. Circular references are checked and a RecursionError is raised if a template tries to include itself, or a child template tries to include its parent.
  2. All other substitutions are performed on the consolidated template.
  3. Translations are performed.

7.7.4 Managing translations

The translation admin tool recognises kt files. It automatically extracts strings to be translated from inside _[] tags in the same way that it extracts translation strings from _() function calls and pih <%_ %> tags.

7.7.5 Unicode

KT converts all text to Unicode UTF-8, and returns a Unicode value.

7.7.6 Example

This is an example of a KT template, called template/master.kt: 

<html>
<head>
<link rel="stylesheet" href="$this.baseurl/css/my.css">
<title>MyApp $data.title</title>
</head>
<body>
@[$data.bodytmpl]
<hr>
<i>_[Powered by Karrigell]</i>
<p />
</body>
</html>

Note how THIS is passed to KT and used to help define URLs to CSS style sheets and the like.

The tag @[$data.bodytmpl] includes another template, the name of which is held by the identifier $data.bodytmpl. In this example, we will set the value of $data.bodytmpl to index.kt.

index.kt contains this code: 

<h1>Welcome to $data.who home page!<h1>

This code snippet shows how the template would be called from within a ks script called /myapp.ks" 

def index():
    SET_UNICODE_OUT("utf-8")
    title = ' -  home'
    who = 'my'
    bodytmpl = 'index.kt'
    print KT('template/master.kt', data=locals(), this=THIS)

If the reader's browser was set to English, calling /myapp.kt/index would produce this html: 

<html>
<head>
<link rel="stylesheet" href="/css/my.css">
<title>MyApp - home</title>
</head>
<body>
<h1>Welcome to my home page!</h1>
<hr>
<i>Powered by Karrigell</i>
<p />
</body>
</html>

If the browser's default language is set to French, and the translation is defined in the Karrigell admin tool, the result would be: 

<html>
<head>
<link rel="stylesheet" href="/css/my.css">
<title>MyApp - home</title>
</head>
<body>
<h1>Welcome to my home page!</h1>
<hr>
<i>Motorisé par Karrigell</i>
<p />
</body>
</html>