docs: Deduplication and clarity in the tutorials (#317)

Co-authored-by: Fabian Braun <fsbraun@gmx.de>

Author: marbru

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::
@@ -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:

docs/source/tutorial/custom_components.rst

@@ -1,71 +1,39 @@
 .. _custom_components:
 
-####################################
-Building Custom Frontend Components
-####################################
+#######################################
+Building Custom Components With Form Classes
+#######################################
 
 .. 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 **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>`.
 
-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
@@ -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
 ---------------------------------------
 
@@ -88,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):
@@ -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.
 
 
@@ -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
 ==========
@@ -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.

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 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.

docs/source/tutorial/template_components.rst

@@ -1,7 +1,7 @@
 .. _template_components:
 
 ############################
-Building Template Components
+Simplified Component Creation with Templates
 ############################
 
 .. index::
@@ -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/
@@ -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 %}
@@ -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 Frontend Component <custom_components>`
+or a :ref:`custom Plugin<how-to-add-frontend-plugins>`
+
+
 Examples
 ========