Friday 7 October 2016

Introduction to TACTIC Plugins


TACTIC Plugins are a way of packaging up functionality and distributing them
to other projects or other servers.

The Plugin architecture is very flexible and almost any functionality, large
or small can be packaged in as a plugin.

A TACTIC Plugin can contain:

  1. data
  2. configuration
  3. python class
  4. 4mages and media
  5. css and javascript libraries


At the core of a TACTIC Plugin is a manifest file.  The manifest file tells TACTIC how to load and unload a plugin.  It is an xml file and is placed at the root of the plugin folder.  A simple example of on is as follows:

<manifest>
  <data>
    <code>spt.whatever</code>
    <title>XYZ</title>
  </data>
  <sobject search_type="custom/asset"/>
</manifest>

It declares what data belongs to the plugin.

The above manifest will create a plugin that will export all entries from the "custom/asset" search
type to a file called "custom_asset.spt".  Files with ".spt" extension are TACTIC custom files that are used for importing and exporting data.  The syntax used is exactly the same as Python (a python processor is used to read the data), however they are not self-contained and executable and thus not really considered ".py" files. However, if desired, any python code could be added and it should be processed correctly.

When loading the plugin, the "sobject" will read the corresponding ".spt" file and insert the new sobjects into the database.  On unloading the plugin, the entire table will be removed.  This because the line states that the entire table belongs to the plugin.  This is useful for custom search types, but often it is desireble for the plugin to own a subset of table.  The easiest way to do this is with an expression

<sobject search_type="custom/asset" expression="@SOBJECT(custom/asset['asset_type','image'])"/>

This will export all the sobjects with the column asset_type equal to "image".  This
allows multiple plugins to share data in the same search type.  Care must be taken so
that a given sobject only belongs to a single plugin to avoid conflicts.

To control the output file the data is written to, the "path" attribute can be used.

<sobject search_type="custom/asset" path="config/asset.spt"/>

This file created will be relative to the manifest file.  This can be used to
break up a single table into multiple files, if that is desired.

It is quite common not to wnat all the columns in the exported file.  The
"ignore_columns" attribute can be used to specify columns that are not exported.

<sobject search_type="custom/asset" igonre_columns="id,code,timestamp"/>

The code and id are commonly not exported.   The "id" column is usually auto
generated, so their exact values are not important as long as they are not used
to relate to other table.  This prevents conflicts of ids loaded in from other
plugins.  If the code needs to be exported, it is important to ensure that this
code will be unique enough to be loaded even if data is already filled in that table.

If the definition of a search_type needs to be exported, the "search_type" tag can
be used:

<search_type code="custom/asset"/>

This will save out the entire search_type definition into the ".spt" file.  This makes
it possible for a plugin to own the definition of a search_type allowing a plugin
to define a data model.

With the combination of the <search_type> tag and the <sobject> tag, almost any
configuration data can be stored in a plugin.


When a plugin is loaded, the plugins folder is also accessible from the web server.
This means that images and other files can be put into a plugin and be visible by
a client web broser.

For example:

<img src="/plugins/test_plugin/media/image.png"/>

This would be visible by the following URL:

http://<server>/plugins/test_plugin/media/image.png

This allows the plugin to package up different image files as well as javascript and css files.

This was just a small introduction to TACTIC plugins.  The plugin architecture is flexible enough that almost any TACTIC functionality can be encapsulated in one.