# salt.renderers.jinja

Jinja loading utils to enable a more powerful backend for jinja templates

Important

Jinja supports a secure, sandboxed template execution environment that Salt takes advantage of. Other text Renderers do not support this functionality, so Salt highly recommends usage of `jinja` / `jinja|yaml`.

salt.renderers.jinja.render(template_file, saltenv='base', sls='', argline='', context=None, tmplpath=None, **kws)

  Render the template_file, passing the functions and grains into the Jinja rendering system.

  Return type:

    string

class salt.utils.jinja.SerializerExtension(environment)

  Yaml and Json manipulation.

  Format filters

  Allows jsonifying or yamlifying any data structure. For example, this dataset:

      data = {
          'foo': True,
          'bar': 42,
          'baz': [1, 2, 3],
          'qux': 2.0
      }

      yaml = {{ data|yaml }}
      json = {{ data|json }}
      python = {{ data|python }}
      xml  = {{ {'root_node': data}|xml }}

  will be rendered as:

      yaml = {bar: 42, baz: [1, 2, 3], foo: true, qux: 2.0}
      json = {"baz": [1, 2, 3], "foo": true, "bar": 42, "qux": 2.0}
      python = {'bar': 42, 'baz': [1, 2, 3], 'foo': True, 'qux': 2.0}
      xml = """<<?xml version="1.0" ?>
               <root_node bar="42" foo="True" qux="2.0">
                <baz>1</baz>
                <baz>2</baz>
                <baz>3</baz>
               </root_node>"""

  The yaml filter takes an optional flow_style parameter to control the default-flow-style parameter of the YAML dumper.

      {{ data|yaml(False) }}

  will be rendered as:

      bar: 42
      baz:
        - 1
        - 2
        - 3
      foo: true
      qux: 2.0

  Load filters

  Strings and variables can be deserialized with load_yaml and load_json tags and filters. It allows one to manipulate data directly in templates, easily:

      {%- set yaml_src = "{foo: it works}"|load_yaml %}
      {%- set json_src = '{"bar": "for real"}'|load_json %}
      Dude, {{ yaml_src.foo }} {{ json_src.bar }}!

  will be rendered as:

      Dude, it works for real!

  Load tags

  Salt implements `load_yaml` and `load_json` tags. They work like the import tag, except that the document is also deserialized.

  Syntaxes are `{% load_yaml as [VARIABLE] %}[YOUR DATA]{% endload %}` and `{% load_json as [VARIABLE] %}[YOUR DATA]{% endload %}`

  For example:

      {% load_yaml as yaml_src %}
          foo: it works
      {% endload %}
      {% load_json as json_src %}
          {
              "bar": "for real"
          }
      {% endload %}
      Dude, {{ yaml_src.foo }} {{ json_src.bar }}!

  will be rendered as:

      Dude, it works for real!

  Import tags

  External files can be imported and made available as a Jinja variable.

      {% import_yaml "myfile.yml" as myfile %}
      {% import_json "defaults.json" as defaults %}
      {% import_text "completeworksofshakespeare.txt" as poems %}

  Catalog

  `import_*` and `load_*` tags will automatically expose their target variable to import. This feature makes catalog of data to handle.

  for example:

      # doc1.sls
      {% load_yaml as var1 %}
          foo: it works
      {% endload %}
      {% load_yaml as var2 %}
          bar: for real
      {% endload %}

      # doc2.sls
      {% from "doc1.sls" import var1, var2 as local2 %}
      {{ var1.foo }} {{ local2.bar }}

  ** Escape Filters **

  Added in version 2017.7.0.

  Allows escaping of strings so they can be interpreted literally by another function.

  For example:

      regex_escape = {{ 'https://example.com?foo=bar%20baz' | regex_escape }}

  will be rendered as:

      regex_escape = https\:\/\/example\.com\?foo\=bar\%20baz

  ** Set Theory Filters **

  Added in version 2017.7.0.

  Performs set math using Jinja filters.

  For example:

      unique = {{ ['foo', 'foo', 'bar'] | unique }}

  will be rendered as:

      unique = ['foo', 'bar']

  ** Salt State Parameter Format Filters **

  Added in version 3005.

  Renders a formatted multi-line YAML string from a Python dictionary. Each key/value pair in the dictionary will be added as a single-key dictionary to a list that will then be sent to the YAML formatter.

  For example:

      {% set thing_params = {
          "name": "thing",
          "changes": True,
          "warnings": "OMG! Stuff is happening!"
         }
      %}

      thing:
        test.configurable_test_state:
          {{ thing_params | dict_to_sls_yaml_params | indent }}

  will be rendered as:

      .. code-block:: yaml

  > thing:
  >   test.configurable_test_state:

  >     - name: thing

  >     - changes: true

  >     - warnings: OMG! Stuff is happening!