Extension Settings

Simple Extension Settings

Simple extension settings refer to the extension settings form in the control panel, where fields are added by declaring them in the init method of the extension. They are specified in the form of an array as follows:

$this->configSettings(array(
    'key1' => array( // Unique setting key, valid characters: a-z, A-Z, 0-9, -, _
        'title' => 'Field name displayed in the form',
        'title.description' => 'Description of the field displayed below the field name in gray smaller text',
        'description' => 'Additional description displayed below the field',
        'tip' => 'Tooltip displayed as a question mark icon next to the field name or to the right of the field (in the case of a number input field)',
        'placeholder' => 'Example value for text input fields (text, textarea, password)',
        'input' => 'Field type: text, textarea, etc. All available field types are described below',
        'type' => 'Data type: TYPE_STR, TYPE_BOOL, ... It is possible to specify a type different from the default type',
        'default' => 'Default value, must correspond to the data type of the field to avoid type conversion errors',
        'required' => true/false, // Required field, default - false
        'readonly' => true/false, // Field is read-only, without the ability to change the value specified in the "default" setting, default - false
        'onChange' => function($newValue, $oldValue){
            // Function to perform additional validation of the value specified by the user.
            // Applicable to all field types that require user selection/input.
            // Example of validating the new value:
            // if (empty($newValue)) {
            //    $this->errors->set('Error when validating the new value');
            //    return false;
            // }
            return $newValue; // Returns the final setting value or false in case of an error
        },
    ),
    'key2' => array(
        // ...
    ),
));

In addition to the specified settings, a field may also have specific additional settings. See an example of their declaration in the settings of each type. In the future, access to these settings, or rather retrieving the values specified in the form, can be done using the $this->config method, for example:

$value1 = $this->config('key1');

There is also the $this->configUpdate method available for modifying the value of a setting and saving it:

$this->configUpdate('key1', 'value');

Text Fields

Text input field:

array(
    'text1' => array(
        'title' => 'Single-line text',
        'input' => 'text',
        //'width' => 100, // Field width in pixels (100, '100px', '50%'), by default full width
    ),
    'text2' => array(
        'title' => 'Multiline text',
        'input' => 'textarea',
    ),
);

Data type by default is TYPE_STR.
By default, text fields are multilingual. If multiple languages are enabled in the project, you can specify a value for each language. To disable this, you can use 'lang' => false,. When retrieving a value, you can also specify the desired language version:

$text1 = $this->config('text1');
$text1_ru = $this->config('text1', '', 'ru');

Checkbox

Checkbox field (yes/no).

array(
    'key' => array(
        'title' => 'Title',
        'description' => 'Description displayed to the right of the checkbox',
        'input' => 'checkbox',
    ),
);

Default data type is TYPE_BOOL.

Checkbox Group

A group of checkboxes for selecting multiple values.

array(
    'key' => array(
        'title' => 'Title',
        'input' => 'checkbox-group',
        'options' => array(
            1 => array('title' => 'Checkbox 1'),
            2 => array('title' => 'Checkbox 2'),
            //...
        ),
    ),
);

Default data type is TYPE_ARRAY. To convert it to the desired type, use TYPE_ARRAY_, for example TYPE_ARRAY_UINT. The saved data is returned ($this->config()) as an array.

Dropdown list (select)

A field for selecting one value from the available list.

array(
    'key' => array(
        'title' => 'Title',
        'input' => 'select',
        'options' => array( // A callback function can also be used here, which returns an array with a similar structure
            '1' => array('title' => 'Option 1'),
            '2' => array('title' => 'Option 2', 'description' => 'Additional description displayed when this option is selected'),
            //...
        ),
    ),
);

The default data type is TYPE_STR.

Password

A field for entering a password.

array(
    'key' => array(
        'title' => 'Title',
        'input' => 'password',
    ),
);

The default data type is TYPE_NOTRIM (string without processing). The value is stored encrypted and is not displayed when editing.
If necessary, you can also encrypt the value of any field by specifying 'encrypt' => true, in the field settings.

Number

A field for entering a number.

array(
    'key' => array(
        'title' => 'Title',
        'input' => 'number',
        'min' => 5, // Minimum allowable value
        'max' => 100, // Maximum allowable value
        'tip' => $this->lang('min'), // An example of a brief description, such as the units in which the value is specified 
    ),
);

The default data type is TYPE_UINT (unsigned integer).
The tip configuration will be displayed to the right of the field if the text is not longer than 15 characters.

Image

Field for uploading image files.
Allowed extensions: jpg, jpeg, gif, png, svg

array(
    'image1' => array(
        'title' => 'Title',
        'input' => 'image',
        'image' => array(
            'sizes' => array(
                'small' => array(
                    'width'    => 100, 'height'   => false,
                    'vertical' => array('width' => false, 'height' => 100)
                ),
                'view' => array(
                    'width'    => 800, 'height'   => false,
                    'vertical' => array('width' => false, 'height' => 800)
                ),
            ),
            //'maxSize' => 10485760, # Maximum allowed file size of the image in bytes
            'limit' => 1, # Maximum number of uploaded image files allowed
        ),
    ),
);

In the sizes field, specify all the necessary images in which the uploaded image will be saved.
The text size key must be unique and specified in Latin letters, with the following characters allowed: a-z, A-Z, 0-9, -, _ To get the URL of the uploaded image file, use the method $this->configImages:

$url = $this->configImages('image1', 'small'); // The second parameter specifies the key of the required size
// If the limit is set to 2 or more, the method will return a list of URLs for the specified size

File

Field for uploading a single file.
Default allowed extensions: jpg, jpeg, gif, png, bmp, tiff, ico, odt, doc, docx, docm, xls, xlsx, xlsm, ppt, rtf, pdf, djvu, zip, gzip, gz, 7z, rar, txt, xml

array(
    'file1' => array(
        'title' => 'Title',
        'input' => 'file',
        'file' => array(
            // Additional settings:
            //'extensionsAllowed' => 'png,svg,ico',
            //'maxSize' => 3145728, // Maximum allowed size of the uploaded file in bytes
            //'publicStore' => true/false, // true - files are accessible via a direct URL after upload
        ),
    ),
);

To get the URL of the uploaded file, use the method $this->configFiles:

$url = $this->configFiles('file1');

If the uploaded file should not be accessible via a direct URL after upload, you can change the storage directory to /files/extensions/ as follows:

'file' => array(
    'publicStore' => false,
),

Additional Field Types

Hidden Field

A field that is not displayed in the form but its value can be specified/modified in the extension.
Often used for data generated during installation or obtained from external sources.

array(
    'key' => array(
        'title' => 'Title',
        'input' => 'hidden',
    ),
);

The default data type is TYPE_STR.

Divider

A field that separates fields with a horizontal line <hr />.
Often used for data generated during installation or obtained from external sources.

array(
    'key' => array(
        'input' => 'divider',
    ),
);

The default data type is TYPE_STR.
The field key can be specified as D1, D2, for example.

Title

A field title for a group of fields.

array(
    'key' => array(
        'title' => 'Title',
        'input' => 'title',
    ),
);

The default data type is TYPE_STR.
The field key can be specified as D1, D2, for example.

%%%

Settings Tabs

If you have a lot of settings and need to divide them into multiple tabs, you can do it as follows:

$this->configSettings(array(
    'key1' => array(
        'title' => 'Field №1',
        'input' => 'text',
        'tab'   => 'tabKey1', // Tab Key 1
    ),
    'key2' => array(
        'title' => 'Field №2',
        'input' => 'text',
        'tab'   => 'tabKey2', // Tab Key 2
    ),
), array(
    'tabs' => array(
        'tabKey1' => array( // Unique tab key, allowed characters: a-z, A-Z, 0-9, -, _
            'title' => 'Tab №1',
        ),
        'tabKey2' => array(
            'title' => 'Tab №2',
        ),
    ),
));

In this example, the setting key1 will be displayed in tab №1, and the setting key2 in tab №2.

Field Visibility

Simple form fields can be interdependent using visibility settings, for example:

array(
    'key1' => array(
        'title' => '№1',
        'input' => 'checkbox',
    ),
    'key2' => array(
        'title' => '№2',
        'input' => 'checkbox',
        'visibleIf' => ['key1' => true],
    ),
    'key3' => array(
        'title' => '№3',
        'input' => 'checkbox',
        'hiddenIf' => ['key1' => true, 'key2' => true],
    ),
);

In this example, field №2 will only be displayed if field №1 is checked, and field №3 will be hidden if either field №1 or №2 is checked. The hiddenIf/visibleIf parameter specifies the list of fields in the format 'field key'=>'field value'. %%%

Settings and Form Component

More complex settings for the extension can be created based on the Form Component.

To do this, you can use the init() method of the extension as follows:

    /** @var \bff\extend\extension\settings\Form  */
    public $settings;

    public function init()
    {
        parent::init();
        
        $this->settings = $this->configSettingsForm($this->langAdmin('Settings'));
        $this->settings->tab('tab1', $this->langAdmin('General settings'));
        $this->settings->text('title', $this->langAdmin('Title'));
        $this->settings->checkbox('enabled', $this->langAdmin('Disabled'));
        
        $this->configSettings(array(
            // ...
        ));
        
    }

Note that calling the configSettings method is also mandatory and should be done after calling configSettingsForm.

Read about all available form field types in the article "Form Fields".