Template Rendering

Template rendering is the process of generating a file similar to template’s content but where variables have been replaced with actual values. These values come from settings or parameters.

Template engine

ComodIT uses FreeMarker as template engine, here is an example of template’s content:

<html>
<head>
    <title>Simple Web Page</title>
</head>
<body>
    <p>Hello world !</p>
    <p>Setting key: simple_web_page</p>
    <p>Setting value: ${simple_web_page}</p>

    <ul>
    <#list list_setting as l>
        <li>${l}</li>
    </#list>
    </ul>

    <p>Struct a: ${struct_setting.a}</p>
    <p>Struct b: ${struct_setting.b}</p>
</body>
</html>

In this example, the template contains 3 variables:

  • simple_web_page: should be replaced by a string, for example “Hello”
  • list_setting: should be replaced by a list of strings, for example [“1”, “2”, “3”]
  • struct_setting: should be replaced by a structure defining 2 fields a and b, for example {“a”: “a value”, “b”: “b value”}.

Given above variable values, rendered template will look like this:

<html>
<head>
    <title>Simple Web Page</title>
</head>
<body>
    <p>Hello world !</p>
    <p>Setting key: simple_web_page</p>
    <p>Setting value: Hello</p>

    <ul>
        <li>1</li>
        <li>2</li>
        <li>3</li>
    </ul>

    <p>Struct a: a value</p>
    <p>Struct b: b value</p>
</body>
</html>

Parameters, settings and templates

Depending on template container (application, distribution or platform), different settings are used for rendering. For example, when rendering a distribution’s file, values for variables are looked-up in distribution’s parameters, distribution’s settings, organization’s settings, environment’s settings, host’s settings and finally distribution context’s settings.

Of course, several settings may define different values for the same variable. Priorities have therefore been defined, the setting having the highest priority assigning its value to the variable. Let x < y denote the fact that x has a lower priority than y, then priorities are defined as follows:

  • distribution’s template: DP < DS < OS < ES < HS < DCS < RDS
  • platform’s template: PP < PS < OS < ES < HS < PCS
  • application’s template: AP < OS < ES < HS < ACS

where:

  • xP denotes x’s parameters
  • yS denotes y’s settings
  • O stands for organization
  • E stands for environment
  • H stands for host
  • D stands for distribution
  • P stands for platform
  • A stands for application
  • RDS stands for rendered distribution settings

Internal variables

A variable having a name starting with an underscore (‘_’) is a special variable injected by ComodIT called private variable. Note that it is not possible to create a parameter or a setting targeting this kind of variable. It is therefore impossible to override the values injected by ComodIT. Again, depending on which kind of template is rendered, different private variables may be available.

Global private variables:

  • _config.api: ComodIT’s API URL
  • _config.rabbitmq_hostName: AMQP server hostname
  • _config.rabbitmq_portNumber: AMQP server port
  • _config.rabbitmq_virtualHost: AMQP server default virtual host
  • _org.name: Name of host’s organization
  • _org.uuid: UUID of host’s organization
  • _env.name: Name of host’s environment
  • _env.uuid: UUID of host’s environment
  • _host.name: Name of host
  • _host.uuid: UUID of host

Distribution private variables:

  • _application.packages: packages of all application’s installed on host
  • _application.services: services of all application’s installed on host
  • _setup_url: One-time URL to setup URL (see host resource)
  • _urls: One-time URLs to rendered distribution files; if distribution has a template x, rendering of _urls[“x”] is a one-time URL to rendered version of x.

Platform private variables:

  • _distribution: structure containing _urls value (see above) and rendered distribution settings.

Application private variables:

  • _distribution: settings of host’s distribution context; for example, if distribution context has a setting with key x, _distribution.x is the value of this setting.
  • _platform: settings of host’s platform context; for example, if platform context has a setting with key x, _platform.x is the value of this setting.

Distribution context private variables:

  • _distribution.name: name of the distribution

Platform context private variables:

  • _platform.name: name of the platform

Application context private variables:

  • _application.name: name of the application
  • _application.services.X.enabled: boolean variable telling if service X is enabled i.e. starting at boot time as defined at the application level
  • _application.services.X.active: boolean variable telling if service X is active i.e. enabled or activated at the application context level

Methods

Methods are used to transform on-the-fly variable values. For example, let a method f and a variable v be defined, the result of applying f to v can be displayed in a rendering with the following sentence in your template:

${f(v)}

Currently, ComodIT provides a single method _hash which hashes an input string. An optional second argument provides the hash algorithm to use (by default, “MD5” is used), this argument can take any of the values supported by Java’s MessageDigest.getInstance for instance MD5, SHA-1, SHA-256, etc. The output string is the hexadecimal representation of generated bytes.

For example, in order to display the content of variable v hashed with SHA-1 algorithm, you should insert the following sentence in your template:

${_hash(v,"SHA-1")}