2. Creating a theme

There are two equivalent ways to define a theme. You may pick the one that suits better to you.

A) Configure a theme with a theme.json file

Tip: You should use theme:create command to create a theme. These are the manual steps:

Into the root of your views path create a new folder and then place a theme.json file inside with some configuration:

{
  "name"        : "THEME_NAME",
  "asset-path"  : "ASSET_PATH",
  "extends"     : "PARENT_THEME"
}

Important notes:

• THEME_NAME is the name of your theme. Can be any string.
• ASSET_PATH is relative to public path. You should create this folder too!
• PARENT_THEME is the name of the parent theme. Set it to null if this is a stand-alone theme
• You can add any additionaly configuration into the json file. You may access to your own settings with Theme:getSetting('key') & Theme:setSetting('key','value') at runtime.
• Why we don't set the views path? Because it is the current path! Just rename current folder and all will work fine.

B) Configure a theme within the config/themes.php file

You may want to override previous settings (or define a new theme) into your config/themes.php. Just add your theme into the themes array. The format for every theme is very simple:

// Select a name for your theme
'theme-name' => [

    /*
    |--------------------------------------------------------------------------
    | Theme to extend. Defaults to null (=none)
    |--------------------------------------------------------------------------
    */
    'extends'       => 'theme-to-extend',

    /*
    |--------------------------------------------------------------------------
    | The path where the view are stored. Defaults to 'theme-name' 
    | It is relative to 'themes_path' ('/resources/views' by default)
    |--------------------------------------------------------------------------
    */
    'views-path'    => 'path-to-views',
    
    /*
    |--------------------------------------------------------------------------
    | The path where the assets are stored. Defaults to 'theme-name' 
    | It is relative to laravels public folder (/public)
    |--------------------------------------------------------------------------
    */
    'asset-path'    => 'path-to-assets',

    /*
    |--------------------------------------------------------------------------
    | Custom configuration. You can add your own custom keys.
    | Use Theme::getSetting('key') & Theme::setSetting('key', 'value') to access them
    |--------------------------------------------------------------------------
    */
    'key'           => 'value', 
],

all settings are optional and can be omitted. Check the example in the configuration file...

Implicit Theme decleration

Defining a theme is completely optional.

You may not create a configuration file as long as the defaults fits you! If a theme has not been registered at all then the default values will be used when you activate it.

For example if you Theme::set('my-theme') and you haven't created a theme.json file, nor declared 'my-theme' at the config\themes.php file, then the default locations will be assumed:

• views = THEMES_ROOT_PATH/my-theme
• assets = public/my-theme

Custom configuration settings

You can add your own configuration into a theme (either into the theme.json file or into the config/themes.php).

This is an example theme.json with added configuration:

{
  "name"        : "myTheme",
  "asset-path"  : "myTheme",
  "views-path"  : "myTheme",
  "extends"     : null,
  "thumbs-size"  : 150,
  "sidebar-position" : "right"
}

You can access these settings at runtime with:

Theme::getSetting('key','default'); // read current theme's configuration value for 'key'
Theme::setSetting('key','value');    // assign a key-value pair to current theme's configuration

Cache Settings

Warning: Theme settings are cached for faster loading times. If you change any setting you should refresh the cache in order to take effect. Check artisan command Refresh Cache. You can disable caching on config\themes.php