Writing Plugins

Imprint is all about customization, and the Plugins Layer is the crux of that customization. But what exactly is a plugin, and how do you write one? This tutorial aims to provide a step-by-step, hands-on, introduction the types of plugins that are supported, and how to write them.

A plugin is a callable that creates the dynamic content that makes gives Imprint its power. Each plugin fulfills a particular interface, defined by the XML tag that it is bound to. There are three main types of content that can be generated by default: Figures, Tables and Strings. Custom tags that support plugins can be created as well. This advanced topic is covered in the content_tutorial.

While different types of plugins are different from each other, there are a few common features they all share. The first two arguments to each of the built-in Handlers are the dictionary of Keywords and the Data Configuration. The remaining arguments depend on the specific tag. Custom tags are not strictly required, but highly encouraged, to follow this convention.

Tables

Tables are generally the most complex type of plugin for the builtin tags, since they have to modify the document in-place as they generate their content. This leads to interesting artifacts, like partially generated tables in case of an error. Broken Figures and Strings are entirely replaced by alt-text, but tables will generally be generated up to the point where the error occurred.

It also means that the <table> tag does not handle data logging, instead leaving the task up to the discretion of individual plugins. This is very different from the simpler plugin tags like <figure> and <string>, which handle the data logging in a uniform manner, without delegation to a plugin.

Using Your Plugin

You made a plugin. Now what? How do you use it in the template you just created?

This is a two-step process. First you have to let Imprint and Python know where your plugin lives. Second, you have to refer to the plugin in your template somehow. Both steps are covered in detail in the next sections:

Registering Your Plugin

To register a plugin, you must place it in the Python Path. This is normally done with something like

import sys
sys.path.insert(0, 'path/to/plugin/module')

It is often convenient to put such a registration into a dedicated IIF File.

Todo

This has been totally changed by the ??? keyword.

Todo

Add an example

Note

Keep the import as import sys rather than from sys import path, since the latter will add a keyword to your namespace, while a module will be ignored after loading.

Referencing Your Plugin

Once a plugin is in your Python Path, you can reference it as you would any other module in your tag’s handler attribute.

Todo

Add an example