Chapters
This Page
Option Arrays
Introduction
Options inside of Platform 5 are driven by a very simple PHP options array format.
Using this format allows us a very simple and consistent way of drawing out various options and option types for user customization
Where options arrays are used
Inside Sections
The primary location for options arrays are inside the section_options()
method of the Section API. This function is designed to simply return the options array that will then configure the unique options available for that section.
The basic option array inside a section looks like this:
/**
* Example: "Section Option Array"
*/
class My_Section extends PL_Section {
/** Option array method (returns options) */
function section_opts(){
// Setup Option Array
$options = array();
$options[] = array(
'type' => 'text, // type of option
'key' => 'my_unique_key', // the unique key for option, referred to in HTML bindings
'title' => 'My Option Title', // Title for option UI
'help' => 'Any help for the user',
'label' => 'Option Label',
);
return $options;
}
/** Section HTML Template (with bindings) */
function section_template(){
?>
<!-- This will sync its text to value of the option -->
<div data-bind="pltext: my_unique_key"></div>
<?php
}
}
Inside Templates
It is also possible to use option arrays inside of WordPress page templates along with the pl_add_static_settings()
function.
/*
* Template Name: My Template
*/
$options = array();
$options[] = array(
'type' => 'text, // type of option
'key' => 'my_unique_key', // the unique key for option, referred to in HTML bindings
'title' => 'My Option Title', // Title for option UI
'help' => 'Any help for the user',
'label' => 'Option Label',
);
// Adds options to the template
pl_add_static_settings( $options );
?>
<!-- This will sync its text to value of the option -->
<div data-bind="pltext: my_unique_key"></div>
Option Parameters
Each entry in your option array supports a variety of different parameters for adding relevant information. For example, adding help text or a link.
// Standard Option Parameters
$options[] = array(
'type' => 'text, // Type of option
'key' => 'my_unique_key', // Unique key
'default' => 'Hello!', // The default option value
'title' => 'My Option Title', // UI Title
'help' => 'Help for the user', // Help
'ref' => 'Help in a dropdown', // Dropdown Help
'label' => 'Option Label', // Label for Option
'opts' => array() // Sub options (used in selects, accordion, multi),
'stylize' => 'custom-class' // Add a custom class to the option (for styling)
);
Overriding Section Options
Every section option can be overridden at runtime using WordPress filters.
In this example we are going to set the posts_per_page section option for postgrid to 48 posts, the maximum the section allows is 32.
class Postgrid_Posts {
function __construct() {
add_filter( 'pl_opt-posts_per_page', array( $this, 'filter' ) );
}
function filter( $var ) {
return 48;
}
}
new Postgrid_Posts;
Option Types
Basic
multi
The multi option type is a utility for nesting options in the UI.
// "multi" option type
// This will have two nested text options within the top level option
$options[] = array(
'type' => 'multi',
'opts' => array(
array(
'type' => 'text',
'key' => 'k1'
),
array(
'type' => 'text',
'key' => 'k2'
),
)
// Other parameters
);
text
and textarea
The text and textarea option types adds basic text and textarea input fields respectively.
text_small
creates a text field but it will be a small field.
// "text" option type
$options[] = array(
'type' => 'text,
// Other parameters
);
// "textarea" option type
$options[] = array(
'type' => 'textarea,
// Other parameters
);
richtext
Adds a richtext editor for text with formatting options. Users can switch between this and a simple textarea.
// "text" option type
$options[] = array(
'type' => 'richtext,
// Other parameters
);
image_upload
A simple image uploader for the WordPress media library
// "image_upload" option type
$options[] = array(
'type' => 'image_upload',
// Other parameters
);
check
A simple checkbox option
// "check" option type
$options[] = array(
'key' => 'sticky',
'type' => 'check',
'label' => __( 'Make nav sticky on scroll?', 'pagelines' ),
),
A checkbox option might be used with a binding as follows:
// "check" option binded in template
// If the checkbox is 'checked', its value will be 1 so add the class of 'do-sticky' to the item.
<div class="my-nav pl-trigger" data-bind="plclassname: [sticky() == 1 ? 'do-sticky' : '']">
<div class="nav-stuff">
</div>
</div>
Selects
select
Create a select option for various options.
Select options use a sub 'opts' array to add the various values.
// "image_upload" option type
$options[] = array(
'type' => 'select',
'opts' => array(
'value_1' => array( 'name' => "Option 1 Text"),
'value_2' => array( 'name' => "Option 2 Text")
)
// Other parameters
);
select_icon
Select a standard icon.
// "select_icon" option type
$options[] = array(
'type' => 'select_icon',
// Other parameters
);
select_menu
Select a WP menu.
// "select_menu" option type
$options[] = array(
'type' => 'select_menu',
// Other parameters
);
count_select
Uses count parameters to create a numerical selector
// "count_select" option type
$options[] = array(
'type' => 'count_select',
'count_start' => 5, // Count starts at this value
'count_mult' => 5, // Count between each option
'count_number' => 200, // Count total
'suffix' => 'px', // Suffix added to option text
'default' => 10,
// Other parameters
);
Advanced
accordion
The advanced accordion type is ideal for adding sortable arrays of items with similar formats. For example, multiple boxes, slides or quotes.
// "accordion" option type
$options[] = array(
'key' => 'my_accordion_key',
'type' => 'accordion',
'title' => __('Item Setup', 'pagelines'),
'opts' => array(
array(
'key' => 'title',
'label' => __( 'Title', 'pagelines' ),
'type' => 'text',
'default' => 'Hello'
),
array(
'key' => 'text',
'label' => __( 'Text', 'pagelines' ),
'type' => 'richtext',
'default' => 'This is a box.'
),
)
);
The accordion is typically used with either the pltemplate or plforeach bindings in a template as follows
// "accordion" option type
<div class="my-item-wrap pl-trigger" data-bind="plforeach: my_accordion_key">
<div class="the-item pl-trigger">
<h3 data-bind="pltext: title"></h3>
<p data-bind="pltext: text"></p>
</div>
</div>
The foreach loop above will loop through and create a unique item for every item in the accordion option.
dragger
The dragger option type creates several small, draggable input fields for numerical inputs. For example, this is used for padding and grid controls.
To add your own dragger options simply use a sub options array as follows:
// "accordion" option type
$options[] = array(
'type' => 'dragger',
'label' => __( 'Logo Size / Height', 'pagelines' ),
'opts' => array(
array(
'key' => 'logo_height',
'min' => 20,
'max' => 300,
'def' => 30,
'unit' => 'px'
),
array(
'key' => 'logo_width_max',
'min' => 20,
'max' => 300,
'def' => 30,
'unit' => 'px'
),
),
);
Utilities
pl_std_opt()
Some options are used time and time again and have a similar format. That's why we've created the pl_std_opt() function to save time by quickly getting a standard type option entry.
Example Standard Option Types
posts_per_page
Select for amount of posts on a pagetext_alignment
Text alignment classessection_alignment
Section alignment classesscheme
Background color scheme selectorbtn
Standard button configuration optionscolumns
Select out of a 12 column gridbackground_image
Background image optionbackground_color
Background color pickermenu
Select a menulink
A link option
// Using pl_std_opt()
$options[] = array(
'key' => 'my_accordion_key',
'type' => 'accordion',
'title' => __('Item Setup', 'pagelines'),
'opts' => array(
pl_std_opt('text'),
pl_std_opt('button'),
pl_std_opt('button', array('key' => 'non_default_key') ), // use the second parameter to override the defaults
)
);
Creating Buttons
Because each button has a standard structure and options, we have created some utitilities to help you quickly create button options.
The function pl_button_link_options
takes a key and creates several options.
[the_key]
The url of the button[the_key]_text
The text of the button[the_key]_style
The color style of the button[the_key]_size
The size of the button (xs, sm, st, lg)[the_key]_newwindow
Should the link open in new window?
// Using pl_button_link_options()
$options[] = array(
'title' => __( 'Primary Button', 'pagelines' ),
'type' => 'multi',
'stylize' => 'button-config',
'opts' => pl_button_link_options( 'button_primary', array(
'button_primary' => '#', // Default URL
'button_primary_text' => 'More', // Default Text
'button_primary_size' => 'lg' // Default Size
) )
);