From e9e3b313206ca9c357bf17a734e3bb573c5bf42e Mon Sep 17 00:00:00 2001 From: Marc Jauvin Date: Sat, 6 Dec 2025 10:52:48 -0500 Subject: [PATCH 1/4] document optgroup for backend forms dropdown field --- backend/forms.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/backend/forms.md b/backend/forms.md index 96a1e73e..e46e1fd9 100644 --- a/backend/forms.md +++ b/backend/forms.md @@ -440,6 +440,26 @@ status_type: draft: [Draft, icon-clock-o] ``` +#### Add option grouping (optgroup) to dropdown options + +In order to add option grouping, use a multidimensional array like below: + +```yaml +status_type: + type: dropdown + label: Blog Post Status + options: + Group1: + opt1: Option 1 + opt2: Option 2 + opt3: Option 3 + Group2: + opt4: Option 4 + opt5: [Option 5, icon-check-circle] + opt6: Option 6 +``` +>**NOTE:** individual items in the groups can also use icons or images as shown in "Option 5" above. + To define the behavior when there is no selection, you may specify an `emptyOption` value to include an empty option that can be reselected. ```yaml From a258d1e7d5d13267e6823c8d314a3c0266a1a48d Mon Sep 17 00:00:00 2001 From: Marc Jauvin Date: Sat, 6 Dec 2025 10:58:04 -0500 Subject: [PATCH 2/4] add missing empty line after code block --- backend/forms.md | 1 + 1 file changed, 1 insertion(+) diff --git a/backend/forms.md b/backend/forms.md index e46e1fd9..090b7bf4 100644 --- a/backend/forms.md +++ b/backend/forms.md @@ -458,6 +458,7 @@ status_type: opt5: [Option 5, icon-check-circle] opt6: Option 6 ``` + >**NOTE:** individual items in the groups can also use icons or images as shown in "Option 5" above. To define the behavior when there is no selection, you may specify an `emptyOption` value to include an empty option that can be reselected. From f4101c1d89a940c6bdf9bc3c9e5447d27541a298 Mon Sep 17 00:00:00 2001 From: Marc Jauvin Date: Sat, 6 Dec 2025 11:02:05 -0500 Subject: [PATCH 3/4] add missing space around lists --- cms/themes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cms/themes.md b/cms/themes.md index 234eb6b0..71c98e9f 100644 --- a/cms/themes.md +++ b/cms/themes.md @@ -307,6 +307,7 @@ themes/ ``` In this example, when `my-custom-theme` is active: + - `theme.css` and `logo.png` load from the child theme - `header.htm` loads from the child theme - `footer.htm` loads from the parent theme (inherited) @@ -349,6 +350,7 @@ When [database templates](#database-driven-themes) are enabled, you can: 3. Inherit all other files from the parent theme's filesystem This approach allows you to: + - Manage hundreds of similar themes without duplicating files - Update the parent theme and have changes cascade to all child themes automatically - Store tenant-specific customizations in the database while sharing a common codebase @@ -375,23 +377,27 @@ The child theme will now function without any physical directory, inheriting eve ### Best Practices **When to use child themes:** + - Customizing a third-party theme while preserving the ability to update it - Creating multiple branded variations of a base theme - Building a multi-tenant application where each tenant needs minor customizations - Developing a theme framework where a base theme provides core functionality **When to create a new theme instead:** + - Making extensive changes that affect most templates and assets - Building something significantly different from the original design - When you need to modify the theme structure itself **Organization tips:** + - Keep child themes minimal - only override what's necessary - Document which files are overridden and why - Use clear, descriptive names for child themes (e.g., `mytheme-client-a`, `mytheme-blue-variant`) - Consider using [theme customization](../themes/development#theme-customization) for simple configuration changes before creating a child theme **Performance considerations:** + - Child themes have minimal performance impact - file resolution is cached - Avoid deep nesting (grandparent/parent/child) - only one level of inheritance is supported - Database-driven templates are cached, so virtual child themes perform well From e9f02ba098776b0636ca6e9ab30bca14a560e81e Mon Sep 17 00:00:00 2001 From: Marc Jauvin Date: Sat, 6 Dec 2025 11:27:53 -0500 Subject: [PATCH 4/4] fix lint issues --- cms/themes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cms/themes.md b/cms/themes.md index 71c98e9f..5ff675b5 100644 --- a/cms/themes.md +++ b/cms/themes.md @@ -355,7 +355,7 @@ This approach allows you to: - Update the parent theme and have changes cascade to all child themes automatically - Store tenant-specific customizations in the database while sharing a common codebase -**Example: Creating a virtual child theme** +**Example:** Creating a virtual child theme 1. Enable database templates in `config/cms.php`: @@ -363,14 +363,14 @@ This approach allows you to: 'databaseTemplates' => true, ``` -2. Create a theme record in the database with just the `theme.yaml` content: +1. Create a theme record in the database with just the `theme.yaml` content: ```yaml name: "Client A Custom Theme" parent: base-theme ``` -3. Customize only the templates that need to differ from the parent by saving them to the database +1. Customize only the templates that need to differ from the parent by saving them to the database The child theme will now function without any physical directory, inheriting everything from `themes/base-theme` except for the database-stored customizations.