Core¶

• Public functions and classes should be prefixed with:

  • fw_ for functions
  • FW_ for classes

  function fw_useful_function() {
      // ...
  }
  
  class FW_Useful_Class {
      // ...
  }
  

  Note

  A Public function is meant to be used by anyone. Usually it’s a helper function that does something useful.

• Private functions and classes should be prefixed with:

  • _fw_ for functions
  • _FW_ for classes

  /**
   * @internal
   */
  function _fw_private_function() {
      // ...
  }
  
  /**
   * @internal
   */
  class _FW_Private_Class
  {
      // ...
  }
  

  Note

  A private function is used somewhere internally. Don’t forget to use the @internal tag in your PhpDoc in order to make it clear to other developers that this is a private function. It will also remove the function from your documentation (if you are using an automatic documentation generator)

• Functions and methods used for hooks should be prefixed with:

  • _action_ for add_action()
  • _filter_ for add_filter()

  /**
   * @internal
   */
  function _action_init_something() {
      // ...
  }
  add_action('init', '_action_init_something');
  

  Important

  Be sure the function name is unique enough in order to minimize the chances to be defined by someone else. Do not use too simple function names like _action_init.

  class FW_Example
  {
      public function __construct()
      {
          add_filter('the_content', array($this, '_filter_the_content'));
      }
  
      /**
       * @internal
       */
      public function _filter_the_content($content) {
          // ...
  
          return $content;
      }
  }
  

• Filters and actions should be prefixed with 'fw_'.

  $data = apply_filters('fw_whatever', $data);
  
  do_action('fw_whatever');
  

Theme¶

• Public functions and classes should be prefixed with:

  • fw_theme_ for functions
  • FW_Theme_ for classes

  function fw_theme_head() {
      // ...
  }
  
  class FW_Theme_Pagination
  {
      // ...
  }
  

• Private functions and classes should be prefixed with:

  • _fw_theme_ for functions
  • _FW_Theme_ for classes

  /**
   * @internal
   */
  function _fw_theme_private_function() {
      // ...
  }
  
  /**
   * @internal
   */
  class _FW_Theme_Private_Class
  {
      // ...
  }
  

• Functions used for hooks should be prefixed with:

  • _action_theme_ for add_action()
  • _filter_theme_ for add_filter()

  /**
   * @internal
   */
  function _filter_theme_the_content($content) {
      // ...
  
      return $content;
  }
  add_filter('the_content', '_filter_theme_the_content');
  
  /**
   * @internal
   */
  function _action_theme_init() {
      // ...
  }
  add_action('init', '_action_theme_init');
  

• Filters and actions should be prefixed with fw_theme_.

  $data = apply_filters('fw_theme_whatever', $data);
  
  do_action('fw_theme_whatever');
  

Extensions¶

• Public functions and classes should be prefixed with:

  • fw_ext_<extension-name>_ for functions
  • FW_Ext_<extension-name>_ for classes

• Private functions and classes should be prefixed with:

  • _fw_ext_<extension-name>_ for functions
  • _FW_Ext_<extension-name>_ for classes

• Functions used for hooks should be prefixed with:

  • _action_fw_ext_<extension-name>_ for add_action()
  • _filter_fw_ext_<extension-name>_ for add_filter()

  For e.g. if extension name is demo:

  /**
   * @internal
   */
  function _filter_fw_ext_demo_the_content($content) {
      // ...
  
      return $content;
  }
  add_filter('the_content', '_filter_fw_ext_demo_the_content');
  
  /**
   * @internal
   */
  function _action_fw_ext_demo_init() {
      // ...
  }
  add_action('init', '_action_fw_ext_demo_init');
  

• Filters and actions should be prefixed with 'fw_ext_<extension-name>_'.

  For e.g. if extension name is demo:

  $data = apply_filters('fw_ext_demo_whatever', $data);
  
  do_action('fw_ext_demo_whatever');
  

HTML¶

All option types must have .fw-option-type-{type} class on main/wrapper html element.

CSS¶

If the option type has css, all rules must be prefixed with .fw-option-type-{type} class:

/* correct */
.fw-option-type-demo .some-class {
    color: blue;
}

/* wrong */
.some-class {
    color: blue;
}

Javascript¶

All javascript must stick to .fw-option-type-{type} class and work only within the main/wrapper element (no events attached to the body). If the option type has custom javascript events, those events must be triggered on the main element.

$someInnerElement.closest('.fw-option-type-demo')
    .trigger('fw:option-type:demo:custom-event', {some: 'data'});

If it’s specified in the documentation that an option type has custom events, it means that you can attach event listeners on the elements with .fw-option-type-{type} class (not on body or fwEvents).

Text¶

Regular text input.

array(
    'type'  => 'text',
    'value' => 'default value',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Password¶

Regular password input.

array(
    'type'  => 'password',
    'value' => 'default value',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Textarea¶

Regular textarea.

array(
    'type'  => 'textarea',
    'value' => 'default value',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Hidden¶

Simple hidden input.

array(
    'type'  => 'hidden',
    'value' => 'default value',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
)

HTML¶

If you want to display a custom piece of html, use this option type.

array(
    'type'  => 'html',
    'value' => 'default hidden value',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'html'  => 'My <b>custom</b> <em>HTML</em>',
)

Checkbox¶

Single checkbox.

array(
    'type'  => 'checkbox',
    'value' => true, // checked/unchecked
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'text'  => __('Yes', 'fw'),
)

Checkboxes¶

A list of checkboxes.

array(
    'type'  => 'checkboxes',
    'value' => array(
        'choice-1' => false,
        'choice-2' => true,
    ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'choices' => array(
        'choice-1' => __('Choice 1', 'fw'),
        'choice-2' => __('Choice 2', 'fw'),
        'choice-3' => __('Choice 3', 'fw'),
    ),
)

Radio¶

A list of radio buttons.

array(
    'type'  => 'radio',
    'value' => 'choice-3',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'choices' => array(
        'choice-1' => __('Choice 1', 'fw'),
        'choice-2' => __('Choice 2', 'fw'),
        'choice-3' => __('Choice 3', 'fw'),
    ),
)

Select¶

Regular select.

array(
    'type'  => 'select',
    'value' => 'choice-3',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'choices' => array(
        '' => '---',
        'choice-1' => __('Choice 1', 'fw'),
        'choice-2' => array(
            'text' => __('Choice 2', 'fw'),
            'attr' => array('data-foo' => 'bar'),
        ),
        array( // optgroup
            'attr'    => array('label' => __('Group 1', 'fw')),
            'choices' => array(
                'choice-3' => __('Choice 3', 'fw'),
                // ...
            ),
        ),
    ),
    /**
     * Allow not existing choices
     * Used when select is used in another option types and populated dynamically
     */
    'no-validate' => false,
)

Select Multiple¶

Select with multiple values.

array(
    'type'  => 'select-multiple',
    'value' => array( 'choice-1', 'choice-3' ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'choices' => array(
        '' => '---',
        'choice-1' => __('Choice 1', 'fw'),
        'choice-2' => array(
            'text' => __('Choice 2', 'fw'),
            'attr' => array('data-foo' => 'bar'),
        ),
        array( // optgroup
            'attr'    => array('label' => __('Group 1', 'fw')),
            'choices' => array(
                'choice-3' => __('Choice 3', 'fw'),
                // ...
            ),
        ),
    ),
)

Multi-Select¶

Select multiple choices from different sources: posts, taxonomies, users or a custom array.

array(
    'type'  => 'multi-select',
    'value' => array( 'choice-1', 'choice-3' ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    /**
     * Set population method
     * Are available: 'posts', 'taxonomy', 'users', 'array'
     */
    'population' => 'array',
    /**
     * Set post types, taxonomies, user roles to search for
     *
     * 'population' => 'posts'
     * 'source' => 'page',
     *
     * 'population' => 'taxonomy'
     * 'source' => 'category',
     *
     * 'population' => 'users'
     * 'source' => array( 'editor', 'subscriber', 'author' ),
     *
     * 'population' => 'array'
     * 'source' => '' // will populate with 'choices' array
     */
    'source' => '',
    /**
     * An array with the available choices
     * Used only when 'population' => 'array'
     */
    'choices' => array(
        'choice-1' => __('Choice 1', 'fw'),
        'choice-2' => __('Choice 2', 'fw'),
        'choice-3' => __('Choice 3', 'fw'),
    ),
    /**
     * Set maximum items number that can be selected
     */
    'limit' => 100,
)

Multi¶

Option with another options in it.

array(
    'type'  => 'multi',
    'value' => array(
        'option-1' => 'value 1',
        'option-2' => 'value 2',
    ),
    'attr'  => array(
        'class' => 'custom-class',
        'data-foo' => 'bar',
        /*
        // Add this class to display inner options separators
        'class' => 'fw-option-type-multi-show-borders',
        */
    ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'inner-options' => array(
        'option-1' => array( 'type' => 'text' ),
        'option-2' => array( 'type' => 'textarea' ),
    )
)

Switch¶

Switch between two choices.

array(
    'type'  => 'switch',
    'value' => 'hello',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'left-choice' => array(
        'value' => 'goodbye',
        'label' => __('Goodbye', 'fw'),
    ),
    'right-choice' => array(
        'value' => 'hello',
        'label' => __('Hello', 'fw'),
    ),
)

Custom Events

fw:option-type:switch:change - Value was changed.

Color Picker¶

Pick a color.

array(
    'type'  => 'color-picker',
    'value' => '#FF0000',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Gradient¶

Pick gradient colors.

array(
    'type'  => 'gradient',
    'value' => array(
        'primary'   => '#FF0000',
        'secondary' => '#0000FF',
    )
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Background Image¶

Choose background image.

array(
    'type'  => 'background-image',
    'value' => 'bg-1',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'choices' => array(
        'none' => array(
            'icon' => get_template_directory_uri() . '/images/bg/bg-0.jpg',
            'css'  => array(
                'background-image' => 'none'
            ),
        ),
        'bg-1' => array(
            'icon'  => get_template_directory_uri() . '/images/bg/bg-1.jpg',
            'css'  => array(
                'background-image'  => 'url("' . get_template_directory_uri() . '/images/bg-1.png' . '")',
                'background-repeat' => 'repeat',
            ),
        ),
        'bg-2' => array(
            'icon' => get_template_directory_uri() . '/images/bg/bg-2.jpg',
            'css'  => array(
                'background-image'  => 'url("' . get_template_directory_uri() . '/images/bg-2.png' . '")',
                'background-repeat' => 'repeat-y'
            ),
        )
    )
)

Date Picker¶

Pick a date in calendar.

array(
    'type'  => 'date-picker',
    'value' => '',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'monday-first' => true, // The week will begin with Monday; for Sunday, set to false
    'min-date' => date('d-m-Y'), // By default minimum date will be current day. Set a date in format d-m-Y as a start date
    'max-date' => null, // By default there is not maximum date. Set a date in format d-m-Y as a start date
)

Image Picker¶

Pick an image.

array(
    'type'  => 'image-picker',
    'value' => 'image-2',
    'attr'  => array(
        'class'    => 'custom-class',
        'data-foo' => 'bar',
    ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'choices' => array(
        'value-1' => get_template_directory_uri() .'/images/thumbnail.png',
        'value-2' => array(
            // (required) url for thumbnail
            'small' => get_template_directory_uri() .'/images/thumbnail.png',
            // (optional) url for large image that will appear in tooltip
            'large' => get_template_directory_uri() .'/images/preview.png',
            // (optional) choice extra data for js, available in custom events
            'data' => array(...)
        ),
        'value-3' => array(
            // (required) url for thumbnail
            'small' => array(
                'src' => get_template_directory_uri() .'/images/thumbnail.png',
                'height' => 70
            ),
            // (optional) url for large image that will appear in tooltip
            'large' => array(
                'src' => get_template_directory_uri() .'/images/preview.png',
                'height' => 400
            ),
            // (optional) choice extra data for js, available in custom events
            'data' => array(...)
        ),
    ),
    'blank' => true, // (optional) if true, images can be deselected
)

Custom Events

fw:option-type:image-picker:clicked - A thumbnail was clicked.

fw:option-type:image-picker:changed - Value was changed.

Icon¶

Choose a FontAwesome icon.

array(
    'type'  => 'icon',
    'value' => 'fa-smile-o',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Upload¶

Single file upload.

array(
    'type'  => 'upload',
    'value' => array(
         'attachment_id' => '9',
         'url' => '//site.com/wp-content/uploads/2014/02/whatever.jpg'
    ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    /**
     * If set to `true`, the option will allow to upload only images, and display a thumb of the selected one.
     * If set to `false`, the option will allow to upload any file from the media library.
     */
    'images_only' => true,
)

Custom Events

fw:option-type:upload:change - The value was changed.

fw:option-type:upload:clear - The value was cleared (the selected item is removed).

Multi-Upload¶

Upload multiple files.

array(
    'type'  => 'multi-upload',
    'value' => array(
        array(
             'attachment_id' => '9',
             'url' => '//site.com/wp-content/uploads/2014/02/whatever.jpg'
        ),
        array(
             'attachment_id' => '10',
             'url' => '//site.com/wp-content/uploads/2014/02/random.jpg'
        ),
    ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    /**
     * If set to `true`, the option will allow to upload only images, and display a thumb of the selected one.
     * If set to `false`, the option will allow to upload any file from the media library.
     */
    'images_only' => true,
)

Custom Events

fw:option-type:multi-upload:change - The value was changed.

fw:option-type:multi-upload:clear - The value is cleared (all the selected items are removed).

fw:option-type:multi-upload:remove - A thumb (selected item) is removed. Triggered only when images_only is set to true.

Addable Option¶

Create a list of options.

array(
    'type'  => 'addable-option',
    'value' => array('Value 1', 'Value 2', 'Value 3'),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'option' => array( 'type' => 'text' ),
)

Custom Events

fw:option-type:addable-option:option:init - New option was added and initialized.

Addable Box¶

Addable box with options.

array(
    'type'  => 'addable-box',
    'value' => array(
        array(
            'option_1' => 'value 1',
            'option_2' => 'value 2',
        )
    ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    'box-options' => array(
        'option_1' => array( 'type' => 'text' ),
        'option_2' => array( 'type' => 'textarea' ),
    ),
    'template' => 'Hello {{- option_1 }}', // box title
    'box-controls' => array( // buttons next to (x) remove box button
        'control-id' => '<small class="dashicons dashicons-smiley"></small>',
    ),
    'limit' => 0, // limit the number of boxes that can be added
)

Custom Events

fw:option-type:addable-box:box:init - Box was initialized. Triggered for each existing box after page load, or when a box was added.

fw:option-type:addable-box:control:click - A custom control was clicked.

Addable Popup¶

Addable popup with options.

array(
    'type' => 'addable-popup',
    'label' => __('Addable Popup', 'fw'),
    'desc'  => __('Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', 'fw'),
    'template' => '{{- demo_text }}',
    'popup-options' => array(
        'demo_text' => array(
            'label' => __('Text', 'fw'),
            'type' => 'text',
            'value' => 'Demo text value',
            'desc' => __('Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', 'fw'),
            'help' => sprintf("%s \n\n'\"<br/><br/>\n\n <b>%s</b>",
                __('Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', 'fw'),
                __('Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium', 'fw')
            ),
        ),
        'demo_textarea' => array(
            'label' => __('Textarea', 'fw'),
            'type' => 'textarea',
            'value' => 'Demo textarea value',
            'desc' => __('Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', 'fw'),
            'help' => sprintf("%s \n\n'\"<br/><br/>\n\n <b>%s</b>",
                __('Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', 'fw'),
                __('Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium', 'fw')
            ),
        ),
    ),
)

Typography¶

Choose font family, size, style and color.

array(
    'type'  => 'typography',
    'value' => array(
        'family' => 'Arial',
        'size'   => 12,
        'style'  => '400',
        'color'  => '#000000'
    )
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

WP Editor¶

Textarea with the WordPress Editor like the one you use on the blog posts edit pages.

array(
    'type'  => 'wp-editor',
    'value' => 'default value',
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
    /**
     * Load TinyMCE, can be used to pass settings directly to TinyMCE using an array
     * bool|array
     */
    'tinymce' => true,
    /**
     * Whether to display media insert/upload buttons
     * boolean
     */
    'media_buttons' => true,
    /**
     * Whether to output the minimal editor configuration used in PressThis
     * boolean
     */
    'teeny' => false,
    /**
     * Whether to use wpautop for adding in paragraphs
     * boolean
     */
    'wpautop' => true,
    /**
     * Additional CSS styling applied for both visual and HTML editors buttons, needs to include <style> tags, can use "scoped"
     * string
     */
    'editor_css' => '',
    /**
     * If smething goes wrong try set to true
     * boolean
     */
    'reinit' => false,
)

Multi-Picker¶

Pick a choice, then complete options related to that choice.

The picker parameter holds a valid option type with choices. Supported option types are select, radio, image-picker and switch.

array(
    'type'  => 'multi-picker',
    'label' => false,
    'desc'  => false,
    'value' => array(
        /**
         * '<custom-key>' => 'default-choice'
         */
        'gadget' => 'phone',

        /**
         * These are the choices and their values,
         * they are available after option was saved to database
         */
        'laptop' => array(
            'price' => '123',
            'webcam' => false
        ),
        'phone' => array(
            'price' => '456',
            'memory' => '32'
        )
    ),
    'picker' => array(
        // '<custom-key>' => option
        'gadget' => array(
            'label'   => __('Choose device', 'fw'),
            'type'    => 'select',
            'choices' => array(
                'phone'  => __('Phone', 'fw'),
                'laptop' => __('Laptop', 'fw')
            ),
            'desc'    => __('Description', 'fw'),
            'help'    => __('Help tip', 'fw'),
        )
    ),
    /*
    'picker' => array(
        // '<custom-key>' => option
        'gadget' => array(
            'label'   => __('Choose device', 'fw'),
            'type'    => 'radio',
            'choices' => array(
                'phone'  => __('Phone', 'fw'),
                'laptop' => __('Laptop', 'fw')
            ),
            'desc'    => __('Description', 'fw'),
            'help'    => __('Help tip', 'fw'),
        )
    ),
    */
    /*
    'picker' => array(
        // '<custom-key>' => option
        'gadget' => array(
            'label'   => __('Choose device', 'fw'),
            'type'    => 'image-picker',
            'choices' => array(
                'phone'  => 'http://placekitten.com/70/70',
                'laptop' => 'http://placekitten.com/71/70'
            ),
            'desc'    => __('Description', 'fw'),
            'help'    => __('Help tip', 'fw'),
        )
    ),
    */
    /*
    picker => array(
        // '<custom-key>' => option
        'gadget' => array(
            'label' => __('Choose device', 'fw'),
            'type'  => 'switch',
            'right-choice' => array(
                'value' => 'laptop',
                'label' => __('Laptop', 'fw')
            ),
            'left-choice' => array(
                'value' => 'phone',
                'label' => __('Phone', 'fw')
            ),
            'desc' => __('Description', 'fw'),
            'help' => __('Help tip', 'fw'),
        )
    ),
    */
    'choices' => array(
        'phone' => array(
            'price' => array(
                'type'  => 'text',
                'label' => __('Price', 'fw'),
            ),
            'memory' => array(
                'type'  => 'select',
                'label' => __('Memory', 'fw'),
                'choices' => array(
                    '16' => __('16Gb', 'fw'),
                    '32' => __('32Gb', 'fw'),
                    '64' => __('64Gb', 'fw'),
                )
            )
        ),
        'laptop' => array(
            'price' => array(
                'type'  => 'text',
                'label' => __('Price', 'fw'),
            ),
            'webcam' => array(
                'type'  => 'switch',
                'label' => __('Webcam', 'fw'),
            )
        ),
    ),
    /**
     * (optional) if is true, the borders between choice options will be shown
     */
    'show_borders' => false,
)

Map¶

Google maps location.

array(
    'type'  => 'map',
    'value' => array(
        'coordinates' => array(
            'lat'   => -34,
            'lng'   => 150,
        )
    ),
    'attr'  => array( 'class' => 'custom-class', 'data-foo' => 'bar' ),
    'label' => __('Label', 'fw'),
    'desc'  => __('Description', 'fw'),
    'help'  => __('Help tip', 'fw'),
)

Disable Extension¶

An extension can be disabled by adding it to the blacklist. Blacklist is an array in theme config:

// file: framework-customizations/theme/config.php

$cfg['extensions_blacklist'] = array('extension_name', 'another_extension_name');

Disable Child Extensions¶

Child extensions will not be activated if parent extension will return false; from _init().

<?php if (!defined('FW')) die('Forbidden');

class FW_Extension_Example extends FW_Extension
{
    /**
     * @internal
     */
    protected function _init()
    {
        // ...

        if ($this->something_is_wrong()) {
            return false; // prevent child extensions activation
        }
    }
}

Validate Child Extensions¶

The parent extension has the possibility to check each child extension if it’s valid or not. If the child extension is not valid, it will not be activated. To do that, the parent extension must overwrite the _child_extension_is_valid() method.

The method should return true if child extension is valid, and false if not.

<?php if (!defined('FW')) die('Forbidden');

class FW_Extension_Example extends FW_Extension
{
    /**
     * {@inheritdoc}
     */
    public function _child_extension_is_valid($child_extension_instance)
    {
        // force child extensions to extend some custom class, instead of FW_Extension
        return is_subclass_of($child_extension_instance, 'FW_Ext_Demo_Custom_Class');
    }

    // ...
}

General¶

General PHP helpers:

• fw_print($value, $die = false) - styled version of print_r().

• fw_html_tag($tag, $attr = null, $end = null) - generate html tag.

  echo fw_html_tag('script', array('src' => '/demo.js'), true);
  
  // <script src="/demo.js"></script>
  

• fw_attr_to_html(array $attr_array) - generate html attributes from array.

  echo '<div '. fw_attr_to_html(array('id' => 'foo', 'class' => 'bar')) .'></div>';
  
  // <div id="foo" class="bar" ></div>
  

• fw_akg($keys, &$array_or_object, $default_value = null, $keys_delimiter = '/') - get array multikey value.

  Note

  MultiKey is a string composed from multiple array keys, separated by a delimiter character, that represents an array structure. For example

  'a/b/c'
  

  represents

  array(
      'a' => array(
          'b' => array(
              'c' => null
          )
      )
  )
  

  $demo = array(
      'a' => array(
          'b' => 'hello'
      )
   );
  
  echo fw_akg('a/b', $demo);
  
  // 'hello'
  

• fw_aks($keys, $value, &$array_or_object, $keys_delimiter = '/') - set a multikey value in array.

  $demo = array(
      'a' => array()
  );
  
  fw_aks('a/b', 'hello', $demo);
  
  print_r($demo);
  
  /*
  array(
      'a' => array(
          'b' => 'hello'
      )
  )
  */
  

• fw_aku($keys, &$array_or_object, $keys_delimiter = '/') - unset a multikey from array.

  $demo = array(
      'a' => array(
          'b' => array()
      )
  );
  
  fw_aku('a/b', $demo);
  
  print_r($demo);
  
  /*
  array(
      'a' => array()
  )
  */
  

• fw_rand_md5() - generate a random md5.

• fw_unique_increment() - random number incremented every time you call the function.

  echo fw_unique_increment(), PHP_EOL;
  echo fw_unique_increment(), PHP_EOL;
  echo fw_unique_increment(), PHP_EOL;
  
  /*
  9370
  9371
  9372
  */
  

• fw_stripslashes_deep_keys($value) - strip slashes (recursive) from values and keys (if value is array) if magic_quotes_gpc = On.

• fw_addslashes_deep_keys($value) - add slashes (recursive) to values and keys (if value is array) if magic_quotes_gpc = On.

• fw_current_screen_match($rules) - check if current global $current_screen; (available in admin side) matches the given rules. Used to detect on which admin page you currently are. Thus you can for example enqueue a script only on a target page, not on all admin pages.

  /**
   * @internal
   */
  function _action_enqueue_demo_admin_scripts() {
      // To find out what is the current screen of the current page, uncomment next line
      //global $current_screen; fw_print($current_screen);
  
      $only = array(
          'only' => array(
              array( 'id' => 'dashboard' )
          )
      );
  
      if (fw_current_screen_match($only)) {
          // enqueue this script only on dashboard page
          wp_enqueue_script(
              'demo-dashboard',
              fw_get_stylesheet_customizations_directory_uri('/js/demo-only.js')
          );
      }
  
      $exclude = array(
          'exclude' => array(
              array( 'id' => 'dashboard' ),
              array( 'post_type' => 'post' )
          )
      );
  
      if (fw_current_screen_match($exclude)) {
          // enqueue this script on all admin pages
          // except dashboard page and all pages from posts menu (add, edit, categories, tags)
          wp_enqueue_script(
              'demo-dashboard',
              fw_get_stylesheet_customizations_directory_uri('/js/demo-excluded.js')
          );
      }
  }
  add_action('admin_enqueue_scripts', '_action_enqueue_demo_admin_scripts');
  

  Note

  You can combine only and exclude in the same rules array.

• fw_locate_theme_path_uri($rel_path) - search by relative path, in child then in parent theme directory, and return URI.

  echo fw_locate_theme_path_uri('/styles.css');
  
  // http://your-site.com/wp-content/themes/child-theme/style.css
  

• fw_locate_theme_path($rel_path) - search by relative path, in child then in parent theme directory, and return full path.

  echo fw_locate_theme_path('/styles.css');
  
  // /var/www/wordpress/public_html/wp-content/themes/child-theme/style.css
  

• fw_render_view($file_path, $view_variables = array()) - safe render view and return html. In view will be accessible only passed variables, not current context variables.

  $private = 'Top Secret';
  
  echo fw_render_view(
      get_stylesheet_directory() .'/demo-view.php',
      array('message' => 'Hello')
  );
  
  /* demo-view.php
  <?php if (!defined('FW')) die('Forbidden');
  
  echo $message;
  echo $private;
  */
  
  // Hello
  // Notice: Undefined variable: private
  

• fw_get_variables_from_file($file_path, array $variables) - extract specified variables from file.

  $variables = fw_get_variables_from_file(
      get_stylesheet_directory() .'/demo-variables.php',
      array(
          'message' => 'Hi',
          'foo' => 'bar'
      )
  );
  
  /* demo-variables.php
  <?php if (!defined('FW')) die('Forbidden');
  
  $message = 'Hello';
  */
  
  print_r($variables);
  
  /*
  array(
      'message' => 'Hello',
      'foo' => 'bar'
  )
  */
  

• fw_include_file_isolated($file_path) - include files isolated and don’t give access to current context variables.

  $private = 'Top Secret';
  
  fw_include_file_isolated(get_stylesheet_directory() .'/demo-isolated.php');
  
  /* demo-isolated.php
  <?php if (!defined('FW')) die('Forbidden');
  
  echo $private;
  */
  
  // Notice: Undefined variable: private
  

• fw_html_attr_name_to_array_multi_key($attr_name) - convert html name attribute to multikey.

  echo fw_html_attr_name_to_array_multi_key('a[b][c]');
  
  // 'a/b/c'
  

• fw_is_real_post_save() - used in ‘save_post’ action to detect if it’s a real post save, not a revision, auto save or something else.

• fw_current_url() - generate current page url from $_SERVER data.

• fw_is_valid_domain_name($domain_name) - check if a domain name is valid.

• fw_htmlspecialchars($string) - UTF-8 version of php’s htmlspecialchars(). Just a shorthand not to write two more parameters for default htmlspecialchars() every time.

  Note

  In php 5.2 htmlspecialchars() default encoding is not UTF-8.

• fw_human_time($seconds) - convert seconds to human readable time.

  echo fw_human_time(12345);
  
  // '3 hours'
  

• fw_strlen($string) - UTF-8 version of php’s strlen().

  echo strlen('Привет!'), PHP_EOL;
  echo fw_strlen('Привет!'), PHP_EOL;
  
  // 13
  // 7
  

• fw_is_post_edit() - check if you are currently on a post edit page. It also detects if form submit was made from the post edit page.

• fw_dirname_to_classname($dirname) - convert directory name to string to be used as/in class name.

  echo 'FW_'. fw_dirname_to_classname('hello-world');
  
  // FW_Hello_World
  

• fw_fix_path($path) - make sure a path is in unix style, with / directory separators.

• fw_get_stylesheet_customizations_directory() - Full path to the child-theme/framework-customizations directory.

• fw_get_stylesheet_customizations_directory_uri() - URI to the child-theme/framework-customizations directory.

• fw_get_template_customizations_directory() - Full path to the parent-theme/framework-customizations directory.

• fw_get_template_customizations_directory_uri() - URI to the parent-theme/framework-customizations directory.

• fw_get_framework_directory() - Full path to the parent-theme/framework directory.

• fw_get_framework_directory_uri() - URI to the parent-theme/framework directory

Cache¶

Use cache to store frequently accessed data. Cache is just a big array and has one useful feature: it will automatically begin to unset array keys if the php memory is close to full. So it is safe to store in it as much data as you want (of course the maximum allowed by php, by default is ~100Mb).

function get_foo_bar() {
    $cache_key = 'foo/bar';

    try {
        /**
         * This will throw an exception if the key was not found
         */
        return FW_Cache::get($cache_key);
    } catch (FW_Cache_Not_Found_Exception $e) {
        $data = _generate_foo_bar_data();

        FW_Cache::set($cache_key, $data);

        return $data;
    }
}

    ...
} catch (FW_Cache_Not_Found_Exception $e) {
    FW_Cache::set($cache_key, _generate_foo_bar_data());

    return FW_Cache::get($cache_key);
}

Options¶

Functions for working with options:

• fw_extract_only_options(array $options) - extract only regular options from any array of options.

  $options = array(
      array(
          'type' => 'box',
          'options' => array(
              'demo-1' => array(
                  'type' => 'text'
              )
          )
      ),
      array(
          'type' => 'box',
          'options' => array(
              array(
                  'type' => 'tab',
                  'options' => array(
                      'demo-2' => array(
                          'type' => 'textarea'
                      )
                  )
              )
          )
      )
  );
  
  print_r( fw_extract_only_options($options) );
  
  /*
  array(
      'demo-1' => array(
          'type' => 'text'
      ),
      'demo-2' => array(
          'type' => 'textarea'
      )
  )
  */
  

• fw_get_options_values_from_input(array $options, $input_array = null) - extract options values from input array. If no input array is provided, values from $_POST will be used.

  $options = array(
      'demo-1' => array( 'type' => 'text', 'value' => 'default value 1' ),
      'demo-2' => array( 'type' => 'text', 'value' => 'default value 2' ),
  );
  
  $input_values = array(
      'demo-1' => 'input value 1',
      'demo-3' => 'input value 3',
  );
  
  $values = fw_get_options_values_from_input($options, $input_values);
  
  print_r($values);
  
  /*
  array(
      'demo-1' => 'input value 1',
      'demo-2' => 'default value 2',
  )
  */
  

• fw_prepare_option_value($value) - by default WordPress offers filters for other plugins to alter database options and post meta. For ex translation plugins use these filters to translate things. If you save your options values in a custom place (like framework does by default, by saving options in a serialized array in database options and post meta) the WordPress filter doesn’t know how to work with them.

  Tip

  Use this function to pass an option value through filters and translation features that simulates WordPress default behavior. This function is already used in core so you don’t have to bother about passing options values through it each time. Use it if you will do something custom and strings will not be translated.

Database¶

Functions and classes for working with database:

• FW_WP_Option - alternative to WordPress get_option() and update_option() functions.

  Note

  Features:

  • Supports multikeys
  • The value is stored in two formats: original and prepared. Prepared is used for frontend because it is translated.

• FW_WP_Post_Meta - alternative to WordPress get_post_meta() and update_post_meta().

  Note

  Features:

  • Supports multikeys
  • The value is stored in two formats: original and prepared. Prepared is used for frontend because it is translated.

• fw_get_db_settings_option($option_id, $default_value = null) - get value from the database of an option from the framework’s settings page. Settings options are located in framework-customizations/theme/options/settings.php.

• fw_set_db_settings_option($option_id, $value) - set a value in the database for an option from the framework’s settings page.

• fw_get_db_post_option($post_id, $option_id, $default_value = null) - get a post option value from the database. Post options are located in framework-customizations/theme/options/posts/{post-type}.php.

• fw_set_db_post_option($post_id, $option_id, $value) - set a post option value in the database.

• fw_get_db_term_option($term_id, $taxonomy, $option_id, $default_value = null) - get a term option value from the database. Term options are located in framework-customizations/theme/options/taxonomies/{taxonomy}.php.

• fw_set_db_term_option($term_id, $taxonomy, $option_id, $value) - set a term option value in the database.

• fw_get_db_extension_data($extension_name, $key, $default_value = null) - get a value from the database of some data stored by some extension.

• fw_set_db_extension_data($extension_name, $key, $value) - extensions uses this function to store custom values in the database.

  Important

  All values are stored in one wp option. This prevents database spam with wp options for each extension.

FW_Form¶

A convenient way to create forms. You can create a form class instance and give it three callbacks that control the render, validate and save process.

$my_form = new FW_Form('<unique-id>', array(
    'render'   => '_my_form_render',
    'validate' => '_my_form_validate',
    'save'     => '_my_form_save',
));

function _my_form_render() {
    $input_value = FW_Request::POST('demo');

    echo '<input type="text" name="demo" maxlength="10" value="'. esc_attr($input_value) .'">';
}

function _my_form_validate($errors) {
    $input_value = FW_Request::POST('demo');

    if (fw_strlen($input_value) > 10) {
        $errors['demo'] = __('Value cannot be more that 10 characters long', 'fw');
    }

    return $errors;
}

function _my_form_save() {
    $input_value = FW_Request('demo');

    // do something with value
}

echo $my_form->render();
// this will output:
// <form ... ><input type="text" name="demo" maxlength="10" value=""></form>

General¶

General javaScript helpers:

• fw.FW_URI - URI to the framework directory.

• fw.SITE_URI - URI to the site root directory.

• fw.intval(value) - alternative to php intval(). Returns 0 on failure, instead of NaN like parseInt() does.

• fw.md5(string) - calculate md5 hash of the string.

• fw.loading - show loading on the page.

  Tip

  Useful when doing AJAX requests and want to inform your users about that.

  fw.loading.show();
  
  setTimeout(function(){
      fw.loading.hide();
  }, 3000);
  

  The show() and hide() methods can be called multiple times. If show() is called 10 times, then hide() should be called 10 times for loading to disappear. This is done for cases when this helper is used by multiple asynchronous scripts, the loading should not disappear until all scripts complete the work.

• fw.capitalizeFirstLetter(text) - capitalizes the first letter of a string.

• fw.ops(properties, value, obj, delimiter) - same as fw_aks(...) from PHP Helpers, but for javascript objects.

  var obj = {foo: {}};
  
  fw.ops('foo/bar', 'demo', obj);
  
  console.log(obj); // {foo: {bar: 'demo'}}
  

• fw.opg(properties, obj, defaultValue, delimiter) - same as fw_akg(...) from PHP Helpers, but for javascript objects.

  var obj = {foo: {bar: 'hello'}};
  
  console.log( fw.opg('foo/bar', obj) ); // 'hello'
  

• fw.randomMD5() - generate random md5.

Options Modal¶

Modal with options. Display html generated from a given options array. After the user completes the form and presses “Save”, values are available as a javascript object.

var modal = new fw.OptionsModal({
    title: 'Custom Title',
    options: [
        {'test_1': {
            'type': 'text',
            'label': 'Test1'
        }},
        {'test_2': {
            'type': 'textarea',
            'label': 'Test2'
        }}
    ],
    values: {
        'test_1': 'Default 1',
        'test_2': 'Default 2'
    },
    size: 'small' // 'medium', 'large'
});

// listen for values change
modal.on('change:values', function(modal, values) {
    console.log(values);
});

// replace values
modal.set('values', {
    'test_1': 'Custom 1',
    'test_2': 'Custom 2'
});

modal.open();

fw()->backend->enqueue_options_static($modal_options);

Events¶

fwEvents is a global object on which you can trigger or listen custom events. This way different scripts can communicate with each other.

// script-1.js

fwEvents.on('script-2:message', function(data){
    console.log('script-1 received a message from script-2: '+ data.message);
});

// script-2.js

fwEvents.trigger('script-2:message', {message: 'Hello World!'});

General¶

<p class="fw-text-left">Left aligned text.</p>
<p class="fw-text-center">Center aligned text.</p>
<p class="fw-text-right">Right aligned text.</p>
<p class="fw-text-justify">Justified text.</p>
<p class="fw-text-nowrap">No wrap text.</p>

<p class="fw-text-lowercase">Lowercased text.</p>
<p class="fw-text-uppercase">Uppercased text.</p>
<p class="fw-text-capitalize">Capitalized text.</p>

<img  src="..."  class="fw-img-responsive"  alt="image Responsive" >

<a href="#" class="dashicons fw-x"></a>

<div class="fw-pull-left">...</div>
<div class="fw-pull-right">...</div>

<div class="fw-center-block">...</div>

<div class="fw-clearfix">...</div>

<div class="fw-show">...</div>
<div class="fw-hidden">...</div>

<h1 class="fw-text-hide">Custom heading</h1>

Grid system¶

Css helpers includes a responsive, fluid grid system that appropriately scales up to 12 columns as the device or viewport size increases. Grid systems are used for creating layouts through a series of rows and columns that house your content. Here’s how the grid system works:

• Use rows to create horizontal groups of columns.
• Content should be placed within columns, and only columns may be immediate children of rows.
• Predefined grid classes like .fw-row and .fw-col-xs-4 are available for quickly making grid layouts.
• Grid columns are created by specifying the number of twelve available columns you wish to span. For example, three equal columns would use three .fw-col-xs-4.
• If more than 12 columns are placed within a single row, each group of extra columns will, as one unit, wrap onto a new line.
• Grid classes apply to devices with screen widths greater than or equal to the breakpoint sizes, and override grid classes targeted at smaller devices. Therefore, applying any .fw-col-md- class to an element will not only affect its styling on medium devices but also on large devices if a .fw-col-lg- class is not present.

This grid system was inspired from bootstrap with some modifications:

• Added .fw- prefix to classes
• Changed media queries screen sizes
• Rows are used without containers (no .container and .container-fluid)
• Rows have no padding

/* Extra small devices (phones) */
@media (max-width: 782px) { ... }

/* Small devices (tablets) */
@media (min-width: 783px) and (max-width: 900px) { ... }

/* Medium devices (desktops) */
@media (min-width: 901px) and (max-width: 1199px) { ... }

/* Large devices (large desktops) */
@media (min-width: 1200px) { ... }

Responsive utilities¶

For faster mobile-friendly development, use these utility classes for showing and hiding content by device via media query.

Directory structure¶

A shortcode can be created in the following places:

• framework-customizations/theme/shortcodes/
• {some-extension}/shortcodes/

{shortcode-name}/
├─class-fw-shortcode-{shortcode-name}.php # optional
├─config.php
├─options.php # optional
├─static/ # optional
│ ├─css/
│ │ ├─auto-enqueued-style.css
│ │ └─...
│ ├─img/
│ │ ├─layout_builder.png
│ │ └─...
│ └─js/
│   ├─auto-enqueued-script.js
│   └─...
└─views/
  ├─view.php
  └─...

The framework will register a new WordPress shortcode with its tag being the shortcode directory name, with hyphens replaced by underscores ([shortcode_name] for the above example).

Config File¶

The shortcode configuration is a file named config.php placed inside the root directory of the shortcode. It contains an array that must be stored in a $cfg variable:

$cfg = array(
    'layout_builder' => array(
        'title'         => __('Demo Shortcode', 'fw'),
        'description'   => __('Demo shortcode description', 'fw'),
        'tab'           => __('Demo Elements', 'fw'),
        'popup_size'    => 'small' // can be 'large', 'medium' or 'small'
    )
);

For the shortcode to appear in the layout builder, the config array contains a special layout_builder key that holds an array with the following data:

• title - the title that will appear in the shortcode box.

• description - the text that will be shown in a tooltip when hovering the shortcode box.

• tab - the builder tab in which the shortcode box will appear.

• popup_size - the size of the popup in which the shortcode options will be displayed.

  Allowed values are large | medium | small. This parameter is optional and the default is set to medium.

Builder icon¶

To set an icon for the shortcode box, put an image named layout_builder.png inside {your-shortcode}/static/img/ directory. The image should have the size of 16x16 px.

Options file¶

The shortcode directory can contain a file named options.php with correctly formed options:

$options = array(
    'demo_text'   => array(
        'label'   => __('Demo text label', 'fw'),
        'desc'    => __('Demo text description', 'fw'),
        'help'    => __('Demo text help', 'fw'),
        'type'    => 'text'
    ),
    'demo_select' => array(
        'label'   => __('Demo select label', 'fw'),
        'desc'    => __('Demo select description', 'fw'),
        'type'    => 'select',
        'choices' => array(
            'c1'  => __('Choice 1', 'fw'),
            'c2'  => __('Choice 2', 'fw'),
            'c3'  => __('Choice 3', 'fw')
        ),
        'value'   => 'c2'
    )
);