Nov 03

Extend and Export OctoberCMS theme settings

Themes are very powerful in OctoberCMS. OctoberCMS let you add your custom theme-related settings and save them to the database. It's good so far but when you want to export theme, those settings sadlyare not going to present in files`.

So, if you install exported theme on another website you will miss all of your settings.

themes\THEME_NAME\theme.yaml Theme properties are key => value pair in yaml file. you can say its file based database.

However, it's not possible to directly add and configure new items there.

To overcome this issue we have one trick. we will use OctoberCMS's powerful event system to extend theme properties and `add our own properties which will be present in exports.

Let's start extending our theme. (You need one plugin where we add our event code in boot method)
<?php namespace Hardiksatasiya\So;

use System\Classes\PluginBase;
// ...

class Plugin extends PluginBase
  public function boot() {
    \Event::listen('backend.form.extendFieldsBefore', function ($formWidget) {
      // if its not theme modal do not proceed
      if (!$formWidget->model instanceof \Cms\Classes\Theme) {

      // Here you can't use addFields() because it will throw you an exception because the form is not yet created
      // and it does not have tabs and fields

      // add  navigation_text field
      $formWidget->fields['navigation_text'] = [
          'label' => 'Navigation Text',
          'comment' => 'Site should show navigation text on navigation menu.',
          'span' => 'left'


      // add another primary_color field
      $formWidget->fields['primary_color'] = [
          'label' => 'Primary Color',
          'comment' => 'Select theme primary color.',
          'type' => 'colorpicker',
          'span' => 'right'
  // ...
Here we are adding 2 new fields navigation_text and primary_color these are form fields you can modify as per your like.
check out our new fields.


let's see, how they will look like inside the theme properties edit form.


Now, When we import this theme to another website we do not lose these settings Nice !.

So far we can save our settings to the themes\THEME_NAME\theme.yaml file. Now it's time to get them back and use them in our code. it's rather very easy.

Your themes\THEME_NAME\theme.yaml file will look like this.
navigation_text: 'My website navigation' # <-- new field
primary_color: '#2ecc71'                 # <-- new field
name: Demo
description: 'Some description.'
author: OctoberCMS
homepage: ''
code: 'hardik.satasiya'
How to use saved theme configuration.
use Cms\Classes\Theme;

// get your current active theme  
$theme = Theme::getActiveTheme();

// get your config value
$navigationText = $theme->getConfigValue('navigation_text', 'Default value');
$primaryColor = $theme->getConfigValue('primary_color', '#fff');

// $navigationText => 'My website navigation'
// $primaryColor => '#2ecc71'

In this way, you will never lose your theme configuration settings while exporting the theme and you can easily get them back once you import your theme.

Please share this article if you like it. Thanks !!