django CMS Documentation

django CMS uses a split architecture for all editable entities (pages, aliases, blog posts, etc.) to handle translations and versioning efficiently. Every content object consists of two cooperating parts:

1. Grouper: Holds the long-lived identity of the object. It represents the 'noun' (e.g., this page exists at this position in the tree). It survives translations, versions, and edits. Typical fields include site, tree position, is_home, and application_urls.
2. Content: Holds the editable state for a specific combination of language × version. It represents the 'adjective' (e.g., this title, this template, this set of placeholders). There are many content rows per one grouper.

This split ensures that a page's URL and position in the tree remain stable even when editors create new translations or publish new versions.

A django CMS plugin is a reusable content publisher that can be inserted into any placeholder. It follows a pattern similar to Django's Model-View-Template (MVT) architecture:

Use a model (subclassing CMSPlugin) when your plugin needs configuration (e.g., setting a specific time range for a 'Latest Releases' box). If the plugin always performs the same action without user configuration, a model is not required.

django CMS is designed to separate the concerns of three distinct roles, allowing them to work on their own surfaces without needing to understand the internals of the others:

• Designers: Work in templates and CSS to define the layout vocabulary and drag-and-drop tools.
• Developers: Work in Django (apps, models, plugins, apphooks, and configuration). Extensibility is provided via Python APIs rather than a no-code builder.
• Editors: Work in the frontend toolbar and structure board to compose pages by adding plugins to placeholders, without editing code or templates.

In django CMS, publishing is not a core feature but a contract that versioning packages implement.

Without a versioning package:

• There is no distinction between 'draft' and 'published'.
• Editing a PageContent row immediately makes changes visible.
• There is only one PageContent row per language.
• PageContent.objects and PageContent.admin_manager return the same results.

With djangocms-versioning (the standard package):

• Multiple content rows per language are allowed (one for each draft/version).
• Content rows have states: Draft, Published, Unpublished, or Archived.
• PageContent.objects is filtered to return only the published row per language.
• PageContent.admin_manager acts as an escape hatch to return every row regardless of state.

django CMS uses a 'grouper/content' split to manage multilingualism.

• Grouper (Page, Alias): Language-agnostic. It manages identity, tree position, and apphook bindings.
• Content (PageContent, AliasContent): Per-language. Each translation is a new content row for the same grouper.

Because content is per-language, each translation has its own:

• Placeholders and plugins
• title and meta_description
• template choice
• in_navigation setting
• Slugs (managed via PageUrl rows keyed by (page, language))

The django CMS core is kept small and stable, focusing on a limited set of responsibilities:

• Managing pages and their hierarchical structure.
• Exposing placeholders for content objects to publish into.
• Coordinating plugins and apphooks to allow other Django apps to integrate.
• Integrating editing capabilities directly into rendered pages.

Advanced features like versioning, alias content, headless rendering, the rich-text editor, and the frontend admin theme are provided via separate packages.

An Application Hook (or apphook) attaches a Django application's URL tree to a django CMS page, turning that page into a mount point.

When an apphook is attached to a CMS page (e.g., /records/), the CMS page provides the base path, and the attached application provides the remainder of the URL space (e.g., /records/1984/).

Key Characteristics:

• URL Routing: Requests to the base path and everything below it are routed into the hooked application instead of being served as normal CMS page content.
• CMS Integration: Unlike adding URLs directly to urls.py, apphooks make the CMS aware of the URL space. This prevents slug conflicts, allows for menu integration, and enables the use of CMS publishing workflows.
• Publishing Requirement: An apphook only serves public traffic once the associated CMS page (and its parent pages) are published.

Apphooks have moved from the title to the page model. Key changes include:

• Single Language per Apphook: You can no longer have separate apphooks for each language.
• Namespace Requirement: If you use apphook apps with app_name for app namespaces, you must now fill out the application instance name field on the page.
• request.current_app Removal: This attribute has been removed. To retrieve the current app namespace in a view, use resolve(request.path_info).namespace.

To attach the same application to multiple CMS pages (multiple mount points), the class defining your apphook must include an app_name attribute. This attribute serves as the fallback namespace for URL reversing and provides a default value for the Application instance name field in the CMS admin.

When using reverse('myapp:index') or {% url 'myapp:index' %} in your views or templates, ensure app_name matches the namespace used in your URL reversing. If the Application instance name set in the CMS admin does not match, django CMS will fall back to the app_name defined in the class, preventing NoReverseMatch errors.

class MyApphook(CMSApp):
    name = _("My Apphook")
    app_name = "myapp"

    def get_urls(self, page=None, language=None, **kwargs):
        return ["myapp.urls"]

Since django CMS 4, you must register models for frontend editing by adding a CMSAppConfig class to your app's cms_config.py file. Set cms_enabled = True and define cms_toolbar_enabled_models, which is a list of tuples containing the model class and the view responsible for rendering it. If using Class-Based Views (CBVs), use the stub view (the endpoint view) in the tuple.

from cms.app_base import CMSAppConfig
from . import models, views


class MyAppConfig(CMSAppConfig):
    cms_enabled = True
    # For function-based views
    cms_toolbar_enabled_models = [(models.MyModel, views.render_my_model)]

    # For class-based views, use the endpoint view
    # cms_toolbar_enabled_models = [(models.MyModel, views.my_model_endpoint_view)]