From c0f7c0bcc218f0a80638c9012eac94d9523741e7 Mon Sep 17 00:00:00 2001 From: Mar Date: Tue, 21 Oct 2025 13:36:12 +0200 Subject: [PATCH 1/4] Cleanup of tutorials, needs fixing some markup errors --- docs/source/tutorial/builtin_components.rst | 17 +++- docs/source/tutorial/custom_components.rst | 96 ++++++++------------ docs/source/tutorial/index.rst | 4 +- docs/source/tutorial/template_components.rst | 86 +++++------------- 4 files changed, 80 insertions(+), 123 deletions(-) diff --git a/docs/source/tutorial/builtin_components.rst b/docs/source/tutorial/builtin_components.rst index 3c8e0940..e353a0d3 100644 --- a/docs/source/tutorial/builtin_components.rst +++ b/docs/source/tutorial/builtin_components.rst @@ -1,7 +1,7 @@ .. _built_in_components: ###################################### -Using Built-In Bootstrap 5 Components +Installation and Usage with Built-In Components ###################################### .. index:: @@ -91,6 +91,21 @@ Configuration '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 `, 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: diff --git a/docs/source/tutorial/custom_components.rst b/docs/source/tutorial/custom_components.rst index 9c3c192c..03627840 100644 --- a/docs/source/tutorial/custom_components.rst +++ b/docs/source/tutorial/custom_components.rst @@ -1,71 +1,57 @@ .. _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 +**Custom CMS 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. -When working with `Tailwind CSS `_, for example, you either create your custom -frontend components or customize components from providers, e.g. `Tailwind UI `_, -`Flowbite `_, or the community `Tailwind Components `_. +`djangocms-frontend` provides a simple way for developers to create **custom Frontend CMS Components**, +by subclassing the `CMSFrontendComponent` class and providing a custom template. +This approach requires minimal +Python coding, while still offering flexibility and control over the component's behavior and appearance. -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. -Installation -============ -Install ``djangocms-frontend`` and add it to your project as described here: :ref:`built_in_components`. +In this tutorial, we will explore how to create custom **CMS Frontend Components**. +These components empower developers to provide visually appealing components to content editors +with minimal coding. -If you do not use the built-in components, you do not need to add them to your ``INSTALLED_APPS``. +- Components are defined by subclassing the `CMSFrontendComponent` class. +- Visual presentation is controlled via templates. +- Django CMS allows to register and manage these components seamlessly. -.. code-block:: python +Custom frontend components are more versatile than :ref:`template_components`, but require some minimal +Python coding. Technically, you create a custom frontend component by declaring its change form and +rendering template. - INSTALLED_APPS = [ - 'easy_thumbnails', - 'djangocms_link', # Required if djangocms_frontend.contrib.link is used - # Main frontend app - pre-built components not needed - 'djangocms_frontend', - ] +Hero CMS component example +========================== -Adding Styles and JavaScript -============================ +In this tutorial we will create again a **Hero component** similar to the one in the +:ref:`previous chapter `, but this time with python code. -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 @@ -75,6 +61,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 --------------------------------------- @@ -165,7 +161,7 @@ The templates could be, for example: {{ instance.text }} -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. @@ -193,22 +189,4 @@ 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()``. - -Conclusion -========== - -In this tutorial, we explored how to create custom frontend components. These components empower developers to -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. +For maximun flexibility in your customized components, you can build a :ref:`custom Plugin`. diff --git a/docs/source/tutorial/index.rst b/docs/source/tutorial/index.rst index 29273197..2b35a489 100644 --- a/docs/source/tutorial/index.rst +++ b/docs/source/tutorial/index.rst @@ -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 **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. diff --git a/docs/source/tutorial/template_components.rst b/docs/source/tutorial/template_components.rst index 7715389e..4a7380d0 100644 --- a/docs/source/tutorial/template_components.rst +++ b/docs/source/tutorial/template_components.rst @@ -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 `_, for example, you -either create your custom components or customize components from providers, -e.g. `Tailwind UI `_, -`Flowbite `_, or the community -`Tailwind Components `_. -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 ``/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//cms_components/` directory** of your installed apps. + Ensure your DjangoCMS app has the following structure:: theme_app/ @@ -84,20 +45,19 @@ Ensure your DjangoCMS app has the following structure:: views.py admin.py -Creating the Template Component --------------------------------- +In this case, `heme_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:: {% load frontend cms_component %} @@ -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: @@ -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 ` +or a :ref:`custom Plugin` + + Examples ======== From d1964a71e21d29788aefcab79706a88ec7db9605 Mon Sep 17 00:00:00 2001 From: Mar Date: Wed, 22 Oct 2025 10:59:46 +0200 Subject: [PATCH 2/4] Fix errors --- docs/source/tutorial/builtin_components.rst | 52 ++++++++++---------- docs/source/tutorial/custom_components.rst | 43 +++++++--------- docs/source/tutorial/index.rst | 2 +- docs/source/tutorial/template_components.rst | 4 +- 4 files changed, 48 insertions(+), 53 deletions(-) diff --git a/docs/source/tutorial/builtin_components.rst b/docs/source/tutorial/builtin_components.rst index e353a0d3..c8c35a44 100644 --- a/docs/source/tutorial/builtin_components.rst +++ b/docs/source/tutorial/builtin_components.rst @@ -63,32 +63,32 @@ 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 diff --git a/docs/source/tutorial/custom_components.rst b/docs/source/tutorial/custom_components.rst index 03627840..9dfce4d5 100644 --- a/docs/source/tutorial/custom_components.rst +++ b/docs/source/tutorial/custom_components.rst @@ -9,37 +9,19 @@ Building Custom CMS Frontend Components .. versionadded:: 2.0 -**Custom CMS 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. -`djangocms-frontend` provides a simple way for developers to create **custom Frontend CMS Components**, -by subclassing the `CMSFrontendComponent` class and providing a custom template. -This approach requires minimal -Python coding, while still offering flexibility and control over the component's behavior and appearance. - - - - -In this tutorial, we will explore how to create custom **CMS Frontend Components**. -These components empower developers to provide visually appealing components to content editors -with minimal coding. - -- Components are defined by subclassing the `CMSFrontendComponent` class. -- Visual presentation is controlled via templates. -- Django CMS allows to register and manage these components seamlessly. - -Custom frontend components are more versatile than :ref:`template_components`, but require some minimal -Python coding. Technically, you create a custom frontend component by declaring its change form and -rendering template. +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. Hero CMS component example ========================== In this tutorial we will create again a **Hero component** similar to the one in the -:ref:`previous chapter `, but this time with python code. - +:ref:`previous chapter `, but this time via code. Directory Structure ------------------- @@ -190,3 +172,16 @@ the resulting plugin class with the exception of ``get_render_template()``. Simi 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`. + + +Conclusion +========== + +In this tutorial, we explored how to create custom frontend components. These components empower developers to +provide visually appealing components to content editors with minimal coding. + +By following the steps outlined above, you can: + +- 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. \ No newline at end of file diff --git a/docs/source/tutorial/index.rst b/docs/source/tutorial/index.rst index 2b35a489..846d540f 100644 --- a/docs/source/tutorial/index.rst +++ b/docs/source/tutorial/index.rst @@ -18,7 +18,7 @@ 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 components, allowing you **define them by their HTML templates, without any code**. 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. diff --git a/docs/source/tutorial/template_components.rst b/docs/source/tutorial/template_components.rst index 4a7380d0..a2fca905 100644 --- a/docs/source/tutorial/template_components.rst +++ b/docs/source/tutorial/template_components.rst @@ -31,7 +31,7 @@ Directory Structure ------------------- `djangocms-frontend` will **automatically locate and register template components** by looking for them - **in the `templates//cms_components/` directory** of your installed apps. + in the **``templates//cms_components/``** directory of your installed apps. Ensure your DjangoCMS app has the following structure:: @@ -45,7 +45,7 @@ Ensure your DjangoCMS app has the following structure:: views.py admin.py -In this case, `heme_app/templates/theme_app/cms_components/hero.html` will be the template +In this example, ``theme_app/templates/theme_app/cms_components/hero.html`` will be the template defining our custom hero component. .. note:: From 720507d1f8d55f6fe6addb6a94ed9e8dad3063ea Mon Sep 17 00:00:00 2001 From: Mar Date: Wed, 22 Oct 2025 12:38:05 +0200 Subject: [PATCH 3/4] Missing an import in the code sample --- docs/source/tutorial/custom_components.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorial/custom_components.rst b/docs/source/tutorial/custom_components.rst index 9dfce4d5..4b4a51fe 100644 --- a/docs/source/tutorial/custom_components.rst +++ b/docs/source/tutorial/custom_components.rst @@ -66,7 +66,7 @@ Add a ``cms_components.py`` file to the ``theme`` app (see structure above): from djangocms_frontend.component_base import CMSFrontendComponent from djangocms_frontend.component_pool import components from djangocms_frontend.contrib.image.fields import ImageFormField - + from django import forms @components.register class MyHeroComponent(CMSFrontendComponent): From 3aae21a26054cb41c276395613fe2c156c521370 Mon Sep 17 00:00:00 2001 From: Mar Date: Mon, 27 Oct 2025 11:19:35 +0100 Subject: [PATCH 4/4] Rename tutorials and restore Custom Frontend Component name (without the 'CMS') --- docs/source/tutorial/custom_components.rst | 6 +++--- docs/source/tutorial/index.rst | 2 +- docs/source/tutorial/template_components.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/tutorial/custom_components.rst b/docs/source/tutorial/custom_components.rst index 4b4a51fe..2a74d69e 100644 --- a/docs/source/tutorial/custom_components.rst +++ b/docs/source/tutorial/custom_components.rst @@ -1,7 +1,7 @@ .. _custom_components: ####################################### -Building Custom CMS Frontend Components +Building Custom Components With Form Classes ####################################### .. index:: @@ -9,7 +9,7 @@ Building Custom CMS Frontend Components .. versionadded:: 2.0 -In this tutorial, we will explore how to create custom **CMS Frontend Components**. These are more +In this tutorial, we will explore how to create custom **Frontend Components**. These are more versatile than :ref:`template_components`, but require some minimal Python coding. You create a custom frontend component by subclassing the ``CMSFrontendComponent`` class to @@ -21,7 +21,7 @@ Hero CMS component example ========================== In this tutorial we will create again a **Hero component** similar to the one in the -:ref:`previous chapter `, but this time via code. +:ref:`previous chapter `. Directory Structure ------------------- diff --git a/docs/source/tutorial/index.rst b/docs/source/tutorial/index.rst index 846d540f..1637d5aa 100644 --- a/docs/source/tutorial/index.rst +++ b/docs/source/tutorial/index.rst @@ -23,7 +23,7 @@ that gets the job done for your project. needed. This is the fastest approach to create ``djangocms-frontend`` components. Template-based (or auto) components are auto-detected. -3. **Custom CMS Frontend Component** development – A more advanced method that lets you create +3. **Custom 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. diff --git a/docs/source/tutorial/template_components.rst b/docs/source/tutorial/template_components.rst index a2fca905..792d73fd 100644 --- a/docs/source/tutorial/template_components.rst +++ b/docs/source/tutorial/template_components.rst @@ -1,7 +1,7 @@ .. _template_components: ############################ -Building Template Components +Simplified Component Creation with Templates ############################ .. index:: @@ -265,7 +265,7 @@ 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 ` +For more powerful customization options, consider building a :ref:`custom Frontend Component ` or a :ref:`custom Plugin`