Backend

At some point you probably want to make your custom plugin for October CMS configurable and allow backend users to make changes within the plugin space. October CMS has a simple and intuitive backend navigation, which you can easily extend in no-time. Let’s assume you have a custom plugin that calls an external API. Here is how you can store API credentials by using the Settings Manager.

First of all, you must register the settings in your Plugin.php file.

<?php namespace Playground\Sandbox;

use System\Classes\PluginBase;
use System\Classes\SettingsManager;

class Plugin extends PluginBase
{

    /**
     * Register Settings
     *
     * @return array
     */
    public function registerSettings()
    {
        return [
            'settings' => [
                'label'       => 'playground.sandbox::lang.settings.label',
                'description' => 'playground.sandbox::lang.settings.description',
                'icon'        => 'icon-flask',
                'category'    => SettingsManager::CATEGORY_SYSTEM,
                'class'       => 'Playground\Sandbox\Models\Settings',
                'keywords'    => 'playground sandbox other keyswords',
            ]
        ];
    }
}

<?php namespace Playground\Sandbox;

use System\Classes\PluginBase;

use System\Classes\SettingsManager;

class Plugin extends PluginBase

{

/**

* Register Settings

* @return array

public function registerSettings()

{

return [

'settings' => [

'label' => 'playground.sandbox::lang.settings.label',

'description' => 'playground.sandbox::lang.settings.description',

'icon' => 'icon-flask',

'category' => SettingsManager::CATEGORY_SYSTEM,

'class' => 'Playground\Sandbox\Models\Settings',

'keywords' => 'playground sandbox other keyswords',

]

];

}

After that you must create a Settings.php file with the following content inside your models folder.

<?php namespace Playground\Sandbox\Models;

use Model;

/**
 * Class Settings
 * @package Playground\Sandbox\Models
 */
class Settings extends Model
{
    /**
     * @var array
     */
    public $implement = ['System.Behaviors.SettingsModel'];

    /**
     * @var string
     */
    public $settingsCode = 'playground_sandbox_settings';

    /**
     * @var string
     */
    public $settingsFields = 'fields.yaml';

    // Set defaults
    public function initSettingsData()
    {
        $this->enabled = 0;
        $this->api_key = '';
    }
}

<?php namespace Playground\Sandbox\Models;

use Model;

/**

* Class Settings

* @package Playground\Sandbox\Models

class Settings extends Model

{

/**

* @var array

public $implement = ['System.Behaviors.SettingsModel'];

/**

* @var string

public $settingsCode = 'playground_sandbox_settings';

/**

* @var string

public $settingsFields = 'fields.yaml';

// Set defaults

public function initSettingsData()

{

$this->enabled = 0;

$this->api_key = '';

}

If you define default values inside the method initSettingsData, make sure the above fields match with the definitions inside the fields.yaml file.

tabs:
    fields:
        enabled:
            label: playground.sandbox::lang.settings.enabled
            comment: playground.sandbox::lang.settings.enabled_comment
            tab: playground.sandbox::lang.settings.tab_default
            type: checkbox
        api_key:
            label: playground.sandbox::lang.settings.api_key
            comment: playground.sandbox::lang.settings.api_key_comment
            tab: playground.sandbox::lang.settings.tab_default
            type: text

tabs:

fields:

enabled:

label: playground.sandbox::lang.settings.enabled

comment: playground.sandbox::lang.settings.enabled_comment

tab: playground.sandbox::lang.settings.tab_default

type: checkbox

api_key:

label: playground.sandbox::lang.settings.api_key

comment: playground.sandbox::lang.settings.api_key_comment

tab: playground.sandbox::lang.settings.tab_default

type: text

Once the fields.yaml file is created, you should see a new form within the new tab.

Now you can access the settings values within your controller, console or component by implementing the following model.

use Playground\Sandbox\Models\Settings;

1	use Playground\Sandbox\Models\Settings;

For test purposes, I created a new controller and implemented the above model to get access to the API key.

<?php namespace Playground\Sandbox\Controllers;

use Illuminate\Routing\Controller;
use Playground\Sandbox\Models\Settings;

class Swing extends Controller
{
    /**
     * @var Plugin settings
     */
    protected $settings;

    /**
     * Sandbox constructor.
     */
    public function __construct()
    {
        $this->settings = Settings::instance();
    }

    /**
     * @param $params
     */
    public function index($params)
    {
        try {

            $enabled = $this->settings->enabled;

            if ($enabled) {
                
                // Use settings values
                var_dump($this->settings->api_key);
            }
        }

        catch (\Exception $ex) {
            $ex->getMessage();
        }
    }
}

<?php namespace Playground\Sandbox\Controllers;

use Illuminate\Routing\Controller;

use Playground\Sandbox\Models\Settings;

class Swing extends Controller

{

/**

* @var Plugin settings

protected $settings;

/**

* Sandbox constructor.

public function __construct()

{

$this->settings = Settings::instance();

}

/**

* @param $params

public function index($params)

{

try {

$enabled = $this->settings->enabled;

if ($enabled) {

// Use settings values

var_dump($this->settings->api_key);

}

catch (\Exception $ex) {

$ex->getMessage();

}

Here you go.

The entire source code can be found on https://github.com/tobias-forkel/october-cms-playground.

I tried to implement a simple field validation for a checkbox Apply Special Price which I needed on the Catalog > Product > Edit page. Unfortunately my first attempt below didn’t work and broke the whole grid table.

The requested component ("settings") is not found. Before using, you must add the implementation.

1	The requested component ("settings") is not found. Before using, you must add the implementation.

Here is how I have defined the field apply_special_price in category_form.xml based on different stackoverflow posts.

<field name="apply_special_price">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            ....
        </item>
    </argument>
    <settings>
        <validation>
            <rule name="required-entry" xsi:type="boolean">false</rule>
        </validation>
        <dataType>boolean</dataType>
    </settings>
    <formElements>
        <checkbox>
            <settings>
                <valueMap>
                    <map name="false" xsi:type="string">0</map>
                    <map name="true" xsi:type="string">1</map>
                </valueMap>
                <prefer>toggle</prefer>
            </settings>
        </checkbox>
    </formElements>
</field>

....

</item>

</argument>

<rule name="required-entry" xsi:type="boolean">false</rule>

</validation>

<dataType>boolean</dataType>

</settings>

</valueMap>

<prefer>toggle</prefer>

</settings>

</checkbox>

</formElements>

</field>

As I said, it didn’t work at all. So, I kept researching and found a solution which allowed me to implement the validation rule without the nodes <settings> and <formElements> inside of <field>.

<field name="apply_special_price">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="dataType" xsi:type="string">boolean</item>
            <item name="formElement" xsi:type="string">checkbox</item>
            <item name="source" xsi:type="string">category</item>
            <item name="label" xsi:type="string" translate="true">Apply Special Price</item>
            <item name="sortOrder" xsi:type="number">10</item>
            
            <item name="default" xsi:type="number">0</item>
            <item name="prefer" xsi:type="string">toggle</item>
            <item name="validation" xsi:type="array">
                <item name="required-entry" xsi:type="boolean">false</item>
            </item>
            <item name="valueMap" xsi:type="array">
                <item name="true" xsi:type="string">1</item>
                <item name="false" xsi:type="string">0</item>
            </item>
        </item>
    </argument>
</field>

<item name="dataType" xsi:type="string">boolean</item>

<item name="formElement" xsi:type="string">checkbox</item>

<item name="source" xsi:type="string">category</item>

<item name="label" xsi:type="string" translate="true">Apply Special Price</item>

<item name="prefer" xsi:type="string">toggle</item>

<item name="required-entry" xsi:type="boolean">false</item>

</item>

</item>

</argument>

</field>

Basically, everything has to be defined inside of config otherwise the XML for your custom UI component will be invalid. The section validation allows you to define filters for pretty much every use case. The example below sets a field as mandatory and detects white spaces. Beside that it will make sure the value matches a specific regex pattern.

<item name="validation" xsi:type="array">
    <item name="required-entry" xsi:type="boolean">false</item>
    <item name="no-whitespace" xsi:type="boolean">true</item>
    <item name="validate-pattern" xsi:type="string">/^[a-z][a-z0-9_.-]$/i</item>
</item>

<item name="required-entry" xsi:type="boolean">false</item>

</item>

More validation options are available out-of-the-box.

min_text_length
max_text_length
max-words
min-words
range-words
letters-with-basic-punc
alphanumeric
letters-only
no-whitespace
zip-range
integer
vinUS
dateITA
dateNL
time
time12h
phoneUS
phoneUK
mobileUK
stripped-min-length
email2
url2
credit-card-types
ipv4
ipv6
pattern
validate-no-html-tags
validate-select
validate-no-empty
validate-alphanum-with-spaces
validate-data
validate-street
validate-phoneStrict
validate-phoneLax
validate-fax
validate-email
validate-emailSender
validate-password
validate-admin-password
validate-url
validate-clean-url
validate-xml-identifier
validate-ssn
validate-zip-us
validate-date-au
validate-currency-dollar
validate-not-negative-number
validate-zero-or-greater
validate-greater-than-zero
validate-css-length
validate-number
validate-number-range
validate-digits
validate-digits-range
validate-range
validate-alpha
validate-code
validate-alphanum
validate-date
validate-identifier
validate-zip-international
validate-state
less-than-equals-to
greater-than-equals-to
validate-emails
validate-cc-number
validate-cc-ukss
required-entry
checked
not-negative-amount
validate-per-page-value-list
validate-new-password
validate-item-quantity
equalTo

min_text_length

max_text_length

max-words

min-words

range-words

letters-with-basic-punc

alphanumeric

letters-only

no-whitespace

zip-range

integer

vinUS

dateITA

dateNL

time

time12h

phoneUS

phoneUK

mobileUK

stripped-min-length

email2

url2

credit-card-types

ipv4

ipv6

pattern

validate-no-html-tags

validate-select

validate-no-empty

validate-alphanum-with-spaces

validate-data

validate-street

validate-phoneStrict

validate-phoneLax

validate-fax

validate-email

validate-emailSender

validate-password

validate-admin-password

validate-url

validate-clean-url

validate-xml-identifier

validate-ssn

validate-zip-us

validate-date-au

validate-currency-dollar

validate-not-negative-number

validate-zero-or-greater

validate-greater-than-zero

validate-css-length

validate-number

validate-number-range

validate-digits

validate-digits-range

validate-range

validate-alpha

validate-code

validate-alphanum

validate-date

validate-identifier

validate-zip-international

validate-state

less-than-equals-to

greater-than-equals-to

validate-emails

validate-cc-number

validate-cc-ukss

required-entry

checked

not-negative-amount

validate-per-page-value-list

validate-new-password

validate-item-quantity

equalTo

Tag: Backend

October CMS – Add Menu Item And Store Backend Settings

The requested component (“settings”) is not found. Before using, you must add the implementation.