diff options
Diffstat (limited to 'web/templates/HOWTO.txt')
| -rw-r--r-- | web/templates/HOWTO.txt | 126 |
1 files changed, 0 insertions, 126 deletions
diff --git a/web/templates/HOWTO.txt b/web/templates/HOWTO.txt deleted file mode 100644 index 641878e..0000000 --- a/web/templates/HOWTO.txt +++ /dev/null @@ -1,126 +0,0 @@ -How to use Gondul templating -============================ - -We utilize Jinja2 templates. - -{# - This is a jinja2 comment! --#} - -{% set url = "localhost" -%} -{% set example_switch = "r1.tele" -%} - -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 - |