docs: Improved clarity of template component tutorial (#267)

Author: fsbraun

docs/source/reference.rst

@@ -488,7 +488,7 @@ plugins.
 Management commands
 *******************
 
-Management commands are run by typing ``./manage.py frontend command`` in the
+Management commands are run by typing ``python -m manage frontend command`` in the
 project directory. ``command`` can be one of the following:
 
 ``migrate``
@@ -505,14 +505,18 @@ project directory. ``command`` can be one of the following:
     The drawback is, that references might become stale. This command prints all
     stale references, their plugins and pages/placeholder they belong to.
 
-``sync_permissions users`` or ``sync_permissions groups``
-    Django allows to set permissions for each user and group on a per plugin
-    level. This might become somewhat tedious which is why this command
-    will sync permissions. For each user or group it will copy the permissions
-    of ``djangocms_frontend.models.FrontendUIItem`` to all installed
-    ``djangocms-frontend`` plugins. If you need to change permissions for all
-    plugins this requires you only to change them for ``FrontendUIItem`` and
-    then syncing the new permission with these commands.
+.. _sync_permissions:
+
+``sync_permissions``
+    This command syncs permissions for users or groups. It is run with one of
+    the following arguments:
+
+    - ``users``: Syncs permissions for all users.
+    - ``groups``: Syncs permissions for all groups.
+
+    Permissions are copied from the ``FrontendUIItem`` model to all installed
+    plugins. This way you can set permissions for all plugins by setting them
+    for ``FrontendUIItem`` and then syncing them.
 
 
 *************

docs/source/tutorial/custom_components.rst

@@ -9,19 +9,20 @@ Building 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
+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.
 
-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>`_.
+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>`_.
 
 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
 ============
 
@@ -32,8 +33,6 @@ If you do not use the built-in components, you do not need to add them to your `
 .. code-block:: python
 
     INSTALLED_APPS = [
-        # Optional dependencies
-        'djangocms_icon',
         'easy_thumbnails',
         'djangocms_link',  # Required if djangocms_frontend.contrib.link is used
         # Main frontend app - pre-built components not needed
@@ -71,7 +70,7 @@ Ensure your app has the following structure::
         migrations/
         models.py
         templates/
-            components/
+            theme/
                 hero.html
         views.py
         admin.py
@@ -95,20 +94,19 @@ Add a ``cms_components.py`` file to the ``theme`` app (see structure above):
     class MyHeroComponent(CMSFrontendComponent):
         class Meta:
             # declare plugin properties
-            name = "My Hero Component"
-            render_template = "components/hero.html"
-            allow_children = True
-            mixins = ["Background"]
+            name = "My Hero Component"  # Name displayed in the CMS admin interface
+            render_template = "theme/hero.html"  # Template used to render the component
+            allow_children = True  # Allow child plugins inside this component
+            mixins = ["Background"]  # Add background styling options
             # for more complex components, you can add fieldsets
 
-        # declare fields
+        # Declare fields for the component
         title = forms.CharField(required=True)
         slogan = forms.CharField(required=True, widget=forms.Textarea)
         hero_image = ImageFormField(required=True)
 
-        # add description for the structure board
         def get_short_description(self):
-            return self.title
+            return self.title  # Display the title in the structure board
 
     @components.register
     class MyButton(CMSFrontendComponent):
@@ -149,7 +147,10 @@ The templates could be, for example:
                      {% endchildplugins %}
             </div>
             <div class="hidden lg:mt-0 lg:col-span-5 lg:flex">
-                <img src="{{ instance.hero_image.url }}" alt="{{ instance.image_related.alt }}">
+                {# Get the related object of the image field which itself is just a dict #}
+                {% with image=instance.hero_image|get_related_object %}
+                    <img src="{{ image.url }}" alt="{{ image.alt }}">
+                {% endwith %}
             </div>
         </div>
     </section>
@@ -167,8 +168,18 @@ The templates could be, for example:
 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.
 
-Understanding the Code
-----------------------
+
+.. note::
+
+    The component instance is available in the template as ``instance``. This is a proxy model of the
+    ``FrontendUIItem`` model, which is a subclass of Django's ``Model`` class. The instance has all the
+    fields declared in the component class.
+
+    Additionally, if the component does not have a field called ``instance``, the fields themselves are
+    available directly in the template. Both ways are equivalent::
+
+        {{ instance.title }}  {{ title }}
+        {{ instance.slogan }} {{ slogan }}
 
 
 
@@ -179,8 +190,9 @@ Custom frontend components are a powerful tool for developers, but they have a l
 
 **Limited Python code**: Custom components are (indirect) subclasses of Django's ``AdminForm`` class
 and can contain Python code to modify the behavior of a form. You cannot directly add Python code to
-the resulting plugin class with the exception of ``get_render_template()`` and ``save_model()``.
-Similarly, you cannot add Python code the model class, in this case with the exception of ``get_short_description()``.
+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
 ==========

docs/source/tutorial/index.rst

@@ -34,11 +34,9 @@ that gets the job done for your project.
    but also the most complex, since template, plugin, and forms need to be created.
    For custom plugin development, see the :ref:`how-to-add-frontend-plugins` guide.
 
+---------
 
-Tutorials
-#########
-
-
+**Start with one of the following tutorials:**
 
 .. toctree::
    :maxdepth: 1

docs/source/tutorial/template_components.rst

@@ -34,8 +34,6 @@ If you do not use the built-in components, you do not need to add them to your `
 .. code-block:: python
 
     INSTALLED_APPS = [
-        # Optional dependencies
-        'djangocms_icon',
         'easy_thumbnails',
         'djangocms_link',  # Required if djangocms_frontend.contrib.link is used
         # Main frontend app - built-in components from contrib not needed
@@ -67,7 +65,7 @@ as required for ``djangocms-frontend`` template components.
 Directory Structure
 -------------------
 
-The templte component lives in the template directory of any of your apps.
+The template component lives in the template directory of any of your apps.
 Ensure your DjangoCMS app has the following structure::
 
     theme_app/
@@ -117,7 +115,10 @@ Then, add the following code::
                     {% childplugins %}{% endchildplugins %}
             </div>
             <div class="hidden lg:mt-0 lg:col-span-5 lg:flex">
-                <img src="{{ hero_image.url }}">
+                {# Get the related object of the image field which itself is just a dict #}
+                {% with image=instance.hero_image|get_related_object %}
+                    <img src="{{ image.url }}" alt="{{ image.alt }}">
+                {% endwith %}
             </div>
         </div>
     </section>
@@ -133,7 +134,7 @@ Component Declaration
     {% cms_component "Hero" name=_("My Hero Component") %}
 
 This tag **declares** the component and assigns it a name (``Hero``). This is used internally
-by django CMS to identify the plguin later. The ``name`` parameter is used to display the
+by django CMS to identify the plugin later. The ``name`` parameter is used to display the
 component in the CMS admin interface. Internally the command declares a ``CMSFrontendComponent``
 class. All named arguments are added to the component's Meta class.
 
@@ -205,27 +206,36 @@ content, i.e. add/remove ``{% field %}`` tags, or change the ``{% cms_component
 the Django server to apply the changes.
 
 1. Restart your Django server.
-2. Create a new page end edit it.
+2. Create a new page And edit it.
 3. Add a new **Hero component** to a page from the plugin picker.
 4. Fill in the **title**, **slogan**, and **hero image** fields.
 5. Save and publish the page.
 
 Using the component in your templates
 -------------------------------------
 
-To use the component in your templates, you can use the ``{% plugin %}`` tag with the component's name.
-For example, to render the **Hero component** in a template, use the following code::
+To use the component in your templates outside django CMS, you can use the ``{% plugin %}`` tag with the
+component's name. For example, to render the **Hero component** in a template, use the following code::
 
     {% load frontend %}
     {% plugin "hero" title=_("Welcome to my new website") slogan=_("Building successful websites since 1896") %}
 
+.. note::
+    Do not forget to register the component with :attr:`CMS_COMPONENT_PLUGINS`. If you needed to list the single
+    component in the setting, the hero component's dotted path to its plugin would be
+    ``djangocms_frontend.cms_plugins.HeroPlugin``.
+
 
 Adding inline-editing to the component
 --------------------------------------
 
-When using `djangocms-text <https://github.com/django-cms/djangocms-text>`_, fields of the component can be
-marked as inline fields to activate inline editing. Simply replace ``{{ title }}`` and/or ``{{ slogan }}`` with
-``{% inline_field "title" %}`` and/or ``{% inline_field "slogan" %}``::
+When using `djangocms-text <https://github.com/django-cms/djangocms-text>`_, `CharField` and `HTMLFormField` fields
+of the component can be marked as inline fields to activate inline editing. Inline-editing fields can be changed in
+the edit endpoint by simply clicking inside and typing over the text - without the need to open an edit dialogue for
+the component.
+
+Simply replace ``{{ title }}`` and/or ``{{ slogan }}`` with ``{% inline_field "title" %}`` and/or
+``{% inline_field "slogan" %}``::
 
     <h1>{% inline_field "title" %}</h1>
     <p>{% inline_field "slogan" %}</p>
@@ -253,12 +263,44 @@ Template components are a powerful tool for developers, but they have some limit
   Classes are intantiated by default, for example. This is ok for ``widget=forms.Textarea``, but potentially not
   for more complex cases.
 
+
+Trouble Shooting
+================
+
+If the component does not appear in the plugin picker, check the following:
+
+1. **INSTALLED_APPS**: Verify that the app containing the component is listed in your ``INSTALLED_APPS`` setting.
+
+2. **Template Location**: Ensure the template file is located in the correct directory structure:
+   ``templates/<app_name>/cms_components/`` inside your app.
+
+3. **Server Restart**: Restart the Django server after creating or modifying the component template. Changes in
+   the declarative part are only reflected after server restart.
+
+4. **Rendering exceptions**: The template component will only be added if it renders without exception. Make
+   sure it does not fail if the context is empty. Check the server logs for errors during startup. Missing
+   dependencies or syntax errors in the template can prevent the component from being registered.
+
+5. **Migration module**: Make sure the app has a migration module. If not, create one with
+   ``python -m manage makemigrations <app_name>``.
+
+6. **Permissions**: Add the necessary permissions for the user/group if you are not the superuser.
+   Also see :ref:`sync_permissions`.
+
+If the issue persists, double-check the template syntax and ensure all required fields are properly defined.
+
 Conclusion
 ==========
 
-You have successfully created a **djangocms-frontend template component** using ``cms_component``!
-This structure allows editors to easily customize hero sections while maintaining a reusable
-and structured design.
+In this tutorial, you learned how to create a reusable **Hero component** using ``djangocms-frontend``.
+This approach allows you to:
+
+- Simplify component creation for editors by offering inline editing.
+- Maintain consistent design across your website by reusing the component.
+- Extend functionality without writing Python code.
+
+By following these steps, you can create additional components tailored to your project's needs.
+
 
 .. note::