Creating a Module Settings Page

Modules can add any number of links to the System/Settings and My Settings pages.

There are two ways to add links to the Settings pages - by implementing listSettingsItems() and listPersonalSettingsItems() methods in the module information class or by using the Settings API. First method is more universal and allows to create settings pages of any complexity. It requires writing controllers and views for settings pages. Settings API allows to create simple configuration forms based on the configuration which should be defined in the module information class and do not require developing controllers and views.

How to choose between the usual approach and Settings API

Settings API simplifies development but has the following limitations:

• Settings API creates links to settings forms. You cannot use settings API for creating a link to a list. 
• Automatically rendered relation fields (drop-down menus, checkbox or radio button lists based on relations) are not supported.
• You cannot implement any custom AJAX requests on the settings form. Setting form can only be loaded, edited and saved. On the other hand, you can inject custom JavaScript scripts to the form page with the core:onConfigureModuleSettingsController event and implement simple effects like hiding/showing fields when some checkbox on the form is checked/unchecked.

Creating settings pages with the usual approach 

To create settings links on the System/Settings page or on the My Settings page your module information class should implement listSettingsItems() and listPersonalSettingsItems() methods. The both methods should return an array containing information about the the links. The array structure is identical for the both methods. It should be an array of arrays. Each inner array represents a single link. Example:

public function listSettingsItems()
{
	return array(
		array(
			'icon'=>'/modules/system/resources/images/mail_settings.png', 
			'title'=>'Email Settings', 
			'url'=>'/system/email',
			'description'=>'Configure email settings. Specify SMTP server address and authorization parameters. ',
			'sort_id'=>20,
			'section'=>'System'
			),
		array(
			'icon'=>'/modules/system/resources/images/themes.png', 
			'title'=>'Customize', 
			'url'=>'/system/colortheme',
			'description'=>'Choose color theme for the Administration Area, upload a company logo, etc.',
			'sort_id'=>110,
			'section'=>'System'
			)
	);
}

• icon - path to the icon file relative to the system root directory. Icons should be 48x48 px. PNG images.
• title - specifies the link title.
• url - URL of the page the link refers to, relative to the system root.
• description  - specifies the link description text.
• sort_id - specifies the position of the link on the settings page. All system links have increment of 10.
• section - specifies a name of the settings page section to place the link to. This parameter is optional. If omitted, the link will be placed to the Miscellaneous section. 

For each settings link a controller should be implemented. Settings controllers should extend the Backend_SettingsController. Settings pages should have breadcrumbs referring to the Settings page:

<!-- Breadcrumbs for personal settings -->

<ul class="breadcrumbs">
	<li><a href="<?= url('/system/settings') ?>">My Settings</a></li>
	<li><?= $this->app_page_title ?></li>
</ul>

<!-- Breadcrumbs for global settings -->

<ul class="breadcrumbs">
	<li><a href="<?= url('/system/mysettings') ?>">Settings</a></li>
	<li><?= $this->app_page_title ?></li>
</ul>

Creating settings pages with the Settings API

To use the Settings API your module information class should implement the following methods:

• listSettingsForms
• buildSettingsForm
• initSettingsData (optional)
• validateSettingsData (optional)
• getSettingsFieldOptions (optional)

listSettingsForms()

This method should return a list of the module settings forms. A method should return an associative array of arrays, where where each inner array defines a settings link. Keys of the outer array define settings form codes. Example:

public function listSettingsForms()
{
	return array(
		'global-editor-settings'=>array(
			'icon'=>'/modules/mymodule/resources/images/global-settings.png', 
			'title'=>'Global editor settings', 
			'description'=>'Configure global code editor settings',
			'sort_id'=>100,
			'section'=>'Editor'
		),
		'personal-editor-settings'=>array(
			'icon'=>'/modules/mymodule/resources/images/personal-settings.png', 
			'title'=>'My editor settings', 
			'description'=>'Configure personal code editor settings',
			'sort_id'=>100,
			'section'=>'Editor',
			'personal'=>true,
			'width_class'=>'form-300'
		)
	);
}

• personal - indicates whether the link should be placed to the My Settings page. By default links are placed to the System/Settings page.
• width_class - CSS class name defining the settings form width. Known class names are form-300, form-400, 450, form-500, form-650, form-700, form-750, form-800, form-850.

buildSettingsForm($model, $form_code)

This method configures a settings form. The method has 2 parameters - the model object to add new fields to, and the form code. You can create new fields with calling the add_field() method of the model object. The method has 4 parameters - field code, field title, alignment class (left, right, full) and the value type (db_varchar, db_number, db_float, db_bool, db_datetime, db_date, db_time, db_text). The method returns the Db_FormFieldDefinition object, which you can configure (see Forms article for details). Example:

public function buildSettingsForm($model, $form_code)
{
	$model->add_field('font_size', 'Font size', 'full', db_number)->renderAs(frm_dropdown);
	$model->add_field('soft_wrap', 'Soft word wrap', 'full', db_varchar);

	if ($form_code == 'personal-editor-settings')
		$model->add_field('editor_height', 'Edito height', 'full', db_number);
}

initSettingsData($model, $form_code)

This method allows you to set default parameter values which should be applied in case if the configuration record does not exist in the database. The method has 2 parameters - the model to set the field values and form code. Example: 

public function initSettingsData($model, $form_code)
{
	$model->font_size = 10;
	$model->soft_wrap = 1;

	if ($form_code == 'personal-editor-settings')
		$model->editor_height = 200;
}

validateSettingsData($model, $form_code)

In this method you can validate parameter values before the record is saved to the database.  The method has 2 parameters - the model to set the field values and form code. Use the model validation object to trigger validation errors. Example: 

public function validateSettingsData($model, $form_code)
{
	if ($model->font_size < 1)
		$model->validation->setError('Please specify a positive value in the Font Size field', 'font_size', true);
}

getSettingsFieldOptions($model, $form_code, $field_code)

You should implement this method if you use drop-down menus, checkbox lists or radio button lists on your settings form. The method has 3 parameters - the model, the form code and the field code. Method should return an associative array of option values. Example: 

public function getSettingsFieldOptions($model, $form_code, $field_code)
{
	if ($field_code == 'font_size')
		return array(
			'10'=>'10pt', 
			'11'=>'11pt',
			'12'=>'12pt',
			'13'=>'13pt',
	);
}

Accessing module settings

Use the Core_ModuleSettings::create($module_id, $form_code) method to load module settings object. The method returns an object with all fields which you defined in the buildSettingsForm() method. Example: 

$settings = Core_ModuleSettings::create('mymodule', 'personal-editor-settings');
$font_size = $settings->font_size;

Customizing the settings form page

You can inject CSS and JavaScript files to the settings page by handling the core:onConfigureModuleSettingsController event. The event handler should have 2 parameters - the controller object and the form code. You can use addJavaScript() and addCss() methods of the controller object to add JavaScript and CSS files. Example: 

public function subscribeEvents() 
{
	Backend::$events->add_event('core:onConfigureModuleSettingsController', $this, 'configure_settings_controller');
}

public function configure_settings_controller($controller, $form_code) 
{
	if ($form_code == 'personal-editor-settings')
		$controller->addJavaScript('/modules/mymodule/resources/javascript/personal-settings.js');
}

Previous: Authoring for LemonStand Marketplace
Return to Extending LemonStand