mirror of
https://github.com/pretix/pretix.git
synced 2026-01-02 18:42:27 +00:00
84 lines
2.5 KiB
ReStructuredText
84 lines
2.5 KiB
ReStructuredText
.. highlight:: python
|
|
:linenothreshold: 5
|
|
|
|
Writing an e-mail placeholder plugin
|
|
====================================
|
|
|
|
An email placeholder is a dynamic value that pretix users can use in their email templates.
|
|
|
|
Please read :ref:`Creating a plugin <pluginsetup>` first, if you haven't already.
|
|
|
|
Placeholder registration
|
|
------------------------
|
|
|
|
The placeholder API does not make a lot of usage from signals, however, it
|
|
does use a signal to get a list of all available email placeholders. Your plugin
|
|
should listen for this signal and return an instance of a subclass of ``pretix.base.email.BaseMailTextPlaceholder``:
|
|
|
|
.. code-block:: python
|
|
|
|
from django.dispatch import receiver
|
|
|
|
from pretix.base.signals import register_mail_placeholders
|
|
|
|
|
|
@receiver(register_mail_placeholders, dispatch_uid="placeholder_custom")
|
|
def register_mail_renderers(sender, **kwargs):
|
|
from .email import MyPlaceholderClass
|
|
return MyPlaceholder()
|
|
|
|
|
|
Context mechanism
|
|
-----------------
|
|
|
|
Emails are sent in different "contexts" within pretix. For example, many emails are sent in the
|
|
the context of an order, but some are not, such as the notification of a waiting list voucher.
|
|
|
|
Not all placeholders make sense in every email, and placeholders usually depend some parameters
|
|
themselves, such as the ``Order`` object. Therefore, placeholders are expected to explicitly declare
|
|
what values they depend on and they will only be available in an email if all those dependencies are
|
|
met. Currently, placeholders can depend on the following context parameters:
|
|
|
|
* ``event``
|
|
* ``order``
|
|
* ``position``
|
|
* ``waiting_list_entry``
|
|
* ``invoice_address``
|
|
* ``payment``
|
|
|
|
There are a few more that are only to be used internally but not by plugins.
|
|
|
|
The placeholder class
|
|
---------------------
|
|
|
|
.. class:: pretix.base.email.BaseMailTextPlaceholder
|
|
|
|
.. autoattribute:: identifier
|
|
|
|
This is an abstract attribute, you **must** override this!
|
|
|
|
.. autoattribute:: required_context
|
|
|
|
This is an abstract attribute, you **must** override this!
|
|
|
|
.. automethod:: render
|
|
|
|
This is an abstract method, you **must** implement this!
|
|
|
|
.. automethod:: render_sample
|
|
|
|
This is an abstract method, you **must** implement this!
|
|
|
|
Helper class for simple placeholders
|
|
------------------------------------
|
|
|
|
pretix ships with a helper class that makes it easy to provide placeholders based on simple
|
|
functions:
|
|
|
|
.. code-block:: python
|
|
|
|
placeholder = SimpleFunctionalMailTextPlaceholder(
|
|
'code', ['order'], lambda order: order.code, sample='F8VVL'
|
|
)
|
|
|