Skip to content

docs: Deduplication and clarity in the tutorials #317

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

Merged
merged 6 commits into from
Oct 28, 2025
Merged

docs: Deduplication and clarity in the tutorials #317

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c0f7c0b
Cleanup of tutorials, needs fixing some markup errors
marbru Oct 21, 2025
d1964a7
Fix errors
marbru Oct 22, 2025
720507d
Missing an import in the code sample
marbru Oct 22, 2025
47e7a67
Merge remote-tracking branch 'upstream/main' into docs/tutorial-cleanup
marbru Oct 27, 2025
3aae21a
Rename tutorials and restore Custom Frontend Component name (without …
marbru Oct 27, 2025
42aa9f2
Merge branch 'main' into docs/tutorial-cleanup
fsbraun Oct 28, 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
69 changes: 42 additions & 27 deletions docs/source/tutorial/builtin_components.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _built_in_components:

######################################
Using Built-In Bootstrap 5 Components
Installation and Usage with Built-In Components
######################################

.. index::
Expand Down Expand Up @@ -63,34 +63,49 @@ Configuration
Open your Django project's ``settings.py`` and add the following applications to ``INSTALLED_APPS`` -
you only need (and should) add the components you want content editors to use:

.. code-block:: python

INSTALLED_APPS = [
# Optional dependencies
'djangocms_icon',
'easy_thumbnails',
'djangocms_link', # Required if djangocms_frontend.contrib.link is used
# Main frontend components
'djangocms_frontend',
'djangocms_frontend.contrib.accordion',
'djangocms_frontend.contrib.alert',
'djangocms_frontend.contrib.badge',
'djangocms_frontend.contrib.card',
'djangocms_frontend.contrib.carousel',
'djangocms_frontend.contrib.collapse',
'djangocms_frontend.contrib.component',
'djangocms_frontend.contrib.content',
'djangocms_frontend.contrib.grid',
'djangocms_frontend.contrib.icon',
'djangocms_frontend.contrib.image',
'djangocms_frontend.contrib.jumbotron',
'djangocms_frontend.contrib.link',
'djangocms_frontend.contrib.listgroup',
'djangocms_frontend.contrib.media',
'djangocms_frontend.contrib.tabs',
'djangocms_frontend.contrib.utilities',
.. code-block:: python

INSTALLED_APPS = [
# Optional dependencies
'djangocms_icon',
'easy_thumbnails',
'djangocms_link', # Required if djangocms_frontend.contrib.link is used
# Main frontend components
'djangocms_frontend',
'djangocms_frontend.contrib.accordion',
'djangocms_frontend.contrib.alert',
'djangocms_frontend.contrib.badge',
'djangocms_frontend.contrib.card',
'djangocms_frontend.contrib.carousel',
'djangocms_frontend.contrib.collapse',
'djangocms_frontend.contrib.component',
'djangocms_frontend.contrib.content',
'djangocms_frontend.contrib.grid',
'djangocms_frontend.contrib.icon',
'djangocms_frontend.contrib.image',
'djangocms_frontend.contrib.jumbotron',
'djangocms_frontend.contrib.link',
'djangocms_frontend.contrib.listgroup',
'djangocms_frontend.contrib.media',
'djangocms_frontend.contrib.tabs',
'djangocms_frontend.contrib.utilities',
]

For example, if you don't want to use any built-in components because you plan on
:ref:`building your own <custom_components>`, a minimal setup of ``INSTALLED_APPS``
would look like this:

.. code-block:: python

INSTALLED_APPS = [
'easy_thumbnails',
'djangocms_link', # Required if djangocms_frontend.contrib.link is used
# Main frontend app - pre-built components not needed
'djangocms_frontend',
]



2. **Apply Migrations**

Run the following command to create the necessary database tables:
Expand Down
87 changes: 30 additions & 57 deletions docs/source/tutorial/custom_components.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,39 @@
.. _custom_components:

####################################
Building Custom Frontend Components
####################################
#######################################
Building Custom CMS Frontend Components
#######################################

.. index::
single: Custom frontend components

.. versionadded:: 2.0

Custom frontend components are a powerful tool for content editors, allowing them to build pages without
needing in-depth knowledge of design, HTML, or nested structures. Editors can simply add content to pre-defined
components, creating visually cohesive pages with ease.
In this tutorial, we will explore how to create custom **CMS Frontend Components**. These are more
versatile than :ref:`template_components`, but require some minimal Python coding.

When working with `Tailwind CSS <https://tailwindcss.com>`_, for example, you either create your custom
frontend components or customize components from providers, e.g. `Tailwind UI <https://tailwindui.com>`_,
`Flowbite <https://flowbite.com>`_, or the community `Tailwind Components <https://tailwindcomponents.com>`_.
You create a custom frontend component by subclassing the ``CMSFrontendComponent`` class to
declare the form, plus providing a rendering template, and `djangocms-frontend` will take care
integrating it automatically.

With django CMS you make your components available to the content editors to simply add them to a page by a
click **and** frontend developers for use in templates from a single source.

Custom frontend components are more versatile than template components, but require some minimal Python coding.
Technically, you create a custom frontend component by declaring its change form and rendering template.
Hero CMS component example
==========================

Installation
============
In this tutorial we will create again a **Hero component** similar to the one in the
:ref:`previous chapter <template_components>`, but this time via code.

Install ``djangocms-frontend`` and add it to your project as described here: :ref:`built_in_components`.

If you do not use the built-in components, you do not need to add them to your ``INSTALLED_APPS``.

.. code-block:: python

INSTALLED_APPS = [
'easy_thumbnails',
'djangocms_link', # Required if djangocms_frontend.contrib.link is used
# Main frontend app - pre-built components not needed
'djangocms_frontend',
]


Adding Styles and JavaScript
============================

When building template components, you will need to provide your custom CSS files
either by adding them to the base templates to load on every page, or by adding a
django-sekizai block to each component.

Hero component example
======================
Directory Structure
-------------------

``djangocms-frontend`` will look for custom frontend components in the
**``cms_components`` module in any of your apps**. This way you can
**``cms_components`` module in any of your installed apps**. This way you can
either keep components together in one theme app, or keep them with where
they are used in different custom apps.

Directory Structure
-------------------

Let's go through this by creating a theme app::

python manage.py startapp theme

Custom frontend components live in the ``cms_components`` module of any of your apps.
Ensure your app has the following structure::

theme/
theme_app/
cms_components.py
migrations/
models.py
Expand All @@ -75,6 +43,16 @@ Ensure your app has the following structure::
views.py
admin.py

In this example, `cms_components.py` will contain the component definition, and `hero.html`
the presentation template.

.. note::

Components will create migrations since they use proxy models of ``djangocms-frontend``'s
``FrontendUIItem`` model which are necessary, for example, to manage permissions.
Those migrations will be added to the app containing the ``cms_component.py`` file.


Creating two Custom Frontend Components
---------------------------------------

Expand Down Expand Up @@ -165,7 +143,7 @@ The templates could be, for example:
<a class="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 me-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800"
href="{{ instance.link|to_url }}">{{ instance.text }}</a>

As always, django CMS manages styling and JavaScript dependencies with django-sekizai.
As always, django CMS manages styling and JavaScript dependencies with **django-sekizai**.
In this example, we add the Tailwind CSS CDN to the ``js`` block.


Expand Down Expand Up @@ -193,6 +171,8 @@ and can contain Python code to modify the behavior of a form. You cannot directl
the resulting plugin class with the exception of ``get_render_template()``. Similarly, you cannot add
Python code the model class, in this case with the exception of ``get_short_description()``.

For maximun flexibility in your customized components, you can build a :ref:`custom Plugin<how-to-add-frontend-plugins>`.


Conclusion
==========
Expand All @@ -202,13 +182,6 @@ provide visually appealing components to content editors with minimal coding.

By following the steps outlined above, you can:

- Create a theme app to house your custom components.
- Define components using the `CMSFrontendComponent` class.
- Leverage templates to control the visual presentation of your components.
- Register and manage your components seamlessly within django CMS.

.. note::

Components will create migrations since they use proxy models of ``djangocms-frontend``'s
``FrontendUIItem`` model which are necessary, for example, to manage permissions.
Those migrations will be added to the app containing the ``cms_component.py`` file.
- Register and manage your components seamlessly within django CMS.
4 changes: 2 additions & 2 deletions docs/source/tutorial/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,12 @@ that gets the job done for your project.
added to your project's ``INSTALLED_APPS``.

2. **Template Components** – The easiest approach creating or porting your own
**custom frontend components**, allowing you define components by their HTML templates. Special
custom components, allowing you to define them by their **HTML templates, without any code**. Special
``djangocms-frontend`` tags are used to provide the additional declarative information
needed. This is the fastest approach to create ``djangocms-frontend`` components.
Template-based (or auto) components are auto-detected.

3. **Custom Frontend Component** development – A more advanced method that lets you create
3. **Custom CMS Frontend Component** development – A more advanced method that lets you create
custom components with **minimal code**. This approach is more flexible than the
template-based method, but requires some Python coding providing more control over
the components add and change forms, for example.
Expand Down
86 changes: 25 additions & 61 deletions docs/source/tutorial/template_components.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,68 +10,29 @@ Building Template Components

.. versionadded:: 2.1

Custom components are a powerful tool for content editors, allowing them to build pages without needing
in-depth knowledge of design, HTML, or nested structures. Editors can simply add content to pre-defined
components, creating visually cohesive pages with ease.
**Template components** are the easiest approach to creating or porting your own custom
frontend components, allowing you to define custom components **using django templates,
without needing to write any Python code**.

When working with `Tailwind CSS <https://tailwindcss.com>`_, for example, you
either create your custom components or customize components from providers,
e.g. `Tailwind UI <https://tailwindui.com>`_,
`Flowbite <https://flowbite.com>`_, or the community
`Tailwind Components <https://tailwindcomponents.com>`_.

With django CMS you make your components available to the content editors to
simply add them to a page by a click **and** frontend developers for use in templates from a single
source.
Example Hero Template Component
===============================

Installation
============

Install ``djangocms-frontend`` and add it to your project as described here: :ref:`built_in_components`.

If you do not use the built-in components, you do not need to add them to your ``INSTALLED_APPS``.

.. code-block:: python

INSTALLED_APPS = [
'easy_thumbnails',
'djangocms_link', # Required if djangocms_frontend.contrib.link is used
# Main frontend app - built-in components from contrib not needed
'djangocms_frontend',
]


Adding Styles and JavaScript
============================

When building template components, you will need to provide your custom CSS files
either by adding them to the base templates to load on every page, or by adding a
django-sekizai block to each component.

Hero component
==============

``djangocms-frontend`` allows developers to extend its functionality by creating
**template components**. In this tutorial, we will create an **Hero component**
with the following fields:
In this tutorial, we will create a **Hero template component** with the following fields:

- ``title``: A required text field.
- ``slogan``: A required text area field.
- ``hero_image``: A required image field.

This component will be stored in a template directory named ``<app_name>/cms_components``
(or any subdirectory thereof).

.. note::
You can change the location of your template components inside your template directory
by setting the :attr:`DJANGOCMS_FRONTEND_COMPONENT_FOLDER` setting. The default is
``cms_components``. If you change it, you need to adjust the directory structure accordingly.

This component will be declared by using special djangocms tags in a template file,
with no python code required.

Directory Structure
-------------------

The template component lives in the template directory of any of your apps.
`djangocms-frontend` will **automatically locate and register template components** by looking for them
in the **``templates/<app_name>/cms_components/``** directory of your installed apps.

Ensure your DjangoCMS app has the following structure::

theme_app/
Expand All @@ -84,20 +45,19 @@ Ensure your DjangoCMS app has the following structure::
views.py
admin.py

Creating the Template Component
--------------------------------
In this example, ``theme_app/templates/theme_app/cms_components/hero.html`` will be the template
defining our custom hero component.

The **template component** must be stored in the ``cms_components`` directory
inside your app. ``djangocms-frontend`` expects you to follow Django's template
namespace convention. Create a new file at::
.. note::
You can change the location of your template components inside your template directory
by setting the :attr:`DJANGOCMS_FRONTEND_COMPONENT_FOLDER` setting. The default is
``cms_components``. If you change it, you need to adjust the directory structure accordingly.

theme_app/templates/theme_app/cms_components/hero.html

.. note::
No python code is required to create the component. The component is
defined in the template itself.
Creating the Template Component
--------------------------------

Then, add the following code::
Add the following code to the `hero.html` template::

<!-- theme_app/templates/theme_app/cms_components/hero.html -->
{% load frontend cms_component %}
Expand Down Expand Up @@ -291,7 +251,7 @@ The verbose choice label is appended by the actual value of the field between an


Limitations of template components
----------------------------------
==================================

Template components are a powerful tool for developers, but they have some limitations:

Expand All @@ -305,6 +265,10 @@ Template components are a powerful tool for developers, but they have some limit
Classes are instantiated by default, for example. This is ok for ``widget=forms.Textarea``, but potentially not
for more complex cases.

For more powerful customization options, consider building a :ref:`custom CMS Frontend Component <custom_components>`
or a :ref:`custom Plugin<how-to-add-frontend-plugins>`


Examples
========

Expand Down
Loading