The most frequent function of the component’s control panel is to output and process the form of options that influence the component’s work in the frontend.

The cmsBackend class, from which the control panel’s controller is inhereted, already contains the description of the options action thus facilitatating the implementation of this typical task. This action is available at this URL: /admin/controllers/edit/{component}/options and performs the following:

• Reads the form of options from a file;
• Outputs the form to the screen;
• Saves options to the controllers Table, once the form is sent.

The values of options saved by this action are available in the component’s frontend in the form of pairs title → value.

Below, we are going to consider a step by step implemetation of this method.

First of all you need to create a description of the form of options, i.e. what fields it will contain.

The form is located in the /system/controllers/{component}/backend/forms/form_options.php file.

The form class should be called form{ComponentTitle}Options.

An example of the form of options for the comments component:

//system/controllers/comments/backend/forms/form_options.php
class formCommentsOptions extends cmsForm {
 
    public function init() {
 
        return array(
 
            array(
                'type' => 'fieldset',
                'childs' => array(
 
                    new fieldCheckbox('is_guests', array(
                        'title' => LANG_COMMENTS_OPT_IS_GUESTS,
                        'hint' => LANG_COMMENTS_OPT_IS_GUESTS_HINT,
                    )),
 
                    new fieldNumber('guest_ip_delay', array(
                        'title' => LANG_COMMENTS_OPT_GUESTS_DELAY,
                        'units' => LANG_MINUTE10,
                    )),
 
                    new fieldText('restricted_ips', array(
                        'title' => LANG_COMMENTS_OPT_GUESTS_RESTRICTED_IPS,
                        'hint' => LANG_COMMENTS_OPT_GUESTS_RESTRICTED_IPS_HINT,
                    )),
                )
            ),
        );
    }
}

The structure of the form file and available field types are considered in detail in the Relevant Section.

Add the following string to the class description to make the control panel (backend.php) controller know you want to use a standard action of options:

public $useDefaultOptionsAction = true;

After this, the action will be available at this URL: /admin/controllers/edit/{component}/options.

For InstantCMS higher than 2.4.0

There is no need to create a template of a form of options for InstantCMS versions higher than 2.4.0. By default, the /templates/default/controllers/admin/backend/controllers_options.tpl.php template will be used.

Note that if you need to show a link to documentation, create the LANG_HELP_URL_COM_CONTROLLER-NAME constant in the controller’s Language File and enter the information URL. In this case, a link to it will appear on the page of options.

There is a callback-function request when saving the form, to which an array of new values of the controller’s options is passed. If you need it, define the following method in the backend.php file:

    public function loadCallback() {
 
        $this->callbacks = array(
            'actionoptions'=>array(
                function($controller, $options){
                    // $controller - contains the current controller’s object
                    // $options - an array of new options
                    // you can perform any actions here
                }
            )
        );
 
    }

If, for any reason, you need a custom form of options, see below.

For InstantCMS 2.4.0 and older

Up to InstantCMS version 2.4.0 inclusively, the template is mandatory.

Option output template

If you need a custom template of a form of options – create the /templates/default/controllers/{component}/backend/options.tpl.php file with at least the following contents:

<?php
 
    $this->addBreadcrumb(LANG_OPTIONS);
 
    $this->addToolButton(array(
        'class' => 'save',
        'title' => LANG_SAVE,
        'href'  => "javascript:icms.forms.submit()"
    ));
 
    $this->renderForm($form, $options, array(
        'action' => '',
        'method' => 'post'
    ), $errors);
 

You can modify this file according to your needs.

It makes sense to create a control panel menu if your component’s control panel is going to have other sections in addition to options.

For this, add the getBackendMenu() method to the control panel’s controller (backend.php):

public function getBackendMenu(){
    return array(
 
        // a link to the "Options" action
        array(
            'title' => LANG_OPTIONS,
            'url' => href_to($this->root_url, 'options')
        ),
 
        // ... add links to other control panel sections here ...
 
    );
}

When switching to the component settings, by default, the control panel sends a user to the index action of your control panel’s controller. For this reason, if you do not need such action in your control panel, you can automatically redirect it to another action.

An example of redirection from the index action to the options action (in the auth component):

class backendAuth extends cmsBackend{
 
    public $useDefaultOptionsAction = true;
 
    public function actionIndex(){
        $this->redirectToAction('options');
    }
 
}

To make the frontend and backend (and their actions) use options specified in the component’s control panel, add the following property in the frontend (frontend.php) class and in the backend (backend.php) class:

protected $useOptions = true;

After this, you can get any option’s value in any action in the following way:

$option_value = $this->options['option_name'];

Check if the option value is available in the following way:

if (!empty($this->options['option_name'])) { ... }

In templates, request the option in the following way:

$this->controller->options['option_name']

For InstantCMS higher than 2.5.1

In the form of options, you can enable an automatic adding of fields with SEO parameters for the component’s main page (index action). For this, set the following property in the frontend and backend files:

public $useSeoOptions = true;

This property is optional in the backend file, if the form of options in your controller is formed not automatically. It will be enough if you pass it through a special method in the component’s settings action after you get the form:

// we get the form
$form = $this->getForm('options');
 
// we automatically add fields with SEO parameters into the form
$form = $this->addControllerSeoOptions($form);

These fields’ values will be in the controller’s options:

$this->options['seo_keys']; // keywords
$this->options['seo_desc']; // description

Back to the "Component Control Panel" section