Requirements

django CMS Alias requires that you have a django CMS 4 (or higher) project already running and set up.

To install

Run:

pip install djangocms-alias

Add djangocms_alias and parler to your project’s INSTALLED_APPS.

Run:

python manage.py migrate djangocms_alias

to perform the application’s database migrations.

Static aliases

Static aliases appear in templates and replace static placeholders which were part of django CMS up to version 3.x.

Example:

{% load djangocms_alias_tags %}
...
<footer>
  {% static_alias 'footer' %}
</footer>

New in version 3: Static aliases can now be edited directly on any frontend editable object (such as pages) that includes the {% static_alias %} template tag. Static aliases are marked by a pin icon in the structure board to distinguish them from regular content.

Editing static aliases on the page provides a convenient way to manage alias content in context. However, when using djangocms-versioning, there are important considerations:

Versioning Considerations:

• Independent Publishing: Static aliases must be published independently from their edit endpoint. Use the edit entry in the alias’s burger menu in the structure board to access the full alias editing interface.

• Published Content Only: When objects are viewed on the site (not in edit mode), only the latest published alias version is displayed. If no published version exists, nothing will be shown.

• Draft Creation Required: Published aliases cannot be edited - neither in the structure menu nor on their dedicated endpoint. You must create a new draft version of the alias before editing is possible.

This workflow ensures content consistency and proper version control while providing the flexibility to edit aliases in context when appropriate.

Alias plugin

Alternatively, aliases can be used with the Alias plugin. It allows to select which alias content is shown at the exact position the alias plugin is placed.

Headless API

When djangocms-rest is installed, django CMS Alias adds two endpoints below the prefix you mount djangocms_rest.urls at (/api/ in the examples here). There is no setting to switch on – the integration follows the package.

GET /api/<language>/aliases/

Lists the aliases that have content in that language on the current site.

GET /api/<language>/aliases/<pk or static code>/

Serves one alias’ placeholder content. Static aliases are addressable by their static code, the same identifier used with {% static_alias %}, e.g. /api/en/aliases/footer/.

Both accept ?preview=true to read the draft instead of the published version. That requires the Django view permission on Alias. Published alias content itself is public, as it is already embedded in public pages.

An Alias plugin placed in a page has the referenced alias’ plugin tree expanded inline in that page’s API response, so no second request is needed. An alias that references itself yields empty content rather than recursing.

Customizing the alias preview template

When editing or previewing content managed via djangocms-alias (for example, static aliases like headers or footers), django CMS renders the content inside a dedicated template.

This template may extend your project’s base.html template by default. This could cause the full page layout to be displayed while editing a small piece of content and make it difficult to focus on the alias itself.

You can override this default behaviour by supplying your own template at:

templates/djangocms_alias/base.html

For static aliases you can also provide a slot-specific preview template at:

templates/djangocms_alias/<static_code>/alias_content_preview.html

The provided template will then be used when rendering aliases in edit and preview modes. Also, it does not need to extend your main base.html template.

However, be sure that the required CMS tags and assets are included, for example:

{% load cms_tags sekizai_tags %}
<!DOCTYPE html>
<html>
    <head>
        {% render_block "css" %}
    </head>
    <body>
        {% cms_toolbar %}
        {% block content %}{% endblock %}
        {% render_block "js" %}
    </body>
</html>

This helps you keep the editing interface focused on the alias content instead of the surrounding site layout.

A note about versioning

If you enable djangocms-versioning after creating aliases, you need to run the management command manage.py create_versions --userid=<pk> to create Version objects for existing alias content. See the create_versions command documentation for more details.

For more information about djangocms-versioning, see the djangocms-versioning documentation.