Types of plug-ins
=================

Tattler plug-ins can be either:

**Addressbook plug-ins**
    Allow you to give tattler information about a user (notification recipient).

**Context plug-ins**
    Allow you to give tattler data to fill out template variables.

Tattler can operate both without and with plug-ins. You can also provide multiple plug-ins of each type.

Each type of plug-in is coded in python, by extending a class.

Plug-in interface
-----------------

Regardless of the type, you provide any plug-in by placing a python script into a special folder.

This file must fulfill these requirements:

- Be written in python.

- Be placed in the folder pointed to by the :ref:`TATTLER_PLUGIN_PATH <configuration:TATTLER_PLUGIN_PATH>` configuration directive.

- Be named with suffix ``_tattler_plugin.py``.

- Contain one class which subclasses either:
   - class :class:`AddressbookPlugin <tattler.server.pluginloader.AddressbookPlugin>` if you are providing an :ref:`Addressbook plug-in <plugins/addressbook:Addressbook plug-ins>`.
   - class :class:`ContextPlugin <tattler.server.pluginloader.ContextPlugin>` if you are providing a :ref:`Context plug-in <plugins/context:Context plug-ins>`.

So if you configure ``TATTLER_PLUGIN_PATH=foo/my_plugin_path``, this directory may look like this::

    foo/my_plugin_path/
    ├─ foo.py                       # <- will be ignored: wrong suffix
    ├─ users_tattler_plugin.py
    └─ billing_tattler_plugin.py


Plug-in chains
--------------

For each `type of plug-in <Types of plug-ins>`_ you may provide zero, one or multiple plug-ins.

If you provide multiple plug-ins, they are processed in sequence, in the alphanumeric order of their class names.

:ref:`Addressbook plug-ins <plugins/addressbook:Addressbook plug-ins>` are run in sequence
until one provides any data.

:ref:`Context plug-ins <plugins/context:Context plug-ins>` are run in sequence, and:

- The first plug-in receives the native context generated by Tattler.
- Each subsequent plug-in receives the context returned by its preceding plug-in.

.. mermaid::

    flowchart LR
        TattlerServer --> |native context| Plugin1
        Plugin1 --> |context1| Plugin2
        Plugin2 --> |context2| Templates