✨(plugins) added grid columns and gutter option to section plugin

The plugin 'section' now has grid options to apply grid column rules
to its children contents. The grid define the column sizes rules
and a gutter.

Also this bring two new Makefile tasks to help with pending
migrations.

CHANGELOG.md

@@ -8,6 +8,10 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unrealeased]
 
+### Added
+
+- Grid options for the Section plugin
+
 ## [2.30.0] - 2024-10-16
 
 ### Added

Makefile

@@ -243,6 +243,18 @@ migrate: ## perform database migrations
 	@$(MANAGE) migrate
 .PHONY: migrate
 
+migrations: ## create all pending migrations
+	@echo "Start and wait for ${DB_HOST} to be up..."
+	@$(COMPOSE_UP_WAIT) -d ${DB_HOST}
+	@$(MANAGE) makemigrations -v 3
+.PHONY: migrations
+
+check-migrations: ## check if there is pending migrations to create
+	@echo "Start and wait for ${DB_HOST} to be up..."
+	@$(COMPOSE_UP_WAIT) -d ${DB_HOST}
+	@$(MANAGE) makemigrations --check --dry-run -v 3
+.PHONY: check
+
 search-index: ## (re)generate the Elasticsearch index
 	@echo "Start and wait for ${DB_HOST} & elasticsearch to be up..."
 	@$(COMPOSE_UP_WAIT) -d ${DB_HOST} elasticsearch

UPGRADE.md

@@ -16,6 +16,33 @@ $ make migrate
 
 ## Unreleased
 
+- Add new `r-section-grid-sizes` variable
+```
+  $r-section-grid-sizes: (
+    '50x50': 1fr 1fr,
+    '33x33x33': 1fr 1fr 1fr,
+    '25x75': 25% 2fr,
+    '75x25': 2fr 25%,
+  );
+```
+- Add new `r-section-grid-gutters` variable
+```
+  $r-section-grid-gutters: (
+    'sm': 0.5rem,
+    'xl': 1rem,
+  );
+```
+- There is a new setting that can be used to define custom column sizes for Section
+```
+    RICHIE_SECTION_GRID_COLUMNS = [
+        ("", _("None")),
+        ("33x33x33", _("Three columns: (33% | 33% | 33%)")),
+        ("50x50", _("Two columns: (50% | 50%)")),
+        ("25x75", _("Two columns: (25% | 75%)")),
+        ("75x25", _("Two columns: (75% | 25%)")),
+    ]
+```
+
 ## 2.25-beta.0 to 2.30.0
 
 - Add new `compacted-banner` theme scheme

src/frontend/scss/components/templates/richie/section/_section.scss

@@ -1,3 +1,6 @@
+$r-section-grid-sizes: () !default;
+$r-section-grid-gutters: () !default;
+
 section {
   // Ensure caesura always takes full width with some space around
   // within flex grid
@@ -70,6 +73,9 @@ section {
       }
     }
   }
+
+  // Enable CSS grid
+  @include m-o-grid($r-section-grid-sizes, $r-section-grid-gutters);
 }
 
 //
@@ -127,6 +133,9 @@ section {
     }
   }
 
+  // Enable CSS grid
+  @include m-o-grid($r-section-grid-sizes, $r-section-grid-gutters);
+
   .category-glimpse {
     @include sv-flex(1, 0, calc(15% - 1rem));
     max-width: none;

src/frontend/scss/settings/_variables.scss

@@ -165,3 +165,20 @@ $r-search-filters-gutter: 0.2rem !default;
 $r-ease-in: cubic-bezier(0.5, 0, 0.75, 0) !default;
 $r-ease-out: cubic-bezier(0.25, 1, 0.5, 1) !default;
 $r-ease-in-out: cubic-bezier(0.76, 0, 0.24, 1) !default;
+
+// Define the grid column template for Section grid
+// Each item will be a variant to allow on grid
+$r-section-grid-sizes: (
+  '50x50': 1fr 1fr,
+  '33x33x33': 1fr 1fr 1fr,
+  '25x75': 25% 2fr,
+  '75x25': 2fr 25%,
+);
+
+// Define gutter size to apply on Section grid
+// Each item is a breakpoint where to apply the gutter, breakpoint 'sm' is used as
+// the default gutter size for minimal breakpoint if defined
+$r-section-grid-gutters: (
+  'sm': 0.5rem,
+  'xl': 1rem,
+);

src/frontend/scss/tools/_grids.scss

@@ -0,0 +1,50 @@
+// Basic CSS grid
+
+// Define CSS grid rules for content
+@mixin m-o-grid($grid-sizes, $grid-gutters) {
+  // CSS grid definition
+  &__grid {
+    display: grid;
+    grid-template-columns: 100%;
+
+    // Neutralize and adapt some rules that for content items that can define some
+    // rules which conflict with expected section grid behaviors
+    & > * {
+      min-width: auto !important;
+      max-width: none !important;
+    }
+
+    // Adjust button caesura
+    & > .button-caesura {
+      display: block;
+    }
+
+    // Enable column size only for large screen and up
+    @include media-breakpoint-up(lg) {
+      @each $key, $value in $r-section-grid-sizes {
+        &--#{$key} {
+          grid-template-columns: $value;
+        }
+      }
+    }
+
+    // Variants with a gutter between content items
+    &--with-gutter {
+      @if map-get($r-section-grid-gutters, 'sm') {
+        column-gap: map-get($r-section-grid-gutters, 'sm');
+        row-gap: map-get($r-section-grid-gutters, 'sm');
+      }
+      @each $key, $value in $r-section-grid-gutters {
+        @include media-breakpoint-up($key) {
+          column-gap: $value;
+          row-gap: $value;
+        }
+      }
+
+      // Disable contents margin in profit of grid gutter
+      & > * {
+        margin: 0 !important;
+      }
+    }
+  }
+}

src/frontend/scss/tools/_index.scss

@@ -7,6 +7,7 @@
 @import './empty';
 @import './features';
 @import './flexbox';
+@import './grids';
 @import './hero';
 @import './keyframes';
 @import './list-group';

src/richie/apps/core/templates/richie/styleguide/index.html

@@ -13,7 +13,6 @@ <h1 class="display-2">Styleguide</h1>
         </div>
     </div>
 
-
     <div class="pt-4 pb-4">
         <div class="container mt-4 text-center">
             <h2 class="display-3 p-4">Typography</h2>

src/richie/plugins/section/cms_plugins.py

@@ -23,7 +23,20 @@ class SectionPlugin(CMSPluginBase):
     allow_children = True
     cache = True
     form = SectionForm
-    fieldsets = ((None, {"fields": ["title", "template", "attributes"]}),)
+    fieldsets = (
+        (
+            None,
+            {
+                "fields": [
+                    "title",
+                    "template",
+                    "attributes",
+                    "grid_columns",
+                    "grid_gutter",
+                ]
+            },
+        ),
+    )
     model = Section
     module = PLUGINS_GROUP
     name = _("Section")

src/richie/plugins/section/defaults.py

@@ -20,3 +20,16 @@
         ("richie/section/section_tiles.html", _("Item tiles")),
     ],
 )
+
+
+SECTION_GRID_COLUMNS = getattr(
+    settings,
+    "RICHIE_SECTION_GRID_COLUMNS",
+    [
+        ("", _("None")),
+        ("33x33x33", _("Three columns: (33% | 33% | 33%)")),
+        ("50x50", _("Two columns: (50% | 50%)")),
+        ("25x75", _("Two columns: (25% | 75%)")),
+        ("75x25", _("Two columns: (75% | 25%)")),
+    ],
+)

src/richie/plugins/section/forms.py

@@ -31,4 +31,6 @@ class Meta:
             "title",
             "template",
             "attributes",
+            "grid_columns",
+            "grid_gutter",
         }

src/richie/plugins/section/migrations/0007_add_section_grid_columns_and_more.py

@@ -0,0 +1,52 @@
+# Generated by Django 4.2.16 on 2024-10-11 21:01
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+from ..defaults import SECTION_GRID_COLUMNS
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("cms", "0022_auto_20180620_1551"),
+        ("section", "0006_add_attributes_field"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="section",
+            name="grid_columns",
+            field=models.CharField(
+                blank=True,
+                choices=SECTION_GRID_COLUMNS,
+                default="",
+                help_text="Define a Grid to use for contents, when no Grid is enable each content can define its own width.",
+                max_length=50,
+                verbose_name="Grid",
+            ),
+        ),
+        migrations.AddField(
+            model_name="section",
+            name="grid_gutter",
+            field=models.BooleanField(
+                blank=True,
+                default=True,
+                help_text="Enable a gutter between content items when Grid is enabled.",
+                verbose_name="Grid gutter",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="section",
+            name="cmsplugin_ptr",
+            field=models.OneToOneField(
+                auto_created=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                parent_link=True,
+                primary_key=True,
+                related_name="%(app_label)s_%(class)s",
+                serialize=False,
+                to="cms.cmsplugin",
+            ),
+        ),
+    ]

src/richie/plugins/section/models.py

@@ -9,7 +9,7 @@
 from cms.models.pluginmodel import CMSPlugin
 from djangocms_attributes_field.fields import AttributesField
 
-from .defaults import SECTION_TEMPLATES
+from .defaults import SECTION_GRID_COLUMNS, SECTION_TEMPLATES
 
 
 class Section(CMSPlugin):
@@ -34,6 +34,23 @@ class Section(CMSPlugin):
         blank=True,
         excluded_keys=["href", "target"],
     )
+    grid_columns = models.CharField(
+        _("Grid"),
+        max_length=50,
+        blank=True,
+        choices=SECTION_GRID_COLUMNS,
+        default="",
+        help_text=_(
+            "Define a Grid to use for contents, when no Grid is enable each content "
+            "can define its own width."
+        ),
+    )
+    grid_gutter = models.BooleanField(
+        verbose_name=_("Grid gutter"),
+        default=True,
+        blank=True,
+        help_text=_("Enable a gutter between content items when Grid is enabled."),
+    )
 
     def __str__(self):
         return Truncator(self.title).words(6, truncate="...")

src/richie/plugins/section/templates/richie/section/section.html

@@ -7,7 +7,7 @@
                 {{ instance.title|safe }}
             </h{{ header_level|default:2 }}>
         {% endif %}
-        <div class="section__items">
+        <div class="{% if instance.grid_columns %}section__grid section__grid--{{ instance.grid_columns }}{% if instance.grid_gutter %} section__grid--with-gutter{% endif %}{% else %}section__items{% endif %}">
             {% for plugin in instance.child_plugin_instances %}
                 {% with header_level=3 %}
                     {% render_plugin plugin %}

src/richie/plugins/section/templates/richie/section/section_tiles.html

@@ -5,7 +5,7 @@
         {% if instance.title %}
             <h{{ header_level|default:2 }} class="section-tiles__title">{{ instance.title|safe }}</h{{ header_level|default:2 }}>
         {% endif %}
-        <div class="section-tiles__items">
+        <div class="{% if instance.grid_columns %}section-tiles__grid section-tiles__grid--{{ instance.grid_columns }}{% if instance.grid_gutter %} section-tiles__grid--with-gutter{% endif %}{% else %}section-tiles__items{% endif %}">
         {% for plugin in instance.child_plugin_instances %}
             {% with category_variant="glimpse" %}
                 {% render_plugin plugin %}