Merge branch '1.2' into develop

Author: LukeTowers

cms/themes.md

@@ -196,3 +196,219 @@ Winter CMS comes with another very useful feature, disabled by default, called D
 Files modified in the database are cached to indicate that they should be loaded from the database.
 
 > **NOTE:** All CMS template objects (ex. `Layout`, `Page`, `Content`, `Partial`, `Meta`, etc) are stored in the database when this feature is enabled and a change is made to the template in question; however theme asset files will **not** be.
+
+## Child Themes
+
+Child themes allow you to create a new theme that inherits templates and assets from a "parent" theme. This is useful when you want to customize an existing theme without modifying the original files, create variations of a base theme, or manage multiple similar themes for different clients or tenants.
+
+When using a child theme, you can override specific pages, partials, layouts, content files, or assets from the parent theme by creating files with the same path in your child theme. Any files not present in the child theme will automatically fall back to the parent theme.
+
+### Configuring a Child Theme
+
+To create a child theme, specify the parent theme's directory name using the `parent` key in your child theme's `theme.yaml` file:
+
+```yaml
+name: "My Custom Theme"
+description: "A customized version of the Demo theme"
+author: "Your Name"
+homepage: "https://example.com"
+parent: demo
+```
+
+The value of `parent` should be the directory name of the parent theme (e.g., if the parent theme is located at `themes/demo`, use `demo` as the parent value).
+
+> **NOTE:** See the [Theme information file](../themes/development#theme-information-file) documentation for more details on configuring the `parent` option.
+
+### Creating a Child Theme
+
+The minimal requirement for a child theme is a `theme.yaml` file that specifies a parent theme. Here's how to create a basic child theme:
+
+**Step 1:** Create a new theme directory:
+
+```treeview
+themes/
+|-- demo/                   # Parent theme
+`-- my-custom-theme/        # Child theme
+    `-- theme.yaml
+```
+
+**Step 2:** Define the parent in `themes/my-custom-theme/theme.yaml`:
+
+```yaml
+name: "My Custom Theme"
+parent: demo
+```
+
+At this point, your child theme will function identically to the parent theme, as it inherits all templates and assets.
+
+**Step 3:** Override specific files as needed. For example, to customize the homepage:
+
+```treeview
+themes/
+|-- demo/
+|   |-- pages/
+|   |   `-- home.htm        # Parent's homepage
+|   `-- theme.yaml
+`-- my-custom-theme/
+    |-- pages/
+    |   `-- home.htm        # Child's customized homepage
+    `-- theme.yaml
+```
+
+When the child theme is active, Winter will use `my-custom-theme/pages/home.htm` instead of `demo/pages/home.htm`, while all other pages from the parent theme remain available.
+
+### Inheritance Behavior
+
+Child themes use a cascading file resolution system. When Winter needs to load a template or asset, it searches in the following order:
+
+1. Child theme database templates (if [database templates](#database-driven-themes) are enabled)
+2. Child theme filesystem
+3. Parent theme database templates (if database templates are enabled)
+4. Parent theme filesystem
+
+This means:
+
+- **Templates** (pages, partials, layouts, content files) in the child theme override those in the parent theme when they have the same path
+- **Assets** (CSS, JavaScript, images, fonts) in the child theme override those in the parent theme when they have the same path
+- **Localization strings** from the child theme's `lang` directory override parent theme strings
+- Any file not present in the child theme falls back to the parent theme
+
+#### Example Directory Structure
+
+Here's an example showing a child theme that overrides specific files:
+
+```treeview
+themes/
+|-- demo/                           # Parent theme
+|   |-- assets/
+|   |   |-- css/
+|   |   |   `-- theme.css           # Parent CSS
+|   |   `-- images/
+|   |       `-- logo.png            # Parent logo
+|   |-- layouts/
+|   |   `-- default.htm             # Parent layout
+|   |-- pages/
+|   |   |-- home.htm                # Parent homepage
+|   |   `-- about.htm               # Parent about page
+|   |-- partials/
+|   |   |-- header.htm              # Parent header
+|   |   `-- footer.htm              # Parent footer
+|   `-- theme.yaml
+|
+`-- my-custom-theme/                # Child theme
+    |-- assets/
+    |   |-- css/
+    |   |   `-- theme.css           # OVERRIDES parent CSS
+    |   `-- images/
+    |       `-- logo.png            # OVERRIDES parent logo
+    |-- partials/
+    |   `-- header.htm              # OVERRIDES parent header
+    `-- theme.yaml                  # Specifies parent: demo
+```
+
+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)
+- `default.htm` layout loads from the parent theme (inherited)
+- Both `home.htm` and `about.htm` pages load from the parent theme (inherited)
+
+### Asset Management
+
+Assets in child themes work with the same fallback mechanism as templates. When referencing assets using the `theme.assetUrl()` helper or the `| theme` filter, Winter will check the child theme first, then fall back to the parent theme if the asset doesn't exist.
+
+#### Example: Asset References
+
+In your templates:
+
+```twig
+{# This will use child theme's logo if it exists, otherwise parent's logo #}
+<img src="{{ 'assets/images/logo.png' | theme }}" alt="Logo">
+
+{# CSS files cascade the same way #}
+<link href="{{ 'assets/css/theme.css' | theme }}" rel="stylesheet">
+```
+
+#### Asset Compilation
+
+When using the [asset combiner](../markup/filter/theme#combiner-aliases), child theme assets are resolved first:
+
+```twig
+{# If custom.css exists in child theme, it will be used; otherwise parent's version #}
+<link href="{{ ['assets/css/theme.css', 'assets/css/custom.css'] | theme }}" rel="stylesheet">
+```
+
+### Database-Driven Child Themes
+
+Child themes can be purely virtual, meaning they don't require a physical directory on the filesystem. This is particularly useful for multi-tenant applications where each tenant needs a customized theme.
+
+When [database templates](#database-driven-themes) are enabled, you can:
+
+1. Create a database-only record for the child theme with a `theme.yaml` file specifying the parent
+2. Store all template customizations in the database
+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
+
+**Example: Creating a virtual child theme**
+
+1. Enable database templates in `config/cms.php`:
+
+```php
+'databaseTemplates' => true,
+```
+
+2. 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
+
+The child theme will now function without any physical directory, inheriting everything from `themes/base-theme` except for the database-stored customizations.
+
+### 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
+
+### Updating Parent Themes
+
+When updating a parent theme, child themes automatically inherit the changes for any files they haven't overridden. This means:
+
+- Bug fixes and improvements in the parent theme benefit all child themes
+- New templates added to the parent theme become available to child themes
+- Breaking changes in parent templates that are overridden in the child theme won't affect the child theme
+
+To update a parent theme safely:
+
+1. Test the parent theme update in a development environment
+2. Check if any overridden templates in child themes are affected by parent theme changes
+3. Update child theme overrides if necessary to maintain compatibility
+4. Deploy the parent theme update
+
+> **NOTE:** Child themes only support one level of inheritance. A child theme cannot specify another child theme as its parent.

themes/development.md

@@ -22,6 +22,7 @@ Field | Description
 `description` | the theme description, required.
 `previewImage` | custom preview image, path relative to the theme directory, eg: `assets/images/preview.png`, optional.
 `code` | the theme code, optional. The value is used on the Winter CMS marketplace for initializing the theme code value. If the theme code is not provided, the theme directory name will be used as a code. When a theme is installed from the Marketplace, the code is used as the new theme directory name.
+`parent` | the directory name of a parent theme to inherit from, used for [child themes](../cms/themes#child-themes), optional.
 `form` | a configuration array or reference to a form field definition file, used for [theme customization](#theme-customization), optional.
 `require` | an array of plugin names used for [theme dependencies](#theme-dependencies), optional.
 `mix` | an object that defines Mix packages contained in your theme for [asset compilation](../console/asset-compilation).