diff options
| -rw-r--r-- | web/templates/HOWTO.txt | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/web/templates/HOWTO.txt b/web/templates/HOWTO.txt new file mode 100644 index 0000000..a8233e5 --- /dev/null +++ b/web/templates/HOWTO.txt @@ -0,0 +1,88 @@ +How to use Gondul templating +============================ + +We utilize Jinja2 templates. + +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. + +URLs +==== + +To read raw (unprocessed) templates, see http://nms/templates + +To see the rendered final result, see http://nms/api/templates + +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://nms/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://nms/api/templates/WHATEVER + +Example: + +POST http://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://nms/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["e13-2"].latency4 + +As such: {{ objects["public/ping"].switches["e13-2"].latency4 }} + +The logic is that "public/ping" is the url: http://nms/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 + +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 + + + |