Update docs, add empty children messages

fsbraun · fsbraun · commit 7518b4214e96 · 2024-05-29T10:49:36.000+02:00
diff --git a/djangocms_frontend/contrib/accordion/templates/djangocms_frontend/bootstrap5/accordion.html b/djangocms_frontend/contrib/accordion/templates/djangocms_frontend/bootstrap5/accordion.html
@@ -1,6 +1,7 @@
-{% load cms_tags %}
+{% load cms_tags frontend %}
 <{{ instance.tag_type }}{{ instance.get_attributes }} id="parent-{{ instance.pk|safe }}">
     {% for plugin in instance.child_plugin_instances %}
         {% with parentloop=forloop parent=instance %}{% render_plugin plugin %}{% endwith %}
+    {% empty %}{% user_message _("Add accordion items here") %}
     {% endfor %}
 </{{ instance.tag_type }}>
diff --git a/djangocms_frontend/contrib/accordion/templates/djangocms_frontend/bootstrap5/accordion_item.html b/djangocms_frontend/contrib/accordion/templates/djangocms_frontend/bootstrap5/accordion_item.html
@@ -1,4 +1,4 @@
-{% load cms_tags %}
+{% load cms_tags frontend %}
 {% spaceless %}
     <div class="accordion-item">
         <{{ parent.accordion_header_type|default:"h2" }} class="accordion-header"
@@ -15,6 +15,7 @@
         {% with parent=instance %}
             {% for plugin in instance.child_plugin_instances %}
                 {% with forloop as parentloop %}{% render_plugin plugin %}{% endwith %}
+            {% empty %}{% user_message _("Add content here") %}
             {% endfor %}
         {% endwith %}{% spaceless %}
     </div>
diff --git a/djangocms_frontend/settings.py b/djangocms_frontend/settings.py
@@ -72,6 +72,8 @@
     ],
 )
 
+SHOW_EMPTY_CHILDREN = getattr(django_settings, "DJANGOCMS_FRONTEND_SHOW_EMPTY_CHILDREN", False)
+
 FORM_OPTIONS = getattr(django_settings, "DJANGOCMS_FRONTEND_FORM_OPTIONS", {})
 
 
diff --git a/djangocms_frontend/templates/djangocms_frontend/html_container.html b/djangocms_frontend/templates/djangocms_frontend/html_container.html
@@ -1,5 +1,7 @@
-{% load cms_tags %}<{{ instance.tag_type }}{{ instance.get_attributes }}>
+{% load cms_tags frontend %}<{{ instance.tag_type }}{{ instance.get_attributes }}>
     {% for plugin in instance.child_plugin_instances %}
         {% with parentloop=forloop parent=instance %}{% render_plugin plugin %}{% endwith %}
-    {% empty %}{{ instance.simple_content }}{% endfor %}
+    {% empty %}
+        {% if instance.simple_content %}{{ instance.simple_content }}{% else %}{% user_message _("Add content here") %}{% endif %}
+    {% endfor %}
     </{{ instance.tag_type }}>
diff --git a/djangocms_frontend/templates/djangocms_frontend/user_message.html b/djangocms_frontend/templates/djangocms_frontend/user_message.html
@@ -0,0 +1,5 @@
+{% if message %}
+    <div class="text-center text-black-50 p-5">
+        <i>{{ message }}</i>
+    </div>
+{% endif %}
diff --git a/djangocms_frontend/templatetags/frontend.py b/djangocms_frontend/templatetags/frontend.py
@@ -103,6 +103,15 @@ def framework_info(context, item, as_json=True):
     )
 
 
+@register.inclusion_tag("djangocms_frontend/user_message.html", takes_context=True)
+def user_message(context, message):
+    """Renders a user message"""
+    toolbar = getattr(context.get("request", None), "toolbar", None)
+    if settings.SHOW_EMPTY_CHILDREN and toolbar.edit_mode_active:
+        return {"message": message}
+    return {}
+
+
 class DummyPlugin:
     def __init__(self, nodelist):
         self.nodelist = nodelist
diff --git a/docs/source/components.rst b/docs/source/components.rst
@@ -249,6 +249,51 @@ specified using the ``DJANGOCMS_FRONTEND_CAROUSEL_TEMPLATES`` setting.
     specified the child plugins add to the caption. If no image is specified
     the child plugins make up the slide.
 
+Re-usable component example
+===========================
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "carousel" template="my_template" carousel_controls=True %}
+        {% plugin "carouselslide" %}
+            <h4>Carousel slide title</h4>
+            <p> Some more content...</p>
+        {% endplugin %}
+        {% plugin "carouselslide" %}
+            <h4>Carousel slide title</h4>
+            <p> Some more content...</p>
+        {% endplugin %}
+    {% endplugin %}
+
+Parameters for ``{% plugin "carousel" %}`` are:
+
+* ``template``: The template to use for the carousel. If not specified the
+  default template is used.
+* ``carousel_controls``: If set to ``True`` the carousel will have controls.
+* ``carousel_indicators``: If set to ``True`` the carousel will have indicators.
+* ``carousel_interval``: The interval in milliseconds between slides. If not
+  specified the default interval (5000) is used.
+* ``carousel_pause``: If set to ``hover`` the carousel will pause on hover.
+* ``carousel_wrap``: If set to ``True`` the carousel will wrap around.
+* ``carousel_keyboard``: If set to ``True`` the carousel will react to keyboard
+  events.
+* ``carousel_ride``: If set to ``True`` the carousel will start sliding
+  automatically.
+* ``carousel_aspect_ratio``: The aspect ratio of the carousel. If not specified
+  the default aspect ratio (16:9) is used.
+
+Parameters for ``{% plugin "carouselslide" %}`` are:
+
+* ``carousel_image``: The image to display in the slide. If not specified the
+  slide will be empty.
+* ``carousel_content``: The HTML caption to display in the slide.
+
+
 ******************
 Collapse component
 ******************
@@ -260,6 +305,7 @@ button) to reveal itself.
 Compared to the accordion component the collapse component often is more
 flexible but also requires more detailed styling.
 
+
 .. index::
     single: Jumbotron
 
@@ -484,6 +530,46 @@ Tabs component
     ``DJANGOCMS_FRONTEND_TAB_EFFECTS`` setting.
 
 
+Re-usable component example
+===========================
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "tab" template="my_template" tab_type="nav-pills" tab_align="justify-content-center" %}
+        {% plugin "tabitem" tab_title="Tab 1" tab_bordered=True %}
+            <h4>Content of tab 1</h4>
+            <p> Some content...</p>
+        {% endplugin %}
+        {% plugin "tabitem" tab_title="Tab 2" tab_bordered=True %}
+            <h4>Content of tab 2</h4>
+            <p> Some more content...</p>
+        {% endplugin %}
+    {% endplugin %}
+
+
+Parameters for ``{% plugin "tab" %}`` are:
+
+* ``template``: The template to use for the tabs. If not specified the default
+  template is used.
+* ``tab_type``: The type of the tabs. If not specified the default type is used.
+* ``tab_align``: The alignment of the tabs. If not specified the default alignment
+  is used.
+* ``tab_index``: The index of the initially active tab. If not specified the
+  first tab is active.
+* ``tab_effect``: The effect of the tabs. ``"fade"`` is available. If not
+  specified no effect is used.
+
+Parameters for ``{% plugin "tabitem" %}`` are:
+
+* ``tab_title``: The title of the tab.
+* ``tab_bordered``: If set to ``True`` the tab will have a border.
+
+
 .. index::
     single: Icon
 
diff --git a/docs/source/grid.rst b/docs/source/grid.rst
@@ -112,3 +112,57 @@ content.
     Removed:
         The column type entry has been removed since it was a legacy from
         Bootstrap version 3.
+
+***************************
+Re-usable component example
+***************************
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "gridcontainer" container_type="container-fluid" %}
+        {% plugin "row" vertical_alignment="align-items-center" %}
+            {% plugin "gridcolumn" xs_col=12 md_col=6 text_alignment="center" %}
+                This content is inside a column.
+            {% endplugin %}
+            {% plugin "gridcolumn" xs_col=12 md_col=6 text_alignment="center" %}
+                This content is inside another column.
+            {% endplugin %}
+        {% endplugin %}
+        This content still is inside a container.
+    {% endplugin %}
+
+Parameters for ``{% plugin "gridcontainer" %}`` are:
+
+* ``container_type``: The type of container. Default is ``container``. Other
+    options are ``container-fluid`` and ``container-full``.
+
+Parameters for ``{% plugin "gridrow" %}`` are:
+
+* ``vertical_alignment``: The vertical alignment of the row. Default is
+    ``align-items-start``. Other options are ``align-items-center`` and
+    ``align-items-end``.
+* ``horizontal_alignment``: The horizontal alignment of the row. Default is
+    ``justify-content-start``. Other options are ``justify-content-center``,
+    ``justify-content-end`` and ``justify-content-around``.
+* ``gutters``: Size of gutter between columns. Default is ``3``. Other
+    options are ``0``, ``1``, ``2``, ``4``, ``5``.
+* ``row_cols_xs``: Number of columns on mobile devices.
+* ``row_cols{sm|md|lg|xl|xx}``: Number of columns on larger devices.
+
+
+Parameters for ``{% plugin "gridcolumn" %}`` are:
+* ``column_alignment``: The vertical alignment of the column. Default is
+    ``align-self-start``. Other options are ``align-self-center`` and
+    ``align-self-end``.
+* ``text_alignment``: The text alignment of the column. Options are
+    ``left``, ``center`` and ``right``.
+* ``xs_col``: Number of columns on mobile devices.
+* ``{sm|md|lg|xl|xx}_col``: Number of columns on larger devices.
+
+
+
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
@@ -1,10 +1,10 @@
-###########
- Reference
-###########
+#########
+Reference
+#########
 
-**********
- Settings
-**********
+********
+Settings
+********
 
 **djangocms-frontend** can be configured by putting the appropriate settings
 in your project's ``settings.py``.
@@ -319,6 +319,15 @@ in your project's ``settings.py``.
 
     This lost of options define the icon size choices a user can select. The values (first tuple element) are css units for the ``font-size`` css property. Besides relative units (``%``) any css unit can be used, e.g. ``112pt``.
 
+.. py:attribute:: settings.DJANGOCMS_FRONTEND_SHOW_EMPTY_CHILDREN
+
+    Default: ``False``
+
+    If set to ``True`` the frontend editing will show a message where children
+    can be added to plugins to complete the design. This is supposed to make
+    the editing experience more intuitive for editors.
+
+
 ******
 Models
 ******
@@ -393,9 +402,9 @@ Models
     returns a plugin-specific short description shown in the structure mode
     of django CMS.
 
-**************
- Form widgets
-**************
+************
+Form widgets
+************
 
 **djangocms-frontend** contains button group widgets which can be used as
 for ``forms.ChoiceField``. They might turn out helpful when adding custom
@@ -449,13 +458,9 @@ plugins.
     This form field is identical to the ``OptionalDeviceChoiceField`` above,
     but requires the user to select at least one device.
 
-
-
-
-
-*********************
- Management commands
-*********************
+*******************
+Management commands
+*******************
 
 Management commands are run by typing ``./manage.py frontend command`` in the
 project directory. ``command`` can be one of the following:
@@ -484,9 +489,9 @@ project directory. ``command`` can be one of the following:
     then syncing the new permission with these commands.
 
 
-***************
- Running Tests
-***************
+*************
+Running Tests
+*************
 
 You can run tests by executing:
 

Original file line number	Diff line number	Diff line change
`@@ -72,6 +72,8 @@`
`72`	`72`	`],`
`73`	`73`	`)`
`74`	`74`
	`75`	`+SHOW_EMPTY_CHILDREN = getattr(django_settings, "DJANGOCMS_FRONTEND_SHOW_EMPTY_CHILDREN", False)`
	`76`	`+`
`75`	`77`	`FORM_OPTIONS = getattr(django_settings, "DJANGOCMS_FRONTEND_FORM_OPTIONS", {})`
`76`	`78`
`77`	`79`