Added voucher_redeem_info signal and improved signal documentation

src/pretix/base/signals.py

@@ -47,55 +47,70 @@ class EventPluginSignal(django.dispatch.Signal):
                     responses.append((receiver, response))
         return responses
 
-"""
-This signal is sent out to get all known payment providers. Receivers should return a
-subclass of pretix.base.payment.BasePaymentProvider
-"""
 register_payment_providers = EventPluginSignal(
     providing_args=[]
 )
+"""
+This signal is sent out to get all known payment providers. Receivers should return a
+subclass of pretix.base.payment.BasePaymentProvider
 
+As with all event-plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out to get all known ticket outputs. Receivers should return a
-subclass of pretix.base.ticketoutput.BaseTicketOutput
-"""
+
 register_ticket_outputs = EventPluginSignal(
     providing_args=[]
 )
+"""
+This signal is sent out to get all known ticket outputs. Receivers should return a
+subclass of pretix.base.ticketoutput.BaseTicketOutput
 
+As with all event-plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out to get all known data exporters. Receivers should return a
-subclass of pretix.base.exporter.BaseExporter
-"""
+
 register_data_exporters = EventPluginSignal(
     providing_args=[]
 )
+"""
+This signal is sent out to get all known data exporters. Receivers should return a
+subclass of pretix.base.exporter.BaseExporter
 
+As with all event-plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out every time an order is placed. The order object is given
-as the first argument.
-"""
+
 order_placed = EventPluginSignal(
     providing_args=["order"]
 )
-
 """
-This signal is sent out every time an order is paid. The order object is given
+This signal is sent out every time an order is placed. The order object is given
 as the first argument.
+
+As with all event-plugin signals, the ``sender`` keyword argument will contain the event.
 """
+
 order_paid = EventPluginSignal(
     providing_args=["order"]
 )
+"""
+This signal is sent out every time an order is paid. The order object is given
+as the first argument.
 
+As with all event-plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out every time we need to display a LogEntry object and we
-don't know how to turn it into human-readable text.
-"""
+
 logentry_display = EventPluginSignal(
     providing_args=["logentry"]
 )
+"""
+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.
 
+As with all event-plugin signals, the ``sender`` keyword argument will contain the event.
+"""
+
+periodic_task = django.dispatch.Signal()
 """
 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
@@ -103,4 +118,3 @@ 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 send out more often
 than expected.
 """
-periodic_task = django.dispatch.Signal()

src/pretix/base/templatetags/eventsignal.py

@@ -0,0 +1,25 @@
+import importlib
+
+from django import template
+
+from pretix.base.models import Event
+
+register = template.Library()
+
+
+@register.simple_tag
+def eventsignal(event: Event, signame: str, **kwargs):
+    """
+    Send a signal and return the concatenated return values of all responses.
+
+    Usage::
+
+        {% eventsignal event "path.to.signal" argument="value" ... %}
+    """
+    sigstr = signame.rsplit('.', 1)
+    sigmod = importlib.import_module(sigstr[0])
+    signal = getattr(sigmod, sigstr[1])
+    _html = []
+    for receiver, response in signal.send(event, **kwargs):
+        _html.append(response)
+    return "".join(_html)

src/pretix/control/signals.py

@@ -2,50 +2,74 @@ from django.dispatch import Signal
 
 from pretix.base.signals import EventPluginSignal
 
-"""
-This signal is sent out to build configuration forms for all restriction formsets
-(see plugin API documentation for details).
-"""
 restriction_formset = EventPluginSignal(
     providing_args=["item"]
 )
+"""
+This signal is sent out to build configuration forms for all restriction formsets
+(see plugin API documentation for details).
 
+As with all plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out to include code into the HTML <head> tag
-"""
+
 html_head = EventPluginSignal(
     providing_args=["request"]
 )
+"""
+This signal allows you to put code inside the HTML ``<head>`` tag
+of every page in the backend. You will get the request as a keyword argument
+``request`` and can return plain HTML.
 
+As with all plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out to include navigation items in the event admin
-"""
+
 nav_event = EventPluginSignal(
     providing_args=["request"]
 )
+"""
+This signal allows you to add additional views to the admin panel
+navigation. You will get the request as a keyword argument ``return``.
+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 :ref:`how to deal with URLs <urlconf>`
+in pretix.
+
+As with all plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out to include widgets to the event dashboard. Receivers
-should return a list of dictionaries, where each dictionary can have the keys:
-* content (str, containing HTML)
-* minimal width (int, widget width in 1/12ths of the page, default ist 3, can be
-  ignored on small displays)
-* priority (int, used for ordering, higher comes first, default is 1)
-* link (str, optional, if the full widget should be a link)
-"""
+
 event_dashboard_widgets = EventPluginSignal(
     providing_args=[]
 )
-
 """
-This signal is sent out to include widgets to the personal user dashboard. Receivers
+This signal is sent out to include widgets to the event dashboard. Receivers
 should return a list of dictionaries, where each dictionary can have the keys:
+
 * content (str, containing HTML)
 * minimal width (int, widget width in 1/12ths of the page, default ist 3, can be
   ignored on small displays)
 * priority (int, used for ordering, higher comes first, default is 1)
 * link (str, optional, if the full widget should be a link)
+
+As with all plugin signals, the ``sender`` keyword argument will contain the event.
 """
+
 user_dashboard_widgets = Signal(
     providing_args=['user']
 )
+"""
+This signal is sent out to include widgets to the personal user dashboard. Receivers
+should return a list of dictionaries, where each dictionary can have the keys:
+
+* content (str, containing HTML)
+* minimal width (int, widget width in 1/12ths of the page, default ist 3, can be
+  ignored on small displays)
+* priority (int, used for ordering, higher comes first, default is 1)
+* link (str, optional, if the full widget should be a link)
+
+This is a regular django signal (no pretix event signal).
+"""

src/pretix/presale/signals.py

@@ -1,20 +1,38 @@
 from pretix.base.signals import EventPluginSignal
 
-"""
-This signal is sent out to include code into the HTML <head> tag
-"""
 html_head = EventPluginSignal(
     providing_args=["request"]
 )
+"""
+This signal allows you to put code inside the HTML ``<head>`` tag
+of every page in the frontend. You will get the request as a keyword argument
+``request`` and can return plain HTML.
 
+As with all plugin signals, the ``sender`` keyword argument will contain the event.
 """
-This signal is sent out to include links in the footer
-"""
+
 footer_link = EventPluginSignal(
     providing_args=["request"]
 )
+"""
+The signal ``pretix.presale.signals.footer_links`` 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.
+"""
+
+checkout_flow_steps = EventPluginSignal()
 """
 This signal is sent out to retrieve pages for the checkout flow
+
+As with all plugin signals, the ``sender`` keyword argument will contain the event.
+"""
+
+voucher_redeem_info = EventPluginSignal(
+    providing_args=["voucher"]
+)
+"""
+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.
 """
-checkout_flow_steps = EventPluginSignal()

src/pretix/presale/templates/pretixpresale/event/voucher.html

@@ -1,6 +1,7 @@
 {% extends "pretixpresale/event/base.html" %}
 {% load i18n %}
 {% load eventurl %}
+{% load eventsignal %}
 {% load thumbnail %}
 {% block title %}{% trans "Voucher redemption" %}{% endblock %}
 
@@ -139,6 +140,7 @@
                     {% endfor %}
                 </section>
             {% endfor %}
+            {% eventsignal event "pretix.presale.signals.voucher_redeem_info" voucher=voucher %}
             {% if event.presale_is_running %}
                 <div class="row-fluid checkout-button-row">
                     <div class="col-md-4 col-md-offset-8 col-xs-12">