feat: custom views (#468)

Author: lukasvinclav

README.md

@@ -57,6 +57,7 @@ Did you decide to start using Unfold but you don't have time to make the switch
   - [Dropdown filters](#dropdown-filters)
   - [Numeric filters](#numeric-filters)
   - [Date/time filters](#datetime-filters)
+- [Custom admin pages](#custom-admin-pages)
 - [Nonrelated inlines](#nonrelated-inlines)
 - [Display decorator](#display-decorator)
 - [Change form tabs](#change-form-tabs)
@@ -621,6 +622,45 @@ class YourModelAdmin(ModelAdmin):
     )
 ```
 
+## Custom admin pages
+
+By default, Unfold provides a basic view mixin which helps with creation of basic views which are part of Unfold UI. The implementation requires creation of class based view inheriting from `unfold.views.UnfoldModelAdminViewMixin`. It is important to add `title` and `permissions_required` properties.
+
+```python
+# admin.py
+
+from django.views.generic import TemplateView
+from unfold.admin import ModelAdmin
+from unfold.views import UnfoldModelAdminViewMixin
+
+
+class MyClassBasedView(UnfoldModelAdminViewMixin, TemplateView):
+    title = "Custom Title"  # required: custom page header title
+    permissions_required = () # required: tuple of permissions
+    template_name = "some/template/path.html"
+
+
+class CustomAdmin(ModelAdmin):
+    def get_urls(self):
+        return super().get_urls() + [
+            path(
+                "custom-url-path",
+                MyClassBasedView.as_view(model_admin=self),  # IMPORTANT: model_admin is required
+                name="custom_name"
+            ),
+        ]
+```
+
+The template is straightforward, extend from `unfold/layouts/base.html` and the UI will display all Unfold components like header or sidebar with all menu items. Then all content needs to be located in `content` block.
+
+```django-html
+{% extends "unfold/layouts/base.html" %}
+
+{% block content %}
+    Content here
+{% endblock %}
+```
+
 ## Nonrelated inlines
 
 To display inlines which are not related (no foreign key pointing at the main model) to the model instance in changeform, you can use nonrelated inlines which are included in `unfold.contrib.inlines` module. Make sure this module is included in `INSTALLED_APPS` in settings.py.

src/unfold/templates/unfold/layouts/base.html

@@ -0,0 +1,11 @@
+{% extends "unfold/layouts/base_simple.html" %}
+
+{% block branding %}
+    <h1 id="site-name">
+        <a href="{% url 'admin:index' %}">
+            {{ site_header|default:_('Django administration') }}
+        </a>
+    </h1>
+{% endblock %}
+
+{% block title %}{% if subtitle %}{{ subtitle }} | {% endif %}{{ title }} | {{ site_title|default:_('Django site admin') }}{% endblock %}

src/unfold/views.py

@@ -10,13 +10,25 @@ class UnfoldModelAdminViewMixin(PermissionRequiredMixin):
     Prepares views to be displayed in admin
     """
 
-    def get_context_data(self, **kwargs) -> Dict[str, Any]:
-        if "model_admin" not in self.kwargs:
+    model_admin = None
+
+    def __init__(self, model_admin, **kwargs):
+        self.model_admin = model_admin
+        super().__init__(**kwargs)
+
+    def get_context_data(self, **kwargs: Any) -> Dict[str, Any]:
+        if not hasattr(self, "model_admin"):
             raise UnfoldException(
                 "UnfoldModelAdminViewMixin was not provided with 'model_admin' argument"
             )
-        model_admin = self.kwargs["model_admin"]
-        context_data = super().get_context_data(
-            **kwargs, **model_admin.admin_site.each_context(self.request)
+
+        if not hasattr(self, "title"):
+            raise UnfoldException(
+                "UnfoldModelAdminViewMixin was not provided with 'title' attribute"
+            )
+
+        return super().get_context_data(
+            **kwargs,
+            **self.model_admin.admin_site.each_context(self.request),
+            **{"title": self.title},
         )
-        return context_data