.. _advanced_configuration:

Advanced configuration
======================

For the most important configuration options see :doc:`versioning_integration`. Below are additional configuration options built into versioning.


Overriding how versioning handles core cms models
-------------------------------------------------
By default django-cms models will be registered with versioning automatically. If you do not
want that to happen set ``VERSIONING_CMS_MODELS_ENABLED`` in `settings.py` to False.
You could also set that setting to False and register the django-cms models yourself
with different options.


Adding to the context of versioning admin views
------------------------------------------------

Currently versioning supports adding context variables to the unpublish confirmation
view. Wider support for adding context variables is planned, but at the moment only
the unpublish confirmation view is supported. This is how one would configure this
in ```cms_config.py```:

.. code-block:: python

    # blog/cms_config.py
    from collections import OrderedDict
    from cms.app_base import CMSAppConfig


    def stories_about_intelligent_cats(request, version, *args, **kwargs):
        return version.content.cat_stories


     class SomeConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning_add_to_confirmation_context = {
            'unpublish': OrderedDict([('cat_stories', stories_about_intelligent_cats)]),
        }


Any context variable added to this setting will be displayed on the unpublish confirmation
page automatically, but if you wish to change where on the page it displays, you will
need to override the `djangocms_versioning/admin/unpublish_confirmation.html` template.


Additional options on the VersionableItem class
-------------------------------------------------
The three mandatory attributes of :class:`~djangocms_versioning.datastructures.VersionableItem`
are described in detail on the :doc:`versioning_integration` page. Below are additional
options you might want to set.


.. _preview_url:

preview_url
+++++++++++
This will define the url that will be used for each version on the version list table.

.. code-block:: python

    # some_app/cms_config.py
    from django.urls import reverse
    from cms.app_base import CMSAppConfig
    from djangocms_versioning.datastructures import VersionableItem


    def get_preview_url(obj):
        return reverse('some_interesting_url', args=(obj.pk,))


     class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning = [
            VersionableItem(
                ....,
                preview_url=get_preview_url,
            ),
        ]


.. _extra_grouping_fields:

extra_grouping_fields
++++++++++++++++++++++
Defines one or more :term:`extra grouping fields <extra grouping field>`. This will add a
UI filter to the version list table enabling filtering by that field.

.. code-block:: python

    # some_app/cms_config.py
    from django.urls import reverse
    from cms.app_base import CMSAppConfig
    from djangocms_versioning.datastructures import VersionableItem


     class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning = [
            VersionableItem(
                ....,
                extra_grouping_fields=["language"],
            ),
        ]

.. _version_list_filter_lookups:

version_list_filter_lookups
++++++++++++++++++++++++++++
Must be defined if the :ref:`extra_grouping_fields` option has been set. This will let the
UI filter know what values it should allow filtering by.

.. code-block:: python

    # some_app/cms_config.py
    from django.urls import reverse
    from cms.app_base import CMSAppConfig
    from cms.utils.i18n import get_language_tuple
    from djangocms_versioning.datastructures import VersionableItem


     class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning = [
            VersionableItem(
                ....,
                version_list_filter_lookups={"language": get_language_tuple},
            ),
        ]

grouper_selector_option_label
++++++++++++++++++++++++++++++

If the version table link is specified without a grouper param, a form with a dropdown
of grouper objects will display. By default, if the grouper object is registered with the
admin and has a ``search_fields`` attribute, the dropdown will be an autocomplete
field which will display the object's ``__str__`` method. This is the recommended
method.

For models not registerd with the admin, or without search fields, this setting defines
how the labels of those groupers will display on the dropdown (regular select field).


.. code-block:: python

    # some_app/cms_config.py
    from django.urls import reverse
    from cms.app_base import CMSAppConfig
    from djangocms_versioning.datastructures import VersionableItem


    def grouper_label(obj, language):
        return "{title} ({language})".format(title=obj.title, language=language)


     class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning = [
            VersionableItem(
                ....,
                grouper_selector_option_label=grouper_label,
            ),
        ]

content_admin_mixin
++++++++++++++++++++
Versioning modifies how the admin of the :term:`content model <content model>` works with
:class:`~djangocms-versioning.admin.VersioningAdminMixin`. But you can modify this mixin with this setting.

.. code-block:: python

    # some_app/cms_config.py
    from django.urls import reverse
    from cms.app_base import CMSAppConfig
    from djangocms_versioning.datastructures import VersionableItem


    class SomeContentAdminMixin(VersioningAdminMixin):
        # override any standard django ModelAdmin attributes and methods
        # in this class

        def has_add_permission(self, request):
            return False


     class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning = [
            VersionableItem(
                ....,
                content_admin_mixin=SomeContentAdminMixin,
            ),
        ]

grouper_admin_mixin
++++++++++++++++++++
This option allows you to customize the admin interface for the
:term:`grouper model <grouper model>` by providing a custom ModelAdmin mixin.
By default, versioning uses the standard admin, but you can override or extend
its behavior using this setting.

To use, define your mixin class and set it on the `VersionableItem`:

.. code-block:: python

    # some_app/cms_config.py
    from cms.app_base import CMSAppConfig
    from djangocms_versioning.datastructures import VersionableItem

    class CustomGrouperAdminMixin:
        # Override ModelAdmin methods or attributes as needed
        def has_delete_permission(self, request, obj=None):
            return False

    class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        versioning = [
            VersionableItem(
                ....,
                grouper_admin_mixin=CustomGrouperAdminMixin,
            ),
        ]

This mixin will be applied to the admin for the grouper model registered by
versioning, allowing you to customize permissions, list display, or any other
admin behavior.

Selecting the string ``"__default__"`` will use the
:class:`~djangocms_versioning.admin.DefaultGrouperVersioningAdminMixin`
which combines the functionality of the
:class:`~djangocms_versioning.admin.StateIndicatorMixin` and the
:class:`~djangocms_versioning.admin.ExtendedGrouperVersionAdminMixin`.

extended_admin_field_modifiers
++++++++++++++++++++++++++++++
These allow for the alteration of how a field is displayed, by providing a method,
when the admin menu containing it uses the ExtendedVersionAdminMixin.

This can be provided as a dictionary of {model: {field: method}}.

model - the model which is registered with an admin that inherits ExtendedVersionAdminMixin
field - field to be modified
method - the method used to modify the field

.. code-block:: python

    # some_app/cms_config.py
    from cms.app_base import CMSAppConfig

    from .models import SomeModel

    def transform_text_field(obj, field):
        return obj.field + " Extra Value!"

     class SomeCMSConfig(CMSAppConfig):
        djangocms_versioning_enabled = True
        ...
        extended_admin_field_modifiers = {SomeModel: {"text": transform_text_field}}