Enhancing Django Models with Versioning Using Django CMS Versioning

Feb. 8, 2024

Tracking the evolution of content is indispensable to manage changes efficiently, roll back to prior versions when necessary, and handle drafts with ease. Here's how you can use django CMS' capabilities as a developer.

For Django-based projects, djangocms-versioning is a powerful plugin that introduces versioning capabilities to your models, providing a structured approach to managing content history. This blog post delves into integrating djangocms-versioning into your Django models, with a special focus on understanding the grouper content data model, a core concept for effective versioning.

Understanding the Grouper Content Data Model

Before diving into the setup process, it's crucial to grasp the concept of the grouper content data model. This model plays a pivotal role in how djangocms-versioning organizes and manages versions of your content.

What is a Grouper?

A grouper is essentially an object that serves as the anchor or parent for different versions of content. It groups together various versions of a content item, enabling the system to identify and manage these versions as a cohesive unit. This is particularly useful for content types that undergo frequent revisions, such as articles, blog posts, or product descriptions.

The grouper model does not store the content itself. Instead, it acts as a reference point around which different content versions revolve. Each version is tied to a specific grouper instance, facilitating the organization and retrieval of content versions based on their association with the grouper.

Why is the Grouper Important?

Organization: The grouper model simplifies content management by categorizing versions under a unified identifier. This organization is essential for maintaining clarity in content evolution, especially in complex systems with extensive content.
Efficiency: By associating content versions with a grouper, the system can efficiently query and display the relevant versions, improving both backend management and frontend rendering.
Flexibility: The grouper concept allows for flexibility in content versioning, supporting scenarios like draft management, content preview, and historical tracking without cluttering the primary content models.

What is a content model?

A content model acts as the blueprint for the content, detailing the fields and data types that constitute a piece of content, such as a blog post, product description, or any other content type. In versioning, each instance of the content model represents a specific version of the content, encapsulating all the information (text, images, metadata, etc.) that belongs to that version.

Integrating `djangocms-versioning` into Your Django Project

With a clear understanding of the grouper content data model, let's proceed to integrate versioning into your Django models step by step.

Step 1: Installation

Install djangocms-versioning via pip:

pip install djangocms-versioning

Step 2: Configuration

Add djangocms_versioning and its dependencies to INSTALLED_APPS in your project's settings.py:

INSTALLED_APPS = [ 
    ..., 
    "djangocms_versioning", 
    ...
]

Step 3: Model Versioning

To enable versioning for a model, register it with djangocms-versioning, specifying the grouper field. Registration happens using django CMS 4's new CMSAppConfig.

Create a file called cms_config.py and add:

from cms.app_base import CMSAppConfig

from .models import YourModel

class MyAppConfig(CMSAppConfig):
    djangocms_versioning_enabled = True
    versioning = [
        VersionableItem(
            content_model=YourModel,
            grouper_field_name="your_grouper_field",
        )
    ]

Step 4: Admin Integration

For most models it will be most natural to enhance the Grouper's admin class:

from cms.admin.utils import GrouperModelAdmin
from djangocms_versioning.admin import ExtendedGrouperVersionAdminMixin, StateIndicatorMixin

from .models import YourGrouperModel


@admin.register(YiourGrouperModel)
class GrouperAdmin(
    StateIndicatorMixin,
    ExtendedGrouperVersionAdminMixin,
    GrouperModelAdmin,
):
    pass

This will add versioning state indicators to the model admin (as known from django CMS own pages) including a dropdown menu with versioning actions like "publish".

Step 5: Testing and Usage

After setup, test the versioning functionality thoroughly to ensure it meets your project's needs. We've just covered the simplest example. Please also refer to the documentation.

Also, do join our Slack or Discord channels if you have further questions.

Conclusion

Integrating versioning into your Django project not only enhances content management but also introduces a structured approach to tracking and reverting changes. By understanding and implementing the grouper content data model with djangocms-versioning, you can achieve efficient and flexible version control in your applications. This setup empowers you to manage content evolution with confidence, ensuring your project can gracefully handle the complexities of content management.