As you move onto the articles after this one, you’re going to learn how to modify options in various scenarios. When doing this, it’s important to understand how we format options and the different option types. This article may seem a little out of context in starting with, but as you explore editing the theme options page, adding custom options pages, editing and creating meta boxes, and adding elements to the layout builder, you’ll be using the information in this tutorial to pass in your options.
How options work
An individual option is a simple array with some specific key-value pairs. This is what would be used when setting up a single option like adding an option to a current section of the theme options page, for example.
$option = array( 'name' => 'Option #1', 'desc' => 'This is the description for the first option.', 'id' => 'option_1', 'std' => 'default value for option #1', 'type' => 'text' );
In the above example, there are five key-value pairs.
- name – The name of the option the user sees.
- desc – The description of the option the user sees.
- id – The unique ID of the option used internally.
- std – The default value for the option.
- type – The type of option. See more examples later in the article.
However, in most cases, you’ll be creating a set of options, opposed to a single option. When you create a set of options, you do this by grouping all of your individual option arrays into a larger array.
This is what you’d do if you’re passing in a set of a options to a new options section, a new Layout builder element, etc.
Let’s look at a simple example of a set of three options.
$options = array( array( 'name' => 'Option #1', 'desc' => 'This is the description for the first option.', 'id' => 'option_1', 'std' => 'default value for option #1', 'type' => 'text' ), array( 'name' => 'Option #2', 'desc' => 'This is the description for the second option.', 'id' => 'option_2', 'std' => 'default value for option #2', 'type' => 'text' ), array( 'name' => 'Option #3', 'desc' => 'This is the description for the third option.', 'id' => 'option_3', 'std' => 'default value for option #3', 'type' => 'text' ) );
You can see that, in the above example, we have an array for each option, and those three arrays are grouped into a larger array.
Option Types
Now that you understand how a set of options is constructed, we can discuss the different basic types of options. In the previous examples, you probably noticed that we used “text” for the type value in each option. This means these options will be outputted as text field inputs.
Simple Option Types
The text field and the textareas are the two most basic types of options. They require simply the five key-value pairs we discussed earlier in the article.
Text Input
$option = array( 'name' => 'Example Text Field', 'desc' => 'This is the description for the option.', 'id' => 'example_text_field', 'std' => 'default value for option', 'type' => 'text' );
Textarea
$option = array( 'name' => 'Example Textarea', 'desc' => 'This is the description for the option.', 'id' => 'example_textarea', 'std' => 'default value for option', 'type' => 'textarea' );
Color Selection
$option = array( 'name' => 'Example Color Selection', 'desc' => 'This is the description for the option.', 'id' => 'example_color', 'std' => '#000000', 'type' => 'color' );
Advanced Option Types
In the following selection option types, there is a new item added to the arrays. This is the ‘options’ key. This determines the selection options for each particular option.
Select
$option = array( 'name' => 'Example Select', 'desc' => 'This is the description for the option.', 'id' => 'example_select', 'std' => 'option_1', 'type' => 'select', 'options' => array( 'option_1' => 'Option 1', 'option_2' => 'Option 2', 'option_3' => 'Option 3', 'option_4' => 'Option 4' ) );
Radio
$option = array( 'name' => 'Example Radio', 'desc' => 'This is the description for the option.', 'id' => 'example_radio', 'std' => 'option_1', 'type' => 'radio', 'options' => array( 'option_1' => 'Option 1', 'option_2' => 'Option 2', 'option_3' => 'Option 3', 'option_4' => 'Option 4' ) );
Checkbox Group
$option = array( 'name' => 'Example Checkbox Group', 'desc' => 'This is the description for the option.', 'id' => 'example_multicheck', 'std' => array( 'option_1' => 1, 'option_2' => 1 ), 'type' => 'multicheck', 'options' => array( 'option_1' => 'Option 1', 'option_2' => 'Option 2', 'option_3' => 'Option 3', 'option_4' => 'Option 4' ) );
Conclusion
To sum up, here are all of the above option type examples grouped together into a single option section and added onto the Theme Options page’s Layout tab using the themeblvd_add_option_section function.
themeblvd_add_option_section( 'layout', 'example', 'Example Option Types', 'Description of section.', array(
array(
'name' => 'Example Text Field',
'desc' => 'This is the description for the option.',
'id' => 'example_text_field',
'std' => 'default value for option',
'type' => 'text'
),
array(
'name' => 'Example Textarea',
'desc' => 'This is the description for the option.',
'id' => 'example_textarea',
'std' => 'default value for option',
'type' => 'textarea'
),
array(
'name' => 'Example Color Selection',
'desc' => 'This is the description for the option.',
'id' => 'example_color',
'std' => '#000000',
'type' => 'color'
),
array(
'name' => 'Example Select',
'desc' => 'This is the description for the option.',
'id' => 'example_select',
'std' => 'option_1',
'type' => 'select',
'options' => array(
'option_1' => 'Option 1',
'option_2' => 'Option 2',
'option_3' => 'Option 3',
'option_4' => 'Option 4'
)
),
array(
'name' => 'Example Radio',
'desc' => 'This is the description for the option.',
'id' => 'example_radio',
'std' => 'option_1',
'type' => 'radio',
'options' => array(
'option_1' => 'Option 1',
'option_2' => 'Option 2',
'option_3' => 'Option 3',
'option_4' => 'Option 4'
)
),
array(
'name' => 'Example Checkbox Group',
'desc' => 'This is the description for the option.',
'id' => 'example_multicheck',
'std' => array( 'option_1' => 1, 'option_2' => 1 ),
'type' => 'multicheck',
'options' => array(
'option_1' => 'Option 1',
'option_2' => 'Option 2',
'option_3' => 'Option 3',
'option_4' => 'Option 4'
)
)
));