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) 
    ); 

    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
        ) )
      );