Plugin settings file

If a plugin requires additional setup by a user, then all necessary settings fields must be specified in plugin configuration file lib/config/settings.php in the form of an associative array as shown below:

<?php

return array(
    'setting_key' => array(
        'title'        => '',
        'description'  => '',
        'value'        => '',
        'control_type' => '',
        'options'      => array(
            array (
                'value'       => '',
                'title'       => '',
                'description' => '',
            ),
            ...
        ),
        'control_separator' => '<hr>',
    ),
    ...
);

Parameters used in this file have the following meaning:

Field types

Webasyst framework provides a standard set of controls, which can be displayed on a web page including a plugin settings page. Their types must be specified by means of constants declared in system class waHtmlControl:

waHtmlControl::INPUT: single-line text field.

waHtmlControl::PASSWORD: password field.

waHtmlControl::TEXTAREA: multi-line text field.

waHtmlControl::FILE: file upload button.

waHtmlControl::HIDDEN: hidden field.

waHtmlControl::CHECKBOX: checkbox.

waHtmlControl::GROUPBOX: group of checkboxes. For this type of field, add the 'options' array of items containing the following values:

value: id to be used in PHP code as a key for accessing this item in the associative array of settings values
title: text caption next to a checkbox
description: gray hint displayed to the right of the caption

waHtmlControl::RADIOGROUP: group of radio buttons. For this type of field, add the 'options' array of items containing the following values:

value: value id

title: text caption next to a radio button
description: gray hint displayed to the right of the caption

waHtmlControl::SELECT: drop-down list. For this type of field, add the 'options' array of items containing the following values:

value: value id
title: text value of a list element
description: contents of the title attribute of a list element <option></option>

waHtmlControl::CONTACT: list of contact-editing fields similar to that provided by the Contacts app. By default, these fields contain information related to the current user. Changing these values will not modify the current user and simply saves the entered data in the plugin settings table in the database. For this type of field, add the 'options' array of subarrays corresponding to each displayed contact data field, each such subarray containing a 'value' element with the id of a displayed contact data field:

array('value' => 'phone'),
array('value' => 'email'),

waHtmlControl::CONTACTFIELD: drop-down list contaning all contact fields available in the Contacts app. To make some specific field selected by default, specify its id in the 'value' element for this settings field. For example, if you need the contact phone field (with id='phone') to be selected by default, specify the following value in the 'options' array:

'value' => 'phone',

waHtmlControl::CUSTOM: custom settings control generated by means of arbitrary HTML code. It is recommended to save PHP logic generating such HTML code as a public static method of the main plugin class and specify its name in file settings.php as shown below:

'control_type' => waHtmlControl::CUSTOM.' '.'somePlugin::settingCustomControl'

In this example, HTML code for a custom settings field will be generated in method settingCustomControl() of some plugin class somePlugin.

Dynamic generation of values for multi-fields

The array of values for field types RADIOGROUP, SELECT, GROUPBOX can be generated automatically instead of specifying a manually formed array in the 'options' element. To do so, you must add element 'options_callback' with a simple array of plugin class name and its static method which must return values for the settings control; e.g.:

'options_callback' => array('somePlugin', 'settingSelectValues')

In this example, method somePlugin::settingSelectValues() must return an array with a structure identical to that described for the 'options' element of the same field type (in this example waHtmlControl::SELECT),e.g.:

public static function settingSelectValues()
{
    ...
    $data = array(
        array(
            'value' => '',
            'title' => '',
            'description' => ''
        ),
        array(
            'value' => '',
            'title' => '',
            'description' => ''
        ),
        ...
    );
    return $data;
}

In this case the 'options' element is not required.

Settings file example

<?php

return array(
    'hint' => array(
        'description' => '<h3>'._wp('Specify values requested below for correct plugin operation.').'</h3>',
        'control_type' => waHtmlControl::HIDDEN,
    ),
    'login' => array(
        'title' => _wp('Login name'),
        'description' => _wp('Enter your registered login name.'),
        'control_type' => waHtmlControl::INPUT,
    ),
    'password' => array(
        'title' => _wp('Password'),
        'description' => _wp('Enter your personal password.'),
        'control_type' => waHtmlControl::PASSWORD,
    ),
    'comments' => array(
        'title' => _wp('Comments'),
        'description' => _wp('Optional comments.'),
        'control_type' => waHtmlControl::TEXTAREA,
    ),
    'icon' => array(
        'title' => _wp('Icon'),
        'description' => _wp('Upload a 16*16px large icon file.'),
        'control_type' => waHtmlControl::FILE,
    ),
    'test_mode' => array(
        'title' => _wp('Test mode'),
        'description' => _wp('Disable when you want to go live.'),
        'control_type' => waHtmlControl::CHECKBOX,
        'value' => 1,
    ),
    'statuses' => array(
        'title' => _wp('Order statuses'),
        'description' => _wp('Select the statuses of orders which you want to be exported.'),
        'control_type' => waHtmlControl::GROUPBOX,
        'options_callback' => array('somePlugin', 'getSettingsOrderStatuses'),
        'value' => array('new', 'completed'),
    ),
    'export_mode' => array(
        'title' => _wp('Export mode'),
        'description' => _wp('Select the desired export mode.'),
        'control_type' => waHtmlControl::RADIOGROUP,
        'options' => array(
            array(
                'value' => 'default',
                'title' => _wp('default'),
                'description' => _wp('default data fields'),
            ),
            array(
                'value' => 'advanced',
                'title' => _wp('advanced'),
                'description' => _wp('all data fields'),
            ),
        ),
        'value' => 'default',
    ),
    'protocol' => array(
        'title' => _wp('Data exchange protocol'),
        'description' => _wp('Select the desired data exchange protocol.'),
        'control_type' => waHtmlControl::SELECT,
        'options' => array(
            array(
                'value' => 1,
                'title' => '1.0',
            ),
            array(
                'value' => 2,
                'title' => '2.0',
            ),
        ),
        'value' => 1,
    ),
    'personal_data' => array(
        'control_type' => waHtmlControl::CONTACT,
        'options' => array(
            array('value' => 'email',),
            array('value' => 'phone',),
        ),
    ),
    'customer_phone' => array(
        'title' => _wp('Customer phone number'),
        'description' => _wp('Select the contact field corresponding to customer’s phone number.'),
        'control_type' => waHtmlControl::CONTACTFIELD,
        'value' => 'phone',
    ),
    'tags' => array(
        'title' => _wp('Export tags'),
        'description' => _wp('Add tags which you want to export.'),
        'control_type' => waHtmlControl::CUSTOM.' '.'somePlugin::settingCustomControl',
    ),
);

How to get saved setting value

PHP

$setting_value = wa('app_id')->getPlugin('plugin_id')->getSettings('settings_field_id');

Smarty

{$setting_value = $wa->setting('settings_field_id', '', 'app_id.plugin_id')}