forked from CGM_Public/pretix_original
bac673f3ab
* remove duplicate context generation * allow text templates in frontpage_text * refactor: move placeholder functionality to separate file * fix wrong class name, code style * update year in license header * undo license header update * use new function name * render only the placeholders that are actually used in the message * refactoring * add str(...) call * Update doc/development/api/placeholder.rst Co-authored-by: Raphael Michel <michel@rami.io> * rename register_mail_placeholders to register_template_placeholders (deprecate old name) * isort * add signals to docs --------- Co-authored-by: Raphael Michel <michel@rami.io>
93 lines
2.8 KiB
ReStructuredText
93 lines
2.8 KiB
ReStructuredText
.. highlight:: python
|
|
:linenothreshold: 5
|
|
|
|
Writing a template placeholder plugin
|
|
=====================================
|
|
|
|
A template placeholder is a dynamic value that pretix users can use in their email templates and in other
|
|
configurable texts.
|
|
|
|
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 placeholders. Your plugin
|
|
should listen for this signal and return an instance of a subclass of ``pretix.base.services.placeholders.BaseTextPlaceholder``:
|
|
|
|
.. code-block:: python
|
|
|
|
from django.dispatch import receiver
|
|
|
|
from pretix.base.signals import register_text_placeholders
|
|
|
|
|
|
@receiver(register_text_placeholders, dispatch_uid="placeholder_custom")
|
|
def register_placeholder_renderers(sender, **kwargs):
|
|
from .placeholders import MyPlaceholderClass
|
|
return MyPlaceholder()
|
|
|
|
|
|
Context mechanism
|
|
-----------------
|
|
|
|
Templates are used in different "contexts" within pretix. For example, many emails are rendered from
|
|
templates in the context of an order, but some are not, such as the notification of a waiting list voucher.
|
|
|
|
Not all placeholders make sense everywhere, and placeholders usually depend on 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 a context where 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.services.placeholders.BaseTextPlaceholder
|
|
|
|
.. 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 = SimpleFunctionalTextPlaceholder(
|
|
'code', ['order'], lambda order: order.code, sample='F8VVL'
|
|
)
|
|
|
|
Signals
|
|
-------
|
|
|
|
.. automodule:: pretix.base.signals
|
|
:members: register_text_placeholders
|
|
.. automodule:: pretix.base.signals
|
|
:members: register_mail_placeholders
|
|
|