General APIs

This page lists some general signals and hooks which do not belong to a specific type of plugin but might come in handy for various plugins.

Core

pretix.base.signals.periodic_task = <django.dispatch.dispatcher.Signal object>

This is a regular django signal (no pretix event signal) that we send out every time the periodic task cronjob runs. This interval is not sharply defined, it can be everything between a minute and a day. The actions you perform should be idempotent, i.e. it should not make a difference if this is sent out more often than expected.

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

This signal is sent out to determine whether an event can be taken live. If you want to prevent the event from going live, return a string that will be displayed to the user as the error message. If you don’t, your receiver should return None.

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

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

This signal is sent out when a new event is created as a clone of an existing event, i.e. the settings from the older event are copied to the newer one. You can listen to this signal to copy data or configuration stored within your plugin’s models as well.

You don’t need to copy data inside the general settings storage which is cloned automatically, but you might need to modify that data.

The sender keyword argument will contain the event of the new event. The other keyword argument will contain the event to copy from. The keyword arguments tax_map, category_map, item_map, question_map, and variation_map contain mappings from object IDs in the original event to objects in the new event of the respective types.

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

This signal allows you to implement a middleware-style filter on all outgoing emails. You are expected to return a (possibly modified) copy of the message object passed to you.

As with all event-plugin signals, the sender keyword argument will contain the event. The message argument will contain an EmailMultiAlternatives object. If the email is associated with a specific order, the order argument will be passed as well, otherwise it will be None.

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

This signal is sent out to get all known notification types. Receivers should return an instance of a subclass of pretix.base.notifications.NotificationType or a list of such instances.

As with all event-plugin signals, the sender keyword argument will contain the event, however for this signal, the sender may also be None to allow creating the general notification settings!

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

This signal is sent out when a new product is created as a clone of an existing product, i.e. the settings from the older product are copied to the newer one. You can listen to this signal to copy data or configuration stored within your plugin’s models as well.

The sender keyword argument will contain the event. The target will contain the item to copy to, the source keyword argument will contain the product to copy from.

pretix.base.signals.register_sales_channels = <django.dispatch.dispatcher.Signal object>

This signal is sent out to get all known sales channels types. Receivers should return an instance of a subclass of pretix.base.channels.SalesChannel or a list of such instances.

Order events

There are multiple signals that will be sent out in the ordering cycle:

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

This signal is sent out before the user starts checkout. It includes an iterable with the current CartPosition objects. The response of receivers will be ignored, but you can raise a CartError with an appropriate exception message.

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

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

This signals allows you to add fees to an order while it is being created. You are expected to return a list of OrderFee objects that are not yet saved to the database (because there is no order yet).

As with all plugin signals, the sender keyword argument will contain the event. A positions argument will contain the cart positions and invoice_address the invoice address (useful for tax calculation). The argument meta_info contains the order’s meta dictionary. The total keyword argument will contain the total cart sum without any fees. You should not rely on this total value for fee calculations as other fees might interfere.

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

This signal is sent out every time an order is paid. The order object is given as the first argument. This signal is not sent out if an order is marked as paid because an already-paid order has been split.

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

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

This signal is sent out every time an order is placed. The order object is given as the first argument. This signal is not sent out if an order is created through splitting an existing order, so you can not expect to see all orders by listening to this signal.

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

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

This signals allows you to return a human-readable description for a fee type based on the fee_type and internal_type attributes of the OrderFee model that you get as keyword arguments. You are expected to return a string or None, if you don’t know about this fee.

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

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

This signal is sent out to check if tickets for an order can be downloaded. If any receiver returns false, a download will not be offered.

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

Frontend

pretix.presale.signals.html_head = <pretix.base.signals.EventPluginSignal object>

This signal allows you to put code inside the HTML <head> tag of every page in the frontend. You will get the request as the keyword argument request and are expected to return plain HTML.

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

This signal allows you to put code before the end of the HTML <body> tag of every page in the frontend. You will get the request as the keyword argument request and are expected to return plain HTML.

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

The signal pretix.presale.signals.footer_link allows you to add links to the footer of an event page. You are expected to return a dictionary containing the keys label and url.

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

pretix.presale.signals.front_page_top = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to display additional information on the frontpage above the list of products and but below a custom frontpage text.

As with all plugin signals, the sender keyword argument will contain the event. The receivers are expected to return HTML.

pretix.presale.signals.front_page_bottom = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to display additional information on the frontpage below the list of products.

As with all plugin signals, the sender keyword argument will contain the event. The receivers are expected to return HTML.

pretix.presale.signals.fee_calculation_for_cart = <pretix.base.signals.EventPluginSignal object>

This signals allows you to add fees to a cart. You are expected to return a list of OrderFee objects that are not yet saved to the database (because there is no order yet).

As with all plugin signals, the sender keyword argument will contain the event. A request argument will contain the request object and invoice_address the invoice address (useful for tax calculation). The total keyword argument will contain the total cart sum without any fees. You should not rely on this total value for fee calculations as other fees might interfere.

pretix.presale.signals.contact_form_fields = <pretix.base.signals.EventPluginSignal object>

This signals allows you to add form fields to the contact form that is presented during checkout and by default only asks for the email address. You are supposed to return a dictionary of form fields with globally unique keys. The validated form results will be saved into the contact_form_data entry of the order’s meta_info dictionary.

As with all plugin signals, the sender keyword argument will contain the event. A request argument will contain the request object.

pretix.presale.signals.question_form_fields = <pretix.base.signals.EventPluginSignal object>

This signals allows you to add form fields to the questions form that is presented during checkout and by default asks for the questions configured in the backend. You are supposed to return a dictionary of form fields with globally unique keys. The validated form results will be saved into the question_form_data entry of the position’s meta_info dictionary.

The position keyword argument will contain either a CartPosition object or an OrderPosition object, depending on whether the form is called as part of the order checkout or for changing an order later.

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

pretix.presale.signals.checkout_confirm_messages = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to retrieve short messages that need to be acknowledged by the user before the order can be completed. This is typically used for something like “accept the terms and conditions”. Receivers are expected to return a dictionary where the keys are globally unique identifiers for the message and the values can be arbitrary HTML.

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

pretix.presale.signals.checkout_confirm_page_content = <pretix.base.signals.EventPluginSignal object>

This signals allows you to add HTML content to the confirmation page that is presented at the end of the checkout process, just before the order is being created.

As with all plugin signals, the sender keyword argument will contain the event. A request argument will contain the request object.

pretix.presale.signals.checkout_all_optional = <pretix.base.signals.EventPluginSignal object>

If any receiver of this signal returns True, all input fields during checkout (contact data, invoice address, confirmations) will be optional, except for questions. Use with care!

As with all plugin signals, the sender keyword argument will contain the event. A request argument will contain the request object.

pretix.presale.signals.order_info = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to display additional information on the order detail page

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

pretix.presale.signals.order_meta_from_request = <pretix.base.signals.EventPluginSignal object>

This signal is sent before an order is created through the pretixpresale frontend. It allows you to return a dictionary that will be merged in the meta_info attribute of the order. You will receive the request triggering the order creation as the request keyword argument.

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

Request flow

pretix.presale.signals.process_request = <pretix.base.signals.EventPluginSignal object>

This signal is sent out whenever a request is made to a event presale page. Most of the time, this will be called from the middleware layer (except on plugin-provided pages this will be called by the @event_view decorator). Similarly to Django’s process_request middleware method, if you return a Response, that response will be used and the request won’t be processed any further down the stack.

WARNING: Be very careful about using this signal as listening to it makes it really easy to cause serious performance problems.

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

pretix.presale.signals.process_response = <pretix.base.signals.EventPluginSignal object>

This signal is sent out whenever a response is sent from a event presale page. Most of the time, this will be called from the middleware layer (except on plugin-provided pages this will be called by the @event_view decorator). Similarly to Django’s process_response middleware method you must return a response object, that will be passed further up the stack to other handlers of the signal. If you do not want to alter the response, just return the response parameter.

WARNING: Be very careful about using this signal as listening to it makes it really easy to cause serious performance problems.

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

Vouchers

pretix.presale.signals.voucher_redeem_info = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to display additional information on the “redeem a voucher” page

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

Backend

pretix.control.signals.nav_event = <pretix.base.signals.EventPluginSignal object>

This signal allows you to add additional views to the admin panel navigation. You will get the request as a keyword argument request. Receivers are expected to return a list of dictionaries. The dictionaries should contain at least the keys label and url. You can also return a fontawesome icon name with the key icon, it will be respected depending on the type of navigation. You should also return an active key with a boolean set to True, when this item should be marked as active. The request object will have an attribute event.

If you use this, you should read the documentation on how to deal with URLs in pretix.

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

pretix.control.signals.html_head = <pretix.base.signals.EventPluginSignal object>

This signal allows you to put code inside the HTML <head> tag of every page in the backend. You will get the request as the keyword argument request and are expected to return plain HTML.

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

pretix.control.signals.html_page_start = <django.dispatch.dispatcher.Signal object>

This signal allows you to put code in the beginning of the main page for every page in the backend. You are expected to return HTML.

The sender keyword argument will contain the request.

pretix.control.signals.quota_detail_html = <pretix.base.signals.EventPluginSignal object>

This signal allows you to append HTML to a Quota’s detail view. You receive the quota as argument in the quota keyword argument.

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

pretix.control.signals.nav_topbar = <django.dispatch.dispatcher.Signal object>

This signal allows you to add additional views to the top navigation bar. You will get the request as a keyword argument request. Receivers are expected to return a list of dictionaries. The dictionaries should contain at least the keys label and url. You can also return a fontawesome icon name with the key icon, it will be respected depending on the type of navigation. If set, on desktops only the icon will be shown. The title property can be used to set the alternative text.

If you use this, you should read the documentation on how to deal with URLs in pretix.

This is no EventPluginSignal, so you do not get the event in the sender argument and you may get the signal regardless of whether your plugin is active.

pretix.control.signals.nav_global = <django.dispatch.dispatcher.Signal object>

This signal allows you to add additional views to the navigation bar when no event is selected. You will get the request as a keyword argument request. Receivers are expected to return a list of dictionaries. The dictionaries should contain at least the keys label and url. You can also return a fontawesome icon name with the key icon, it will be respected depending on the type of navigation. You should also return an active key with a boolean set to True, when this item should be marked as active.

If you use this, you should read the documentation on how to deal with URLs in pretix.

This is no EventPluginSignal, so you do not get the event in the sender argument and you may get the signal regardless of whether your plugin is active.

pretix.control.signals.nav_organizer = <django.dispatch.dispatcher.Signal object>

This signal is sent out to include tab links on the detail page of an organizer. Receivers are expected to return a list of dictionaries. The dictionaries should contain at least the keys label and url. You should also return an active key with a boolean set to True, when this item should be marked as active.

If your linked view should stay in the tab-like context of this page, we recommend that you use pretix.control.views.organizer.OrganizerDetailViewMixin for your view and your template inherits from pretixcontrol/organizers/base.html.

This is a regular django signal (no pretix event signal). Receivers will be passed the keyword arguments organizer and request.

pretix.control.signals.nav_event_settings = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to include tab links on the settings page of an event. Receivers are expected to return a list of dictionaries. The dictionaries should contain at least the keys label and url. You should also return an active key with a boolean set to True, when this item should be marked as active.

If your linked view should stay in the tab-like context of this page, we recommend that you use pretix.control.views.event.EventSettingsViewMixin for your view and your template inherits from pretixcontrol/event/settings_base.html.

As with all plugin signals, the sender keyword argument will contain the event. A second keyword argument request will contain the request object.

pretix.control.signals.order_info = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to display additional information on the order detail page

As with all plugin signals, the sender keyword argument will contain the event. Additionally, the argument order and request are available.

pretix.control.signals.event_settings_widget = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to include template snippets on the settings page of an event that allows generating a pretix Widget code.

As with all plugin signals, the sender keyword argument will contain the event. A second keyword argument request will contain the request object.

pretix.control.signals.oauth_application_registered = <django.dispatch.dispatcher.Signal object>

This signal will be called whenever a user registers a new OAuth application.

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

To display an instance of the LogEntry model to a human user, pretix.base.signals.logentry_display will be sent out with a logentry argument.

The first received response that is not None will be used to display the log entry to the user. The receivers are expected to return plain text.

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

To display the relationship of an instance of the LogEntry model to another model to a human user, pretix.base.signals.logentry_object_link will be sent out with a logentry argument.

The first received response that is not None will be used to display the related object to the user. The receivers are expected to return a HTML link. The internal implementation builds the links like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
a_text = _('Tax rule {val}')
a_map = {
    'href': reverse('control:event.settings.tax.edit', kwargs={
        'event': sender.slug,
        'organizer': sender.organizer.slug,
        'rule': logentry.content_object.id
    }),
    'val': escape(logentry.content_object.name),
}
a_map['val'] = '<a href="{href}">{val}</a>'.format_map(a_map)
return a_text.format_map(a_map)

Make sure that any user content in the HTML code you return is properly escaped! As with all event-plugin signals, the sender keyword argument will contain the event.

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

To display an instance of the RequiredAction model to a human user, pretix.base.signals.requiredaction_display will be sent out with a action argument. You will also get the current request in a different argument.

The first received response that is not None will be used to display the log entry to the user. The receivers are expected to return HTML code.

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

Vouchers

pretix.control.signals.item_forms = <pretix.base.signals.EventPluginSignal object>

This signal allows you to return additional forms that should be rendered on the product modification page. You are passed request and item arguments and are expected to return an instance of a form class that you bind yourself when appropriate. Your form will be executed as part of the standard validation and rendering cycle and rendered using default bootstrap styles. It is advisable to set a prefix for your form to avoid clashes with other plugins.

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

Vouchers

pretix.control.signals.voucher_form_class = <pretix.base.signals.EventPluginSignal object>

This signal allows you to replace the form class that is used for modifying vouchers. You will receive the default form class (or the class set by a previous plugin) in the cls argument so that you can inherit from it.

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

pretix.control.signals.voucher_form_html = <pretix.base.signals.EventPluginSignal object>

This signal allows you to add additional HTML to the form that is used for modifying vouchers. You receive the form object in the form keyword argument.

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

pretix.control.signals.voucher_form_validation = <pretix.base.signals.EventPluginSignal object>

This signal allows you to add additional validation to the form that is used for creating and modifying vouchers. You will receive the form instance in the form argument and the current data state in the data argument.

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

Dashboards

pretix.control.signals.event_dashboard_widgets = <pretix.base.signals.EventPluginSignal object>

This signal is sent out to include widgets in the event dashboard. Receivers should return a list of dictionaries, where each dictionary can have the keys:

  • content (str, containing HTML)
  • display_size (str, one of “full” (whole row), “big” (half a row) or “small” (quarter of a row). May be ignored on small displays, default is “small”)
  • priority (int, used for ordering, higher comes first, default is 1)
  • url (str, optional, if the full widget should be a link)

As with all plugin signals, the sender keyword argument will contain the event. An additional keyword argument subevent can contain a sub-event.

pretix.control.signals.user_dashboard_widgets = <django.dispatch.dispatcher.Signal object>

This signal is sent out to include widgets in the personal user dashboard. Receivers should return a list of dictionaries, where each dictionary can have the keys:

  • content (str, containing HTML)
  • display_size (str, one of “full” (whole row), “big” (half a row) or “small” (quarter of a row). May be ignored on small displays, default is “small”)
  • priority (int, used for ordering, higher comes first, default is 1)
  • url (str, optional, if the full widget should be a link)

This is a regular django signal (no pretix event signal).

Ticket designs

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

This signal is sent out to collect variables that can be used to display text in ticket-related PDF layouts. Receivers are expected to return a dictionary with globally unique identifiers as keys and more dictionaries as values that contain keys like in the following example:

1
2
3
4
5
6
7
return {
    "product": {
        "label": _("Product name"),
        "editor_sample": _("Sample product"),
        "evaluate": lambda orderposition, order, event: str(orderposition.item)
    }
}

The evaluate member will be called with the order position, order and event as arguments. The event might also be a subevent, if applicable.