Installation and Example

Install djangocms-custom-content and create your first editable, versionable content model.

By the end you’ll have a working Article model that is editable in the django CMS frontend, versioned per language, and manageable in the admin — written in about a dozen lines.

Prerequisites

  • Django project with django CMS installed

  • About 5 minutes

Step 1: Install the Package

Install djangocms-custom-content:

pip install djangocms-custom-content

Step 2: Add to INSTALLED_APPS

Add to your Django settings:

INSTALLED_APPS = [
    # ...
    "djangocms_custom_content",
]

Then run migrations:

python manage.py migrate djangocms_custom_content

Step 3: Create a Django App

Create an app for your content:

python manage.py startapp my_content

Add it to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "djangocms_custom_content",
    "my_content",
]

Step 4: Create a Content Model

Create my_content/models.py:

from django.db import models
from djangocms_custom_content.models import (
    AbstractCustomGrouper,
    AbstractCustomContent,
)

class Article(AbstractCustomGrouper):
    """Groups all language versions of an article."""
    pass

class ArticleContent(AbstractCustomContent):
    """The editable article content."""
    article = models.ForeignKey(Article, on_delete=models.CASCADE)
    title = models.CharField(max_length=200)
    slug = models.SlugField()
    body = models.TextField()

    class CMSConfig:
        # Make editable in the frontend and versionable
        enable_frontend_editing = True
        enable_versioning = True

    def __str__(self):
        return self.title

The CMSConfig class enables:

  • enable_frontend_editing = True - Content can be edited on the frontend in django CMS

  • enable_versioning = True - Track and manage multiple versions by language

Step 5: Register with Admin

Register the grouper with django CMS’s GrouperModelAdmin and CustomGrouperAdminMixin. Content is edited through this admin, so you do not register ArticleContent yourself. Reach content fields with the content__ prefix.

Create my_content/admin.py:

from cms.admin.placeholderadmin import FrontendEditableAdminMixin
from cms.admin.utils import GrouperModelAdmin
from django.contrib import admin

from djangocms_custom_content.admin import CustomGrouperAdminMixin
from .models import Article

@admin.register(Article)
class ArticleAdmin(CustomGrouperAdminMixin, FrontendEditableAdminMixin, GrouperModelAdmin):
    grouper_field_name = "article"   # the FK on ArticleContent

    list_display = ("content__title", "content__slug")
    search_fields = ("content__title", "content__body")
    prepopulated_fields = {"content__slug": ("content__title",)}

See Register the grouper admin for the full explanation of this pattern.

Step 6: Run Migrations

python manage.py makemigrations my_content
python manage.py migrate

Done!

Your content model is now:

✅ Installed and configured ✅ Editable in the django CMS frontend ✅ Versionable by language ✅ Available in Django admin

Next Steps: