How to use Gondul templating
============================

We utilize Jinja2 templates.

{#
 This is a jinja2 comment!
-#}

{% set url = "localhost" -%}
{% set example_switch = "distro0" -%}

See http://jinja.pocoo.org/ for the full documentation of the templating
language.

The rest of this document is about templating as it relates to Gondul

Neat: This document is an actual template, so the examples are working
examples. The best place to view this HOWTO is in the Gondul GUI, where you
get a side-by-side comparison of the template and the rendered result.

URLs
====

To read raw (unprocessed) templates, see http://{{ url }}/templates

To see the rendered final result, see http://{{ url }}/api/templates

Otherwise, use the Template-tab at http://{{ url }}/

Basics
======

Gondul provides templating through two different, but similar mechanisms.

First, there are permanent templates, or server-side templates. These are
templates stored on the server and accessible by all Tech crew/equipment.

These are fetched typically through a HTTP GET request. E.g.:

http://{{ url }}/api/templates/switches.txt

Secondly, you can write templates yourself and POST them to Gondul. This is
highly useful for one-off templates or template development. The syntax is
the same.

Simply write a template-file and POST it with your favorite command-line
tool to:

http://{{ url }}/api/templates/WHATEVER

Example:

POST http://{{ url }}nms/api/templates/foobar < my-local-template

Available objects
=================

Gondul templates have two dictionaries available for general use. The first
is "options". This is a simple list of GET parameters. If you access
http://{{ url }}/api/templates/HOWTO.txt?foo=bar, options[foo] will evaluate to
"bar" in that template. This can be accessed in the template as:

Foo: {{ options["foo"] }}

The second object is the "objects" ... dictionary. This is a list of all
the HTTP API end-points, in all their glory. The key is the URL.

To use this, you need to review the relevant endpoint. This is best done by
reading the API documentation (or skimming through other templates). If you
want to acces e13-2's latency, for example, you can access
objects["public/ping"].switches["{{ example_switch }}"].latency4

As such: {{ objects["public/ping"].switches[example_switch].latency4 }}

The logic is that "public/ping" is the url: http://{{ url }}/api/public/ping, it
contains JSON that begins with "switches", a list of all switches, each
switch as a "latency4" object (among other things)

Other worth-while api-endpoints:

- read/switch-management - Management information
- public/switches - All switches
- read/snmp - All SNMP data

Filters
=======

Jinja2 uses a number of filters to transform variables. They can be used to
do anything from upper-case all text to pretty-print JSON objects. They are
used by piping a variable. For example: options|pprint . This will "pretty
print" the options-object:

{{ options|pprint }}

See http://jinja.pocoo.org/docs/dev/templates/#builtin-filters for a list
of available filters.

Loops
=====

You can easily loop over objects, such as switches, using a for-loop.
Combine this with the "dictsort" filter to get a sorted list.

{% for switch in objects["public/switches"].switches|dictsort %}
	Switch {{ loop.index }} is {{ switch[0] }} or {{ switch[1] }} or full version: {{ switch }}
{% endfor %}

To avoid having to worry about indices of tuples (e.g.: switch[0]), you can
also use a simpler style:

{% for key, value in objects["public/ping"].switches|dictsort %}
	Switch {{ loop.index }} is {{ key}} with latency4 of {{ value.latency4 }}ms
{% endfor %}

Work flow
=========

Recommended:

1. Read some other template with relevant data.
2. Open the API endpoints in your browser to review the data structure
3. Use query-parameters to provide user-selection (e.g.: ?switch=foobar)
4. Write your template on your local machine, test frequently by POST'ing it
5. When done: Ask us and we'll upload it server-side