fix: Draft static aliases disappeared when viewing pages on site (#297)

* fix: Draft static aliases disappeard when viewing pages on site

* Bump version

* Update readme

* docs: Improve test docstring

* fix: improve error message of migration

* fix: Show alias name if not static code is available in migration error message

* Update tests

* Update readme

* Clean up README formatting and remove blank lines

Removed extra blank lines and adjusted formatting in the README.

* fix: Update readme to explain template structure

* fix typos

* Shorten README

* Add double-backticks

* One more typo

* Hierarchy of README sections

* README refinement

Author: fsbraun

CHANGELOG.rst

@@ -2,6 +2,12 @@
 Changelog
 =========
 
+3.0.1 (2026-09-18)
+==================
+
+* fix: Draft static aliases disappeared when viewing pages on site by @fsbraun in https://github.com/django-cms/djangocms-alias/pull/295
+* fix: Error message message referred to wrong package by @mbi in https://github.com/django-cms/djangocms-alias/pull/296
+
 3.0.0 (2026-09-17)
 ==================
 

README.rst

@@ -1,5 +1,3 @@
-
-
 ****************
 django CMS Alias
 ****************
@@ -58,6 +56,36 @@ Run::
 to perform the application's database migrations.
 
 
+=============
+Configuration
+=============
+
+django CMS Alias provides several Django settings to control its behavior:
+
+``STATIC_ALIAS_EDITING_ENABLED``
+    Default: ``True``
+
+    Controls whether static aliases can be edited directly on frontend editable objects
+    (such as pages) that include the ``{% static_alias %}`` template tag. When set to ``False``,
+    static aliases will not be visible in the structure board and only editable from the alias
+    admin endpoint.
+
+``VERSIONING_ALIAS_MODELS_ENABLED``
+    Default: ``True`` (if djangocms-versioning is installed)
+
+    Enables versioning support for alias models when djangocms-versioning is available. When enabled,
+    aliases support draft/published workflows, version history, and proper content lifecycle management.
+    Set to ``False`` to disable versioning for aliases even if djangocms-versioning is installed. Any changes
+    to any alias will then be immediately visible to the world.
+
+``MODERATING_ALIAS_MODELS_ENABLED``
+    Default: ``True`` (if djangocms-moderation is installed)
+
+    Enables moderation workflows for alias models when djangocms-moderation is available. When enabled,
+    aliases can be subject to approval workflows before publication. Set to ``False`` to disable moderation
+    for aliases even if djangocms-moderation is installed.
+
+
 =====
 Usage
 =====
@@ -75,15 +103,62 @@ Example::
       {% 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.
 
-Side notes
-==========
+=========
+Templates
+=========
 For the plugin to work out of the box ``{% block content %}`` is expected to exist in your main ``base.html`` file.
+Here is the template hierarchy for the edit and preview endpoints::
+
+    base.html
+        └── djangocms_alias/base.html {% block content %}
+              └── djangocms_alias/alias_content_preview.html  {% block alias_content %}
+
+Use Django's template override mechanism to customize these templates as needed. Say, if your base template has
+a different name and the content goes into a block called ``main_content``, you would create a template at
+``templates/djangocms_alias/base.html`` with the following content::
+    {% extends "mybase.html" %}
+    {% load i18n %}
+
+    {% block title %}{% translate "Aliases" %}{% endblock %}
+    {% block main_content %}
+        <div class="aliases my-additional-class">
+            {% block aliases_content %}
+            {% endblock aliases_content %}
+        </div>
+    {% endblock main_content %}
+
+
 
 .. |PyPiVersion| image:: https://img.shields.io/pypi/v/djangocms-alias.svg?style=flat-square
     :target: https://pypi.python.org/pypi/djangocms-alias
@@ -101,4 +176,4 @@ For the plugin to work out of the box ``{% block content %}`` is expected to exi
 
 .. |CmsVersion| image:: https://img.shields.io/pypi/frameworkversions/django-cms/djangocms-alias.svg?style=flat-square
     :target: https://pypi.python.org/pypi/djangocms-alias
-    :alt: django CMS versions
+    :alt: django CMS versions

djangocms_alias/__init__.py

@@ -3,4 +3,4 @@
 A reference can be added to any placeholder using the Alias plugin.
 """
 
-__version__ = "3.0.0"
+__version__ = "3.0.1"

djangocms_alias/migrations/0005_dynamic_slot_names.py

@@ -34,8 +34,12 @@ def migrate_slots(apps, schema_editor, forward=True):
             elif len(slots) > 1:
                 print(
                     f"AliasContent {alias_content.pk} has multiple placeholders, expected only one. "
-                    "Skipping migration for this instance."
+                    "Skipping migration for this instance:\n"
+                    f"{alias_content.alias.static_code or alias_content.name} "
+                    f"({alias_content.language}, pk={alias_content.pk})",
                 )
+                for placeholder in slots:
+                    print(f" - Placeholder {placeholder.pk} with slot '{placeholder.slot}'")
 
 
 class Migration(migrations.Migration):

djangocms_alias/rendering.py

@@ -13,7 +13,7 @@
 from django.template.response import TemplateResponse
 from django.utils.safestring import mark_safe
 
-from djangocms_alias.templatetags.djangocms_alias_tags import StaticAlias
+from djangocms_alias.templatetags.djangocms_alias_tags import StaticAlias, _static_alias_editing_enabled
 
 from .models import Alias, AliasContent
 
@@ -28,6 +28,11 @@ def render_alias_content(request: HttpRequest, alias_content: str) -> TemplateRe
 
 
 def get_declared_static_aliases(template: str) -> list["DeclaredStaticAlias"]:
+    """Scan a template for static_alias declarations.
+    Returns a list of DeclaredStaticAlias namedtuples.
+    """
+    if _static_alias_editing_enabled is False:
+        return []
     compiled_template = get_template(template)
     nodes = _scan_placeholders((_get_nodelist(compiled_template)), node_class=StaticAlias)
     placeholders = [node.get_declaration() for node in nodes]

djangocms_alias/templates/djangocms_alias/base.html

@@ -1,7 +1,7 @@
 {% extends "base.html" %}
-{% load i18n static sekizai_tags %}
+{% load i18n %}
 
-{% block title %}{% trans "Aliases" %}{% endblock %}
+{% block title %}{% translate "Aliases" %}{% endblock %}
 
 {% block breadcrumb %}{% endblock %}
 {% block footer %}{% endblock %}

djangocms_alias/templatetags/djangocms_alias_tags.py

@@ -9,6 +9,7 @@
 from cms.utils.placeholder import validate_placeholder_name
 from cms.utils.urlutils import add_url_parameters, admin_reverse
 from django import template
+from django.conf import settings
 
 from ..constants import DEFAULT_STATIC_ALIAS_CATEGORY_NAME, USAGE_ALIAS_URL_NAME
 from ..models import Alias, AliasContent, Category
@@ -18,15 +19,17 @@
 
 DeclaredStaticAlias = namedtuple("DeclaredStaticAlias", ["static_code", "site"])
 
+_static_alias_editing_enabled = getattr(settings, "STATIC_ALIAS_EDITING_ENABLED", True)
+
 
 @register.simple_tag(takes_context=False)
-def get_alias_usage_view_url(alias, **kwargs):
+def get_alias_usage_view_url(alias, **kwargs) -> str:
     url = admin_reverse(USAGE_ALIAS_URL_NAME, args=[alias.pk])
     return add_url_parameters(url, **ChainMap(kwargs))
 
 
 @register.filter()
-def admin_view_url(obj):
+def admin_view_url(obj) -> str:
     if obj and is_editable_model(obj.__class__):
         # Is obj frontend-editable?
         return get_object_preview_url(obj)
@@ -41,12 +44,12 @@ def admin_view_url(obj):
 
 
 @register.filter()
-def verbose_name(obj):
+def verbose_name(obj) -> str:
     return obj._meta.verbose_name
 
 
 @register.simple_tag(takes_context=True)
-def render_alias(context, instance):
+def render_alias(context, instance) -> str:
     request = context["request"]
 
     toolbar = get_toolbar_from_request(request)
@@ -83,7 +86,7 @@ class StaticAlias(Tag):
         ],
     )
 
-    def _get_alias(self, request, static_code, extra_bits):
+    def _get_alias(self, request, static_code, extra_bits) -> Alias | None:
         alias_filter_kwargs = {
             "static_code": static_code,
         }
@@ -116,10 +119,10 @@ def _get_alias(self, request, static_code, extra_bits):
                 alias_creation_kwargs["site"] = current_site
 
             alias = Alias.objects.create(category=default_category, **alias_creation_kwargs)
-
         if (
             not alias.get_content(language=self.language, show_draft_content=self.get_draft_content)
             and request.user.is_authenticated
+            and self.get_draft_content
         ):
             alias_content = AliasContent.objects.with_user(request.user).create(
                 alias=alias,
@@ -129,7 +132,7 @@ def _get_alias(self, request, static_code, extra_bits):
             alias._content_cache[self.language] = alias_content
         return alias
 
-    def render_tag(self, context, static_code, extra_bits, nodelist=None):
+    def render_tag(self, context, static_code, extra_bits, nodelist=None) -> str:
         request = context.get("request")
 
         if not static_code or not request:
@@ -158,16 +161,18 @@ def render_tag(self, context, static_code, extra_bits, nodelist=None):
                 context=context,
                 nodelist=nodelist,
                 use_cache=True,
-                editable=editable,
+                editable=editable and _static_alias_editing_enabled,
             )
-            if self.toolbar.edit_mode_active and not editable:
+            if self.toolbar.edit_mode_active and not editable and _static_alias_editing_enabled:
                 # Also non-editable placeholders need interactivity in the structure board
                 content += renderer.get_placeholder_toolbar_js(placeholder)
             return content
         return ""
 
-    def get_declaration(self):
+    def get_declaration(self) -> DeclaredStaticAlias | None:
         """Used to identify static_alias declarations"""
+        if not _static_alias_editing_enabled:
+            return None
         static_code = str(self.kwargs["static_code"].var).strip('"').strip("'")
         site = False
         if isinstance(self.kwargs["extra_bits"], ListValue):

pyproject.toml

@@ -22,6 +22,7 @@ classifiers = [
     "Framework :: Django :: 5.0",
     "Framework :: Django :: 5.1",
     "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
     "Framework :: Django CMS :: 5.0",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",

tests/requirements/compile.py

@@ -10,6 +10,8 @@
     "py311-dj52-cms50": [],
     "py312-dj52-cms50": [],
     "py313-dj52-cms50": [],
+    "py312-dj60-cms50": [],
+    "py313-dj60-cms50": [],
     "py313-djmain-cmsdev": [],
     "py313-djmain-cms50": [],
 }
@@ -20,6 +22,7 @@
     "dj50": "Django>=5.0,<5.1",
     "dj51": "Django>=5.1,<5.2",
     "dj52": "Django>=5.2,<5.3",
+    "dj60": "Django>=6.0a1,<6.1",
 }
 
 cms_dict = {

tests/requirements/py311-dj52-cms50-default.txt

@@ -14,7 +14,7 @@ coverage[toml]==7.8.0
     # via
     #   -r requirements.in
     #   pytest-cov
-django==5.2.5
+django==5.2.6
     # via
     #   django-classy-tags
     #   django-cms
@@ -29,7 +29,7 @@ django-classy-tags==4.1.0
     #   -r requirements.in
     #   django-cms
     #   django-sekizai
-django-cms==5.0.2
+django-cms==5.0.3
     # via djangocms-versioning
 django-formtools==2.5.1
     # via django-cms