Update plugin docs

This commit is contained in:
Raphael Michel
2015-02-14 18:00:10 +01:00
parent 1a7b9d0744
commit 93aeda0bdb
2 changed files with 16 additions and 32 deletions
+4 -20
View File
@@ -23,23 +23,7 @@ on the next pages.
Creating a plugin Creating a plugin
----------------- -----------------
To create a new plugin, create a new python package as a subpackage to ``pretixplugins``. To create a new plugin, create a new python package.
In order to do so, you can place your module into pretix's :file:`pretixplugins` folder *or
anywhere else in your python import path* inside a folder called ``pretixplugins``.
.. IMPORTANT::
This makes use of a design pattern called `namespace packages`_ which is only
implicitly available as of Python 3.4. As we aim to support Python 3.2 for a bit
longer, you **MUST** put **EXACLTY** the following content into ``pretixplugins/__init__.py``
if you create a new ``pretixplugins`` folder somewhere in your path::
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
Otherwise it **will break** on Python 3.2 systems *depending on the python path's order*,
which is not tolerable behaviour. Also, even on Python 3.4 the test runner seems to have
problems without this workaround.
Inside your newly created folder, you'll probably need the three python modules ``__init__.py``, Inside your newly created folder, you'll probably need the three python modules ``__init__.py``,
``models.py`` and ``signals.py``, although this is up to you. You can take the following ``models.py`` and ``signals.py``, although this is up to you. You can take the following
@@ -48,11 +32,11 @@ example, taken from the time restriction module (see next chapter) as a template
from django.apps import AppConfig from django.apps import AppConfig
from django.utils.translation import ugettext_lazy as _ from django.utils.translation import ugettext_lazy as _
from pretixbase.plugins import PluginType from pretix.base.plugins import PluginType
class TimeRestrictionApp(AppConfig): class TimeRestrictionApp(AppConfig):
name = 'pretixplugins.timerestriction' name = 'pretix.plugins.timerestriction'
verbose_name = _("Time restriction") verbose_name = _("Time restriction")
class PretixPluginMeta: class PretixPluginMeta:
@@ -67,7 +51,7 @@ example, taken from the time restriction module (see next chapter) as a template
def ready(self): def ready(self):
from . import signals # NOQA from . import signals # NOQA
default_app_config = 'pretixplugins.timerestriction.TimeRestrictionApp' default_app_config = 'pretix.plugins.timerestriction.TimeRestrictionApp'
.. IMPORTANT:: .. IMPORTANT::
You have to implement a ``PretixPluginMeta`` class like in the example to make your You have to implement a ``PretixPluginMeta`` class like in the example to make your
+12 -12
View File
@@ -15,14 +15,14 @@ The restriction model
It is very likely that your new restriction plugin needs to store data. In order to do It is very likely that your new restriction plugin needs to store data. In order to do
so, it should define its own model with a name related to what your restriction does, so, it should define its own model with a name related to what your restriction does,
e.g. ``TimeRestriction``. This model should be a child class of ``pretixbase.models.BaseRestriction``. e.g. ``TimeRestriction``. This model should be a child class of ``pretix.base.models.BaseRestriction``.
You do not need to define custom fields, but you should create at least an empty model. You do not need to define custom fields, but you should create at least an empty model.
In our example, we put the following into :file:`pretixplugins/timerestriction/models.py`:: In our example, we put the following into :file:`pretix/plugins/timerestriction/models.py`::
from django.db import models from django.db import models
from django.utils.translation import ugettext_lazy as _ from django.utils.translation import ugettext_lazy as _
from pretixbase.models import BaseRestriction from pretix.base.models import BaseRestriction
class TimeRestriction(BaseRestriction): class TimeRestriction(BaseRestriction):
@@ -52,14 +52,14 @@ Availability determination
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
This is the one signal *every* restriction plugin has to listen for, as your plugin does not This is the one signal *every* restriction plugin has to listen for, as your plugin does not
restrict anything without doing so. It is available as ``pretixbase.signals.determine_availability`` restrict anything without doing so. It is available as ``pretix.base.signals.determine_availability``
and is sent out every time some component of pretix wants to know whether a specific item or and is sent out every time some component of pretix wants to know whether a specific item or
variation is available for sell. variation is available for sell.
It is sent out with several keyword arguments: It is sent out with several keyword arguments:
``item`` ``item``
The instance of ``pretixbase.models.Item`` in question. The instance of ``pretix.base.models.Item`` in question.
``variations`` ``variations``
A list of dictionaries in the same format as ``Item.get_all_variations``: A list of dictionaries in the same format as ``Item.get_all_variations``:
The list contains one dictionary per variation, where the ``Property`` IDs are The list contains one dictionary per variation, where the ``Property`` IDs are
@@ -68,7 +68,7 @@ It is sent out with several keyword arguments:
the item does not have any properties, the list will contain exactly one empty the item does not have any properties, the list will contain exactly one empty
dictionary. Please note: this is *not* the list of all possible variations, this is dictionary. Please note: this is *not* the list of all possible variations, this is
only the list of all variations the frontend likes to determine the status for. only the list of all variations the frontend likes to determine the status for.
Technically, you won't get ``dict`` objects but ``pretixbase.types.VariationDict`` Technically, you won't get ``dict`` objects but ``pretix.base.types.VariationDict``
objects, which behave exactly the same but add some extra methods. objects, which behave exactly the same but add some extra methods.
``context`` ``context``
A yet-to-be-defined context object containing information about the user and the order A yet-to-be-defined context object containing information about the user and the order
@@ -103,7 +103,7 @@ In our example, the implementation could look like this::
from django.dispatch import receiver from django.dispatch import receiver
from django.utils.timezone import now from django.utils.timezone import now
from pretixbase.signals import determine_availability from pretix.base.signals import determine_availability
from .models import TimeRestriction from .models import TimeRestriction
@@ -217,12 +217,12 @@ Control interface formsets
To make it possible for the event organizer to configure your restriction, there is a To make it possible for the event organizer to configure your restriction, there is a
'Restrictions' page in the item configuration. This page is able to show a formset for 'Restrictions' page in the item configuration. This page is able to show a formset for
each restriction plugin, but *you* are required to create this formset. This is why you each restriction plugin, but *you* are required to create this formset. This is why you
should listen to the the ``pretixcontrol.signals.restriction_formset`` signal. should listen to the the ``pretix.control.signals.restriction_formset`` signal.
Currently, the signal comes with only one keyword argument: Currently, the signal comes with only one keyword argument:
``item`` ``item``
The instance of ``pretixbase.models.Item`` we want a formset for. The instance of ``pretix.base.models.Item`` we want a formset for.
You are expected to return a dict containing the following items: You are expected to return a dict containing the following items:
@@ -245,9 +245,9 @@ Our time restriction example looks like this::
from django.dispatch import receiver from django.dispatch import receiver
from django.forms.models import inlineformset_factory from django.forms.models import inlineformset_factory
from pretixcontrol.signals import restriction_formset from pretix.control.signals import restriction_formset
from pretixbase.models import Item from pretix.base.models import Item
from pretixcontrol.views.forms import ( from pretix.control.views.forms import (
VariationsField, RestrictionInlineFormset, RestrictionForm VariationsField, RestrictionInlineFormset, RestrictionForm
) )