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 Creating a plugin 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:

1from django.dispatch import receiver
2
3from pretix.base.signals import register_text_placeholders
4
5
6@receiver(register_text_placeholders, dispatch_uid="placeholder_custom")
7def register_placeholder_renderers(sender, **kwargs):
8    from .placeholders import MyPlaceholderClass
9    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
BaseTextPlaceholder.identifier

This should return the identifier of this placeholder in the email.

This is an abstract attribute, you must override this!

BaseTextPlaceholder.required_context

This property should return a list of all attribute names that need to be contained in the base context so that this placeholder is available. By default, it returns a list containing the string “event”.

This is an abstract attribute, you must override this!

BaseTextPlaceholder.render(context)

This method is called to generate the actual text that is being used in the email. You will be passed a context dictionary with the base context attributes specified in required_context. You are expected to return a plain-text string.

This is an abstract method, you must implement this!

BaseTextPlaceholder.render_sample(event)

This method is called to generate a text to be used in email previews. This may only depend on the event.

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:

placeholder = SimpleFunctionalTextPlaceholder(
    'code', ['order'], lambda order: order.code, sample='F8VVL'
)

Signals

pretix.base.signals.register_text_placeholders = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to get all known text placeholders. Receivers should return an instance of a subclass of pretix.base.services.placeholders.BaseTextPlaceholder or a list of these.

As with all event-plugin signals, the sender keyword argument will contain the event.

pretix.base.signals.register_mail_placeholders = <pretix.base.signals.EventPluginSignal object>

DEPRECATED: This signal has a new name, please use register_text_placeholders instead.