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 page
text_alignment Text alignment classes
section_alignment Section alignment classes
scheme Background color scheme selector
btn Standard button configuration options
columns Select out of a 12 column grid
background_image Background image option
background_color Background color picker
menu Select a menu
link 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
    ) )
  );