Building a Module – Option Types

Important: This is the second tutorial in the series. If you did not read the previous one, please do that first.

Introduction

In the previous tutorial we covered the basics by building a very simple module. In this tutorial we will take a better look at the options system.

Each option is a  PHP array with several keys and values. In the remaining of the tutorial those sets of keys and values will be refered as option parameters.

Option Parameters (label, id, std, type)

Let’s take a look at how an option looks like:

array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => 'default',
	'type' => 'text'
),

As you can see there are 4 parameters in the code above:  label, id, std and type. Those 4 parameters are required for every option (unlike other parameters, but more on that later).

There’s a couple things to mention regarding the  id:

• Multiple options inside of one module can NOT have the same ID (but you can use same ID accross multiple modules).
• Only use lowercase letters and underscores for spacing (ex. amount_of_posts)
• Keep it tidy, you’ll have a lot of options. For example prepend CSS related options with “css_” (ex. css_padding).

As for the  type parameter, here are all the available ones:

• text
• textarea
• select
• checkbox
• radio
• color
• slider
• font
• icon
• image

Some of them use additional parameters, more on that in the remaining of this tutorial.

Option Parameters (choices)

The  choices parameter is used to supply the choices ( didn’t see that coming, right? hehe ) for these types of options: select, checkbox and radio. It is in form of arrays. Here’s an example with the select option type:

array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => 'one',
	'type' => 'select',
	'choices' => array(
		array(
			'label' => 'Choice One',
			'value' => 'one'
		),
		array(
			'label' => 'Choice Two',
			'value' => 'two'
		),
		array(
			'label' => 'Choice Three',
			'value' => 'three'
		),
	)
),

Option Parameters (refresh_on_change, affect_on_change_rule, affect_on_change_el)

These three work together with each other for  CSS related options ( font-size, color, border-width… ).refresh_on_change is used to tell LC not to reload the module when a change is made,affect_on_change_el is used to set which element will the change affect and affect_on_change_rule is used to set the rule which will be applied to the element.

Here’s an example of an option that changes text color in an element.

array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => '#000000',
	'type' => 'color',
	'refresh_on_change' => false,
	'affect_on_change_el' => '.element-to-affect',
	'affect_on_change_rule' => 'color',
),

array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => '#000000',
	'type' => 'color',
	'refresh_on_change' => false,
	'affect_on_change_el' => '.element-to-affect,.element-to-affect-2',
	'affect_on_change_rule' => 'color,border-color',
),

Important: For these CSS related options you don’t need to do anything to apply them, simply register and LC will take care of everything.

Option Parameters (ext, min, max)

These three are used only for the  slider option type. ext is the extension that will be added to the number ( px, em, % ), min is the minimum value the slider goes to, max is the maximum value the slider goes to.

Here’s an example of a font-size option with px extension and allowed value from 5 to 50:

array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => '14',
	'type' => 'slider',
	'refresh_on_change' => false,
	'affect_on_change_el' => '.element-to-affect',
	'affect_on_change_rule' => 'font-size',
	'ext' => 'px',
	'min' => 5,
	'max' => 50
),

Notice: The minimum value can be negative.

Option Parameters (sections and tabs)

I’m sure you noticed in the existing LC modules that options are separated in “Functionality”, “Styling” and “Responsive”. But just in case you did not, take a look at the screenshot bellow.

Those are handled by two option parameters:  section and tab. Check the code bellow for some examples.

// No section, no tab. Defaults to "Functionality" section and "General" tab.
array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => 'default',
	'type' => 'text'
),

// Section supplied, no tab. Goes in "Styling" section and "General" tab.
array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => 'default',
	'type' => 'text',
	'section' => 'styling',
),

// Section supplied, tab supplied. Goes in "Styling" section and "Thumbnail" tab.
array(
	'label' => 'Option Label',
	'id' => 'option_id',
	'std' => 'default',
	'type' => 'text',
	'section' => 'styling',
	'tab' => 'thumbnail'
),

Tutorial Finished

That concludes this tutorial on the module options system. For examples check out the existing modules ( best way to understand it is to see a “real life” usage of it ).