Update docs

Author: fsbraun

docs/api/advanced_configuration.rst

@@ -1,3 +1,5 @@
+.. _advanced_configuration:
+
 Advanced configuration
 ======================
 

docs/explanations/admin_architecture.rst

@@ -0,0 +1,190 @@
+.. _alternative_admin:
+
+The Admin with Versioning
+=========================
+
+Versioning in django CMS provides powerful tools to manage content and grouper models in the admin interface.
+This chapter explains the default patterns and customization options for integrating versioning into your admin
+classes.
+
+Proxy models of :class:`djangocms_versioning.models.Version` are generated for each registered content model,
+allowing customization of the version table by model.
+
+
+Default Pattern
+---------------
+
+The default pattern is to set the ``grouper_admin_mixin`` property to ``"__default__"``, which applies the
+:class:`~djangocms_versioning.admin.DefaultGrouperVersioningAdminMixin` to the grouper model admin. This mixin
+ensures that state indicators and admin list actions are displayed consistently.
+
+Admin Options Overview
+-----------------------
+
+.. list-table:: Overview on versioning admin options: Grouper models
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Versioning state
+     - Grouper Model Admin
+   * - **Default**: Indicators, drop down menu
+     - .. code-block:: python
+
+            class GrouperAdmin(
+                DefaultGrouperVersioningAdminMixin,
+                GrouperModelAdmin
+            ):
+                list_display = ...
+   * - Indicators, drop down menu (fix the current default)
+     - .. code-block:: python
+
+            class GrouperAdmin(
+                ExtendedGrouperVersionAdminMixin,
+                StateIndicatorMixin,
+                GrouperModelAdmin
+            ):
+                list_display = ...
+   * - Text, no interaction
+     - .. code-block:: python
+
+            class GrouperAdmin(
+                ExtendedGrouperVersionAdminMixin,
+                GrouperModelAdmin
+            ):
+                list_display = ...
+
+.. list-table:: Overview on versioning admin options: Content models
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Versioning state
+     - **Content Model Admin**
+   * - Text, no interaction
+     - .. code-block:: python
+
+            class ContentAdmin(
+                ExtendedVersionAdminMixin,
+                admin.ModelAdmin
+            )
+   * - Indicators, drop down menu
+     - .. code-block:: python
+
+            class ContentAdmin(
+                ExtendedIndicatorVersionAdminMixin,
+                admin.ModelAdmin,
+            )
+
+Adding Versioning to Content Model Admins
+-----------------------------------------
+
+The :term:`ExtendedVersionAdminMixin` provides fields and actions related to versioning, such as:
+
+* Author
+* Modified date
+* Versioning state
+* Preview action
+* Edit action
+* Version list action
+
+Example:
+
+.. code-block:: python
+
+    class PostContentAdmin(ExtendedVersionAdminMixin, admin.ModelAdmin):
+        list_display = ["title"]
+
+The :term:`ExtendedVersionAdminMixin` also has functionality to alter fields from other apps. By adding the :term:`admin_field_modifiers` to a given apps :term:`cms_config`,
+in the form of a dictionary of {model_name: {field: method}}, the admin for the model, will alter the field, using the method provided.
+
+.. code-block:: python
+
+    # cms_config.py
+    def post_modifier(obj, field):
+        return obj.get(field) + " extra field text!"
+
+    class PostCMSConfig(CMSAppConfig):
+        # Other versioning configurations...
+        admin_field_modifiers = [
+            {PostContent: {"title": post_modifier}},
+        ]
+
+Given the code sample above, "This is how we add" would be displayed as
+"this is how we add extra field text!" in the changelist of PostAdmin.
+
+Adding State Indicators
+-------------------------
+
+djangocms-versioning provides status indicators for django CMS' content models, you may know them from the page tree in django-cms:
+
+.. image:: static/Status-indicators.png
+    :width: 50%
+
+You can use these on your content model's changelist view admin by adding the following fixin to the model's Admin class:
+
+.. code-block:: python
+
+    class MyContentModelAdmin(StateIndicatorMixin, admin.ModelAdmin):
+        list_display = [..., "state_indicator", ...]
+
+.. note::
+
+    For grouper models, ensure that the admin instance defines properties for each extra grouping field (e.g., ``self.language``).
+    If you derive your admin class from :class:`~cms.admin.utils.GrouperModelAdmin`, this behavior is automatically handled.
+
+    Otherwise, this is typically set in the ``get_changelist_instance`` method, e.g., by getting the language from the request. The page
+    tree, for example, keeps its extra grouping field (language) as a get parameter to avoid mixing language of the user interface and
+    language that is changed.
+
+    .. code-block:: python
+
+        def get_changelist_instance(self, request):
+            """Set language property and remove language from changelist_filter_params"""
+            if request.method == "GET":
+                request.GET = request.GET.copy()
+                for field in versionables.for_grouper(self.model).extra_grouping_fields:
+                    value = request.GET.pop(field, [None])[0]
+                    # Validation is recommended: Add clean_language etc. to your Admin class!
+                    if hasattr(self, f"clean_{field}"):
+                        value = getattr(self, f"clean_{field}")(value):
+                    setattr(self, field) = value
+                # Grouping field-specific cache needs to be cleared when they are changed
+                self._content_cache = {}
+            instance = super().get_changelist_instance(request)
+            # Remove grouping fields from filters
+            if request.method == "GET":
+                for field in versionables.for_grouper(self.model).extra_grouping_fields:
+                    if field in instance.params:
+                        del instance.params[field]
+            return instance
+
+
+Combining Status Indicators and Versioning
+------------------------------------------
+
+To combine both status indicators and versioning fields, use the :class:`~djangocms_versioning.admin.ExtendedIndicatorVersionAdminMixin`:
+
+.. code-block:: python
+
+    class MyContentModelAdmin(ExtendedIndicatorVersionAdminMixin, admin.ModelAdmin):
+        ...
+
+The versioning state and version list action are replaced by the status indicator and its context menu, respectively.
+
+Add additional actions by overwriting the ``self.get_list_actions()`` method and calling ``super()``.
+
+Adding Versioning to Grouper Model Admins
+-----------------------------------------
+
+For grouper models, use the :class:`~djangocms_versioning.admin.ExtendedGrouperVersionAdminMixin` to add versioning fields:
+
+.. code-block:: python
+
+    class PostAdmin(ExtendedGrouperVersionAdminMixin, GrouperModelAdmin):
+        list_display = ["title", "get_author", "get_modified_date", "get_versioning_state"]
+
+To also add state indicators, include the :class:`~djangocms_versioning.admin.StateIndicatorMixin`:
+
+.. code-block:: python
+
+    class PostAdmin(ExtendedGrouperVersionAdminMixin, StateIndicatorMixin, GrouperModelAdmin):
+        list_display = ["title", "get_author", "get_modified_date", "state_indicator"]

docs/explanations/admin_options.rst

@@ -28,7 +28,7 @@ Welcome to "djangocms-versioning"'s documentation!
    :maxdepth: 2
    :caption: Explanation:
 
-   explanations/admin_architecture
+   explanations/admin_options
    explanations/customizing_version_list
 
 .. toctree::