Writing an e-mail placeholder plugin¶

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:

1
2
3
4
5
6
7
8
9

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¶

BaseMailTextPlaceholder.identifier¶

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

This is an abstract attribute, you must override this!

BaseMailTextPlaceholder.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!

BaseMailTextPlaceholder.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!

BaseMailTextPlaceholder.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 = SimpleFunctionalMailTextPlaceholder(
    'code', ['order'], lambda order: order.code, sample='F8VVL'
)