All complex custom content in Imprint is generated by the plugins <introduction-layers-plugins>. Plugins are implemented by special configurable :pycallable objects called handlers that follow a specific interface, which allows them to be referenced by the appropriate tags in the configuration-xml.
Three types of content are supported out of the box: plugins-figures, plugins-tables and plugins-strings. Each type of plugin accepts a mapping of keywords from the configuration-ipc (and the xml-spec-tags-expr tags in the configuration-xml), and a dictionary of data configuration values from the configuration-idc that defines the behavior of the plugin. Beyond that, each type of handler has a different interface.
In fact, any custom :py~imprint.core.tags.TagDescriptor may define its own plugin interface. What makes a tag pluggable is its reliance on a function that accepts a data configuration. This technically makes the plugin API an implementation of a very distinct part of the tag_api.
Contents
The data configuration is the second argument to every handler. The data configuration is a mapping set for every plugin in the configuration-idc. The name of the configuration dictionary is in the id attribute <configuration-idc-names> of the corresponding xml-spec-tags-figure, xml-spec-tags-table or xml-spec-tags-string placeholder tag in the configuration-xml. Custom tags may be registered as configurable plugins by setting the :py~imprint.core.tags.TagDescriptor.data_config attribute of their :py~imprint.core.tags.TagDescriptor.
Data configuration values can contain any type of values, as long as they are meaningful to the plugin. Plugins may require some keys to be present in the configuration, and should raise a :py~imprint.core.KnownError, optionally caused by a :pyKeyError in response to missing keys. Most plugins will require some sort of data source, such as a file name, but again, this is not required.
Some values are special, in that they can override XML attibutes used by the :py~imprint.core.tags.TagDescriptor. In particular, the handler attribute can be overridden by a key with the similar name in the configuration-idc. Overridable values are noted for each builtin tag <xml-spec-tags> in the xml_spec.
Handlers are named by the handler attribute of the corresponding xml-spec-tags-figure, xml-spec-tags-table or xml-spec-tags-string placeholder tag in the configuration-xml. The exact class name (including package) is searched for the handler. If not found, a prefix of imprint.handlers is prepended to the nominal package name.
The handler can be overridden in the plugins-data-configuration dictionary. Normally, all configuration keys are interpreted directly by the handler. However, a special handler key will processed before a handler is found, and can override the setting in the XML. This mechanism is provided by each of the tag-api-descriptors for plugins-figures, plugins-tables and plugins-strings. It allows for more flexible debugging, and modification of existing templates. New tag-api-descriptors can use the :py~imprint.core.tags.get_handler function to implement the same functionality, although it is not stritcly required.
Some built-in figure handler examples can be found in imprint.handlers.figure.
xml-spec-tags-figure
Some built-in table handler examples can be found in imprint.handlers.table.
xml-spec-tags-table
Some built-in string handler examples can be found in imprint.handlers.string.
xml-spec-tags-string
Since plugins implement a subset of the tag-processing functionality, the same rules apply to plugin errors at to generic tag errors. See tag-api-descriptor-errors in the tag_api section.
imprint.handlers
imprint.handlers.figure
ImageFile
imprint.handlers.figure.images
imprint.handlers.table
CSVFile
DataFrame
imprint.handlers.table.tables
imprint.handlers.string
TextFile
imprint.handlers.string.strings
imprint.handlers.utilities