From 03a56f81ca007a1dd21dc625da73cd9d8a55a174 Mon Sep 17 00:00:00 2001
From: Raphael Michel <mail@raphaelmichel.de>
Date: Tue, 26 Jul 2016 12:16:09 +0200
Subject: [PATCH] Added documentation on custom views

---
 doc/development/api/customview.rst | 107 +++++++++++++++++++++++++++++
 doc/development/api/index.rst      |   1 +
 src/pretix/control/middleware.py   |   2 +-
 3 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 doc/development/api/customview.rst

diff --git a/doc/development/api/customview.rst b/doc/development/api/customview.rst
new file mode 100644
index 000000000..f6a6b0190
--- /dev/null
+++ b/doc/development/api/customview.rst
@@ -0,0 +1,107 @@
+.. highlight:: python
+   :linenothreshold: 5
+
+Creating custom views
+=====================
+
+This page describes how to provide a custom view from within your plugin. Before you start
+reading this page, please read and understand how :ref:`URL handling <urlconf>` works in
+pretix.
+
+Control panel views
+-------------------
+
+If you want to add a custom view to the control area of an event, just register an URL in your
+``maindomain_urls.py`` that lives in the ``/control/`` subpath::
+
+    from django.conf.urls import url
+
+    from . import views
+
+    urlpatterns = [
+        url(r'^control/event/(?P<organizer>[^/]+)/(?P<event>[^/]+)/mypluginname/',
+            views.admin_view, name='backend'),
+    ]
+
+It is required that your URL paramaters are called ``organizer`` and ``event``. If you want to
+install a view on organizer level, you can leave out the ``event``.
+
+You can then implement the view as you would normally do. Our middleware will automatically
+detect the ``/control/`` subpath and will ensure the following things if this is an URL with
+both the ``event`` and ``organizer`` parameters:
+
+* The user is logged in
+* The ``request.event`` attribute contains the current event
+* The ``request.organizer`` attribute contains the event's organizer
+* The user has permission to access view the current event
+
+If only the ``organizer`` parameter is present, it will be ensured that:
+
+* The user is logged in
+* The ``request.organizer`` attribute contains the event's organizer
+* The user has permission to access view the current organizer
+
+If you want to require specific permission types, we provide you with a decorator or a mixin for
+your views::
+
+    from pretix.control.permissions import (
+        event_permission_required, EventPermissionRequiredMixin
+    )
+
+    class AdminView(EventPermissionRequiredMixin, View):
+        permission = 'can_view_orders'
+
+        ...
+
+
+    @event_permission_required('can_view_orders')
+    def admin_view(request, organizer, event):
+        ...
+
+Similarly, there is ``organizer_permission_required`` and ``OrganizerPermissionRequiredMixin``.
+
+Frontend views
+--------------
+
+Including a custom view into the participant-facing frontend is a little bit different as there is
+no path prefix like ``control/``.
+
+First, define your URL in your ``maindomain_urls.py``::
+
+    from django.conf.urls import url
+
+    from . import views
+
+    urlpatterns = [
+        url(r'^(?P<organizer>[^/]+)/(?P<event>[^/]+)/mypluginname/',
+            views.frontend_view, name='frontend'),
+    ]
+
+And for the case of custom domains in your ``subdomain_urls.py``::
+
+    from django.conf.urls import url
+
+    from . import views
+
+    urlpatterns = [
+        url(r'^(?P<event>[^/]+)/mypluginname/',
+            views.frontend_view, name='frontend'),
+    ]
+
+You can then implement a view as you would normally do, but you need to apply a decorator to your
+view if you want pretix's default behavior::
+
+    from pretix.presale.utils import event_view
+
+    @event_view
+    def event_view(request, *args, **kwargs):
+        ...
+
+This decorator will check the URL arguments for their ``event`` and ``organizer`` parameters and
+correctly ensure that:
+
+* The requested event exists and is activated
+* The event is accessed via the domain it should be accessed
+* The ``request.event`` attribute contains the correct ``Event`` object
+* The ``request.organizer`` attribute contains the correct ``Organizer`` object
+* The locale is set correctly
\ No newline at end of file
diff --git a/doc/development/api/index.rst b/doc/development/api/index.rst
index ee28f3676..eb2a08782 100644
--- a/doc/development/api/index.rst
+++ b/doc/development/api/index.rst
@@ -10,4 +10,5 @@ Contents:
    payment
    ticketoutput
    exporter
+   customview
    general
diff --git a/src/pretix/control/middleware.py b/src/pretix/control/middleware.py
index 593f69c04..d9f53a747 100644
--- a/src/pretix/control/middleware.py
+++ b/src/pretix/control/middleware.py
@@ -32,7 +32,7 @@ class PermissionMiddleware:
             # This middleware should only touch the /control subpath
             return
         if hasattr(request, 'domain'):
-            # If the user is on a organizer's subdomain, he sould be redirected to pretix
+            # If the user is on a organizer's subdomain, he should be redirected to pretix
             return redirect(urljoin(settings.SITE_URL, request.get_full_path()))
         if url_name in self.EXCEPTIONS:
             return