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.
Topics Covered:
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