docs: Add inline-editing how-to (#261)

Author: fsbraun

docs/source/how-to/index.rst

@@ -13,6 +13,7 @@ step-by-step guidance.
    :maxdepth: 1
 
    use-frontend-as-component
+   inline-editing
    add-frontend-plugins
    extend-frontend-plugins
    add-tab-style

docs/source/how-to/inline-editing.rst

@@ -0,0 +1,116 @@
+.. _inline_editing_custom_components:
+
+################################################
+How to Use Inline Editing with Custom Components
+################################################
+
+.. versionadded:: 2.0
+
+``djangocms-frontend`` introduces simplified support for **inline editing** in custom
+components, making it easier to edit content directly on the page without opening the
+plugin'S change form. This guide will walk you through using the ``inline_field``
+template tag to enable inline editing for your custom frontend components.
+
+.. note::
+
+    Inline editing requires djangocms-text to be installed and configured in your project.
+
+
+Understanding the ``inline_field`` Template Tag
+=============================================
+
+The ``inline_field`` template tag allows you to make specific fields editable directly from
+the page. It works by wrapping a field in an inline editing context, which is recognized by
+django CMS's edit mode.
+
+Syntax:
+
+.. code-block:: django
+
+    {% load frontend_tags %}
+    {% inline_field instance "field_name" %}
+
+- ``instance`` - The plugin or model instance.
+- ``"field_name"`` - The name of the field you want to make editable inline.
+
+If not in edit mode the template tag will render the field as plain text.
+
+.. note::
+
+    The ``inline_field`` tag is only available for fields that are explicitly listed in
+    the ``frontend_editable_fields`` property of the plugin. The tag itself is a shortcut
+    for django CMS's ``render_model`` tag. Since django CMS 5, this tags works for all
+    CMS plugins (and not only for third-party models). For earlier versions of django CMS
+    djangocms-frontend includes a custom extension for frontend plugins to support inline editing.
+
+
+Step-by-Step: Adding Inline Editing to a Custom Component
+=========================================================
+
+1. **Define Your Custom Component Plugin**
+
+   First, create a djangoCMS plugin for your custom component. Example:
+
+   .. code-block:: python
+
+       from cms.plugin_base import CMSPluginBase
+       from cms.plugin_pool import plugin_pool
+       from django.utils.translation import gettext_lazy as _
+       from djangocms_frontend.models import FrontendUIItem
+
+       class CustomComponentPlugin(CMSPluginBase):
+           model = FrontendUIItem  # Base model
+           name = _("Custom Component")
+           module = _("Frontend")
+           render_template = "frontend/custom_component.html"
+
+       plugin_pool.register_plugin(CustomComponentPlugin)
+
+2. **Modify the Component Template to Support Inline Editing**
+
+   Open the template file (``frontend/custom_component.html``) and update it using the
+   ``inline_field`` tag:
+
+   .. code-block:: django
+
+       {% load frontend_tags %}
+
+       <div class="custom-component">
+           <h2>{% inline_field instance "title" %}</h2>
+           <p>{% inline_field instance "description" %}</p>
+       </div>
+
+3. **Explicitly allow the field for inline editing**
+
+   In the plugin definition, add the field to the ``frontend_editable_fields`` list:
+
+   .. code-block:: python
+
+        class CustomComponentPlugin(CMSPluginBase):
+           model = FrontendUIItem  # Base model
+           name = _("Custom Component")
+           module = _("Frontend")
+           render_template = "frontend/custom_component.html"
+           frontend_editable_fields = ["title", "description"]
+
+4. **Test Inline Editing**
+
+   - Run the Django server:
+
+     .. code-block:: bash
+
+        python manage.py runserver
+
+   - Log in as an admin user and enter **Edit Mode**.
+   - Add your custom component to a page.
+   - Click on the text fields to edit them inline.
+   - Leave the field, and changes will be stored automatically in the database.
+
+
+Additional Considerations
+=========================
+
+- **Rich Text Editing:** If the field is a ``HTMLField``, django CMS text will automatically use
+  a rich text editor for inline editing.
+- **CSS & JavaScript Adjustments:** In rare cases custom component's styles can interfere
+  with django CMS text's inline editing interface. More specific rules typically solve the issue.

docs/source/how-to/use-frontend-as-component.rst

@@ -1,8 +1,8 @@
 
 .. _components:
 
-Using frontend plugins as components in templates
-=================================================
+How to use frontend plugins as components in templates
+======================================================
 
 .. versionadded:: 2.0
 
@@ -99,8 +99,9 @@ use the ``{% plugin %}`` template tag with each plugin.
     a ``{% plugin %}`` tag. This is because the ``{% plugin %}`` tag does
     preprocess the content and placeholders are not recognized by django CMS.
 
+
 Multi-line tags
-===============
+---------------
 
 Multi-line tags are not supported in Django templates. For components with many
 parameters this can lead to long lines of code. To make the code more readable