Plugin Development Overview

Plugin development overview

The plugin development process begins with creating a properly structured plugin directory in a place where Sal can find it. This directory will contain several files. First, a Yapsy plugin file to specify some metadata about the plugin and allow the plugin system to find the plugin should be created. The plugin file itself is a python file with a single class definition, as specified in the Yapsy file. The plugin will need a Django template file to render its output for display. Finally, scripts may optionally include any number of scripts for clients to run, which can then submit custom data to the Sal database for the plugin to use in generating its output.

Plugin folder structure

The plugin folder structure should be named for the plugin it contains and should be structured as below (using "encryption" as the example plugin's name).

• encryption (dir)
  • encryption.py (Plugin python module)
  • encryption.yapsy-plugin (Yapsy metadata file)
  • scripts (dir) (optional)
    • script.py (Any name, any number, executable script files)
    • ...
  • templates (dir)
    • encryption.html (Django template file)

The .yapsy-plugin file

The .yapsy-plugin is how Sal knows about your plugin. The filename should match the name of your plugin. The file itself is in the Python INI format. There is one required section: [Core] and the two required key-value pairs: Name and Module. Module should match the filename of the plugin's python module. Name is the name of the class contained in the plugin file.

You can also include other data about the plugin, like in the example below.

[Core]
Module = encryption
Name = Encryption

[Documentation]
Author = Graham Gilbert
Version = 0.1
Website = http://grahamgilbert.com

The python module

Template Concepts

It may help to familiarize yourself with Django's templating system. The docs start here: https://docs.djangoproject.com/en/2.0/intro/tutorial03/

If you are already familiar with Jinja2 or some other templating system, you're in luck!

In brief, Sal's templates are html files that are used for the actual output in a web browser. Any time you see curly braces (e.g. {{ hostname }} or {% if os_family != 'Darwin' %}, that's a templatetag, a place where Django will replace data from your plugin's context in the template's html. You can do pretty involved things using for loops and other tags, so please examine the builtin plugins and Django's documentation for more ideas.

Template use

By default, without specifying a template path, Sal will look for a template in your plugin's templates folder, with the same name as the python module and a .html extension. If possible, it's best to use a single template file, unless the complexity of doing so results in heinously ugly and convoluted conditional template code.

If multiple template files are needed, you will need to override the get_template method of the plugin, which is parameterized with the group_type and group_id values to allow you to conditionally select a template.

Template Style

Sal uses Bootstrap for its CSS framework. bootstrap. Take a look at the builtin plugins' templates to get an idea of how to use Bootstrap to style your plugin.

Sal includes MorrisJS in all templates for easy charting. You can of course use any charting library of your choosing by making sure to add any <script> includes for that library in your template file.

Other default Javascript includes are jQuery, metisMenu, and DataTables.

Machine List Links

To have your plugin include links to the Sal machine_list view (a DataTable of client machine), construct a URL using the url templatetag:

 <a href="{% url 'machine_list' plugin 'ok' group_type group_id %}">

If you have used the super_get_context method to create your context object, the plugin, group_type, and group_idvalues will already be present in thecontext`.