Skip to content

docs: Fix inconsistency in Documentation #329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
va-lang wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: Fix inconsistency in Documentation #329

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f53de2a
djangocms-frontend/docs-328:Inconsistency in Documentation
Nov 29, 2025
306c218
Merge branch 'main' into djangocms-frontend/docs-328
fsbraun Nov 29, 2025
bcb5c65
Improve clarity in extend-frontend-plugins documentation
fsbraun Nov 30, 2025
1fd2500
Merge branch 'main' into djangocms-frontend/docs-328
fsbraun Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/source/how-to/extend-frontend-plugins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@
How to extend built-in components
**********************************

Existing components can be extended through two type of class mixins.
``djangocms-frontend`` looks for these mixins in two places:
Existing components can be extended through **two type of class mixins**.
``djangocms-frontend`` tries to autodiscover them by looking for these mixins
in two places:

#. In the theme module. Its name is specified by the setting
``DJANGOCMS_FRONTEND_THEME`` and defaults to ``djangocms_frontend``.
``DJANGOCMS_FRONTEND_THEME`` and defaults to ``theme``.
For a theme app called ``theme`` and the bootstrap5 framework this
would be ``theme.frontends.bootstrap5.py``.
Copy link
Contributor

@marbru marbru Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, in the below example the module is `theme.frameworks.bootstrap5.py. So does this line need updating as well?

Copy link
Member

@fsbraun fsbraun Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it does!


Expand All @@ -32,7 +33,7 @@ The framework module is primarily thought to allow for adaptation of
RenderMixins
============

The render mixins are called "``*PluginName*RenderMixin``", e.g.
The render mixins are called "``<PluginName>RenderMixin``", e.g.
``AlertRenderMixin`` and are applied to the plugin class. This allows
for the redefinition of the ``CMSPlugin.render`` method, especially to
prepare the context for rendering.
Expand All @@ -51,7 +52,7 @@ Form mixins are used to add fields to a plugin's admin form. These
fields are available to the render mixins and, of course, to the plugin
templates.

Form mixins are called "``*PluginName*FormMixin``", e.g. ``AlertFormMixin`` and are
Form mixins are called "``<PluginName>FormMixin``", e.g. ``AlertFormMixin`` and are
applied to the editing form class. Form mixins are a subclass of
``entangled.EntangledModelFormMixin``.

Expand All @@ -62,8 +63,8 @@ applied to the editing form class. Form mixins are a subclass of
single: Create a theme
single: Themes

Working example
===============
Working example: Extending the ``GridContainerPlugin``
======================================================

Copy link
Contributor

@marbru marbru Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right after the first paragraph where you're instructed to create the theme app, I would add a new (or a note) saying something along the lines of:

Make sure you make the necessary changes in your settings.py file: your theme app should be added to the list of INSTALLED_APPS, plus pointed to by the DJANGOCMS_FRONTEND_THEME setting:

INSTALLED_APPS = [
   ...,
   'theme',
   ...
]
DJANGOCMS_FRONTEND_THEME ="theme"```

Let's say you wanted to extend the ``GridContainerPlugin`` to offer the
option for a background image, and say a blur effect. The way to do it
Expand Down Expand Up @@ -233,9 +234,9 @@ Then, a new template is needed (in
backdrop-filter: blur({{ instance.container_blur }}px);
{% endif %}"
{% endif %}>
{% if instance.image %}
{% if instance.container_image %}
<div class="image"
style="background-image: url('{{ instance.image.url }}');
style="background-image: url('{{ instance.container_image.url }}');
background-position: {{ instance.image_position|default:'center center' }};
background-repeat: no-repeat;background-size: cover;
{% if instance.container_blur %}
Expand Down Expand Up @@ -313,6 +314,5 @@ information will be preserved.
import ``CMSUIPlugin`` (import from ``djangocms_frontend.cms_plugins``)
as base class for the plugins.

* Create ``models.py``
file for the models (which need to be proxy models of ``FrontendUIItem``
(import from ``djangocms_frontend.models``).
* Create ``models.py`` file for the models (which need to be proxy models
of ``FrontendUIItem`` (import from ``djangocms_frontend.models``).