Themes

Inheritance

Themes can extend each other with the method getExtends(): string of their main class.

Parent themes will be installed automatically when installing a theme in the backend, just make sure they are required in the composer.json of the child theme.

Assets

Assets (images, fonts etc) can be inherited through the twig function theme_url.

If you have an image.jpg defined in your theme in the images folder, you can publish it with theme_url('images/image.jpg')

If you require an asset and the file is not present in your theme, it will look in the parent theme (if defined).

This inheritance can be disabled with the property $inheritsAssets of your theme class.

Partial themes

Define a partial theme with the method isPartial(): bool of the plugin class.

Regions

Regions are defined in the defineRegions(): array method of the themes, by default this returns null which means the regions will be inherited from the parent theme.

The method must return this structure :

[
    [
        'handle' => 'region1-handle',
        'name' => 'Region 1',
        'width' => '100%'
    ],
    [
        'handle' => 'region2-handle',
        'name' => 'Region 2',
        'width' => '100%'
    ]
]

Where width will be used to render the region in the control panel blocks page.

Creating a new Theme

Create a new plugin (following the Craft documentation), its main class must extend Ryssbowh\CraftThemes\base\ThemePlugin.

You could for example create a themes folder at the root, and add it as a composer repository by adding to the root composer.json :

"repositories": [{
    "type": "path",
    "url": "themes/*",
    "options": {
        "symlink": true
    }
}]

Or you could use the creator command: craft themes/create/theme name handle [namespace] [className] [folder=themes]. You would still need to modify your root composer.json to reference the folder passed to that command.

You can then require your theme as any other package.

Asset Bundles

Asset bundles can be defined in your theme class, in the $assetBundles property, it's an array indexed by the url path :

[
    '*' => [
        CommonAssets::class
    ],
    'blog' => [
        BlogAssets::class
    ],
    '/^blog*$/' => [
        BlogAssets::class
    ],
    '/' => [
        HomeAssets::class
    ]
]

Bundle assets will be registered automatically on the view if this theme is loaded for that url, the '*' array will be registered on every request.

By default, parent theme bundles will also be registered. This can be disabled with the property $inheritsAssetBundles of your theme class.

Setting theme manually

You can set a theme manually on the theme registry : Themes::$plugin->registry->setCurrent('theme-handle'). Because Template roots can only be registered once on Craft, you must do this before the View template roots are registered for the mode site (View::TEMPLATE_MODE_SITE) or an exception will be thrown.

Theme preferences

Each Theme can define default classes and attributes for each layout/block/field/file/group/region by defining a preference class

To override the preferences for your theme, override the method getPreferencesModel(): ThemePreferencesInterface of its main class.