mirror of
https://github.com/pretix/pretix.git
synced 2025-12-05 21:32:28 +00:00
9dc5c1b266
* Prevent transferring files from priv/ to pub/ on event clone * Also detect file names with node prefix * Only transfer files in explicitly declared file fields * Update django-hierarkey * Add note to documentation about the new behaviour
82 lines
3.4 KiB
ReStructuredText
82 lines
3.4 KiB
ReStructuredText
Settings storage
|
|
================
|
|
|
|
pretix is highly configurable and therefore needs to store a lot of per-event and per-organizer settings.
|
|
For this purpose, we use `django-hierarkey`_ which started out as part of pretix and then got refactored into
|
|
its own library. It has a comprehensive `documentation`_ which you should read if you work with settings in pretix.
|
|
|
|
The settings are stored in the database and accessed through a ``HierarkeyProxy`` instance. You can obtain
|
|
such an instance from any event or organizer model instance by just accessing ``event.settings`` or
|
|
``organizer.settings``, respectively.
|
|
|
|
Any setting consists of a key and a value. By default, all settings are strings, but the settings system
|
|
includes serializers for serializing the following types:
|
|
|
|
* Built-in types: ``int``, ``float``, ``decimal.Decimal``, ``dict``, ``list``, ``bool``
|
|
* ``datetime.date``, ``datetime.datetime``, ``datetime.time``
|
|
* ``LazyI18nString``
|
|
* References to Django ``File`` objects that are already stored in a storage backend [#f1]_
|
|
* References to model instances
|
|
|
|
In code, we recommend to always use the ``.get()`` method on the settings object to access a value, but for
|
|
convenience in templates you can also access settings values at ``settings[name]`` and ``settings.name``.
|
|
See the hierarkey `documentation`_ for more information.
|
|
|
|
To avoid naming conflicts, plugins are requested to prefix all settings they use with the name of the plugin
|
|
or something unique, e.g. ``payment_paypal_api_key``. To reduce redundant typing of this prefix, we provide
|
|
another helper class:
|
|
|
|
.. autoclass:: pretix.base.settings.SettingsSandbox
|
|
|
|
When implementing e.g. a payment or export provider, you do not event need to create this sandbox yourself,
|
|
you will just be passed a sandbox object with a prefix generated from your provider name.
|
|
|
|
Forms
|
|
-----
|
|
|
|
Hierarkey also provides a base class for forms that allow the modification of settings. pretix contains a
|
|
subclass that also adds support for internationalized fields:
|
|
|
|
.. autoclass:: pretix.base.forms.SettingsForm
|
|
|
|
You can simply use it like this:
|
|
|
|
.. code-block:: python
|
|
|
|
class EventSettingsForm(SettingsForm):
|
|
show_date_to = forms.BooleanField(
|
|
label=_("Show event end date"),
|
|
help_text=_("If disabled, only event's start date will be displayed to the public."),
|
|
required=False
|
|
)
|
|
payment_term_days = forms.IntegerField(
|
|
label=_('Payment term in days'),
|
|
help_text=_("The number of days after placing an order the user has to pay to "
|
|
"preserve his reservation."),
|
|
)
|
|
|
|
|
|
.. _settings-defaults-in-plugins:
|
|
|
|
Defaults in plugins
|
|
-------------------
|
|
|
|
Plugins can add custom hardcoded defaults in the following way:
|
|
|
|
.. code-block:: python
|
|
|
|
from pretix.base.settings import settings_hierarkey
|
|
|
|
settings_hierarkey.add_default('key', 'value', type)
|
|
|
|
Make sure that you include this code in a module that is imported at app loading time.
|
|
|
|
.. _django-hierarkey: https://github.com/raphaelm/django-hierarkey
|
|
.. _documentation: https://django-hierarkey.readthedocs.io/en/latest/
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#f1] If you store ``File`` instances in per-event settings, make sure to always register them with ``add_default``
|
|
as described above in :ref:`settings-defaults-in-plugins`. Otherwise, the file won't get copied properly if the
|
|
user copies the settings of an existing event to a new one.
|