Cleanup of tutorials, needs fixing some markup errors

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::
@@ -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 <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,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 <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>`_.
+`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 <template_components>`, 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:
     <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,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<how-to-add-frontend-plugins>`.

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.

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 <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 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::
 
     <!-- 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 CMS Frontend Component <custom_components>`
+or a :ref:`custom Plugin<how-to-add-frontend-plugins>`
+
+
 Examples
 ========