A PHP class for building WordPress Option Pages. Uses multi-dimensional associative arrays to try and make the process of adding option pages a little easier to map out and use.
- Download or clone the repo
- Include
RationalOptionPages.phpin your file - Instantiate the class with your array of pages
if ( !class_exists( 'RationalOptionPages' ) ) {
require_once('RationalOptionPages.php');
}
$pages = array(
'sample-page' => array(
'page_title' => __( 'Sample Page', 'sample-domain' ),
),
);
$option_page = new RationalOptionPages( $pages );If you installed this previously and the class is already being instantiated somewhere else you will get fatal errors. You can avoid this by either renaming the class or by wrapping the require_once() in a if ( !class_exists() ) conditional.
Pages are added in a key/value syntax where the value is an array of parameters for the page itself.
Based on WordPress' add_menu_page() function.
page_title- The text string for the title of the page Required.menu_title- The text string for the menu item itself. Defaults topage_title.capability- The permissions required to access this page. Defaults tomanage_options.menu_slug- The "slug" of the menu item. Defaults to a "slugified" version of thepage_title.icon_url- The URL of the menu icon. WordPress' Dashicons are available. Defaults tofalse, renders "dashicons-admin-generic".position- The position where the menu item appears, from 1 to 99. Defaults tonull, last.
If your page title is more than 2 words I recommend using the menu_title parameter to avoid wrapping. The default capability should work for most plugins and themes as only the admin would typically make higher level changes like these.
Subpages are differentiated by the parent_slug parameter. They can be added either at the top level of the pages array submitted to the class or under a subpages key within another, top-level page parameter array.
Based on WordPress' add_submenu_page() function.
parent_slug- Themenu_slugof the parent page. WordPress has several top-level menu items. Required (unless added via thesubpageskey method).page_title- The text string for the title of the page. Required.menu_title- The text string for the menu item itself. Defaults topage_title.capability- The permissions required to access this page. Defaults tomanage_options.menu_slug- The "slug" of the menu item. Defaults to a "slugified" version of thepage_title.
require_once('RationalOptionPages.php');
$pages = array(
'sample-page' => array(
'page_title' => __( 'Sample Page', 'sample-domain' ),
// via the subpages key
'subpages' => array(
'sub-page-one' => array(
'page_title' => __( 'Sub Page One', 'sample-domain' ),
),
),
),
// via the pages array itself
'sub-page-two' => array(
'parent_slug' => 'sample_page',
'page_title' => __( 'Sub Page Two', 'sample-domain' ),
),
// sub page of the "Appearance" menu item
'sub-theme' => array(
'parent_slug' => 'themes.php',
'page_title' => __( 'Sub Theme', 'sample-domain' ),
),
);
$option_page = new RationalOptionPages( $pages );Sections are added via a sections key in the page parameter arrays.
Based on WordPress' add_settings_section() function.
title- The title of the section. Required.id- The ID of the section.callback- An optional parameter for generating custom, section content. Requirescustomparameter be set totrue.custom- A boolean option that indicates you want to use a custom callback. Defaults tofalse.text- An option parameter for adding HTML text under the section title.include- An option parameter that calls PHP'sinclude()under the section title. Use absolute path.
require_once('RationalOptionPages.php');
$pages = array(
'sample-page' => array(
'page_title' => __( 'Sample Page', 'sample-domain' ),
'sections' => array(
'section-one' => array(
'title' => __( 'Section One', 'sample-domain' ),
'text' => '<p>' . __( 'Some HTML text to describe the section', 'sample-domain' ) . '</p>',
'include' => plugin_dir_path( __FILE__ ) . '/your-include.php',
),
'section-two' => array(
'title' => __( 'Section Two', 'sample-domain' ),
'custom' => true,
'callback' => 'custom_section_callback_function',
),
),
),
);
$option_page = new RationalOptionPages( $pages );Fields are added via a fields key in the section parameter array.
Based on WordPress' add_settings_field() function.
title- The title/label of the field. Required.id- The ID of the field.callback- An optional parameter for generating custom, field content. Requirescustomparameter be set totrue.custom- A boolean option that indicates you want to use a custom callback. Defaults tofalse.type- The type of field to use. Most input types are available as well asselect,textarea,wp_editorandmedia(instead offileinput type).text- Help text for most input types. Label forcheckbox.title_attr- The "title" attribute of the input (if available).choices- Associative array of options for radio groups and select elements. Required forradioandselecttypes.placeholder- The placeholder attribute of the input (if available).value- The default value of the input.checked- A boolean for the default state of thecheckboxtype. Defaults tofalse.attributes- Associative array of additional attributes for the input element.- Input -
autocomplete, autofocus, disabled, list, max, maxlength, min, pattern, readonly, required, size and step - Select -
multiple, size - Textarea -
cols, rows and wrap
- Input -
sanitize- A boolean that indicates whether or not the field's value should be sanitized. Defaults tofalse, and doesn't apply to checkboxes.
The most basic of inputs.
require_once('RationalOptionPages.php');
$pages = array(
'sample-page' => array(
'page_title' => __( 'Sample Page', 'sample-domain' ),
'sections' => array(
'section-one' => array(
'title' => __( 'Section One', 'sample-domain' ),
'fields' => array(
'default' => array(
'title' => __( 'Default', 'sample-domain' ),
),
),
),
),
),
);
$option_page = new RationalOptionPages( $pages );Almost everything.
require_once('RationalOptionPages.php');
$pages = array(
'sample-page' => array(
'page_title' => __( 'Sample Page', 'sample-domain' ),
'sections' => array(
'section-one' => array(
'title' => __( 'Standard Inputs', 'sample-domain' ),
'fields' => array(
'default' => array(
'title' => __( 'Default (text)', 'sample-domain' ),
'text' => __( 'Text attributes are used as help text for most input types.' ),
),
'date' => array(
'title' => __( 'Date', 'sample-domain' ),
'type' => 'date',
'value' => 'now',
),
'datetime' => array(
'title' => __( 'Datetime-Local', 'sample-domain' ),
'type' => 'datetime-local',
'value' => 'now',
),
'datetime-local' => array(
'title' => __( 'Datetime-Local', 'sample-domain' ),
'type' => 'datetime-local',
'value' => 'now',
),
'email' => array(
'title' => __( 'Email', 'sample-domain' ),
'type' => 'email',
'placeholder' => 'email.address@domain.com',
),
'month' => array(
'title' => __( 'Month', 'sample-domain' ),
'type' => 'month',
'value' => 'now',
),
'number' => array(
'title' => __( 'Number', 'sample-domain' ),
'type' => 'number',
'value' => 42,
),
'password' => array(
'title' => __( 'Password', 'sample-domain' ),
'type' => 'password',
),
'search' => array(
'title' => __( 'Search', 'sample-domain' ),
'type' => 'search',
'placeholder' => __( 'Keywords or terms…', 'sample-domain' ),
),
'tel' => array(
'title' => __( 'Telephone', 'sample-domain' ),
'type' => 'tel',
'placeholder' => '(555) 555-5555',
),
'time' => array(
'title' => __( 'Time', 'sample-domain' ),
'type' => 'time',
'value' => 'now',
),
'url' => array(
'title' => __( 'URL', 'sample-domain' ),
'type' => 'url',
'placeholder' => 'http://jeremyhixon.com',
),
'week' => array(
'title' => __( 'Week', 'sample-domain' ),
'type' => 'week',
'value' => 'now',
),
),
),
'section-two' => array(
'title' => __( 'Non-standard Input', 'sample-domain' ),
'fields' => array(
'checkbox' => array(
'title' => __( 'Checkbox', 'sample-domain' ),
'type' => 'checkbox',
'text' => __( 'Text attributes are used as labels for checkboxes' ),
),
'color' => array(
'title' => __( 'Color', 'sample-domain' ),
'type' => 'color',
'value' => '#cc0000',
),
'media' => array(
'title' => __( 'Media', 'sample-domain' ),
'type' => 'media',
'value' => 'http://your-domain.com/wp-content/uploads/2016/01/sample.jpg',
),
'radio' => array(
'title' => __( 'Radio', 'sample-domain' ),
'type' => 'radio',
'value' => 'option-two',
'choices' => array(
'option-one' => __( 'Option One', 'sample-domain' ),
'option-two' => __( 'Option Two', 'sample-domain' ),
),
),
'range' => array(
'title' => __( 'Range', 'sample-domain' ),
'type' => 'range',
'value' => 75,
),
'select' => array(
'title' => __( 'Select', 'sample-domain' ),
'type' => 'select',
'value' => 'option-two',
'choices' => array(
'option-one' => __( 'Option One', 'sample-domain' ),
'option-two' => __( 'Option Two', 'sample-domain' ),
),
),
'select-multiple' => array(
'title' => __( 'Select multiple', 'sample-domain' ),
'type' => 'select',
'value' => array(
'option-two'
),
'choices' => array(
'option-one' => __( 'Option One', 'sample-domain' ),
'option-two' => __( 'Option Two', 'sample-domain' ),
'option-three' => __( 'Option Three', 'sample-domain' ),
),
'attributes' => array(
'multiple' => 'multiple'
),
'sanitize' => true
),
'textarea' => array(
'title' => __( 'Textarea', 'sample-domain' ),
'type' => 'textarea',
'value' => 'Pellentesque consectetur volutpat lectus, ac molestie lorem molestie nec. Vestibulum in auctor massa. Vivamus convallis nunc quis lacus maximus, non ultricies risus gravida. Praesent ac diam imperdiet, volutpat nisi sed, semper eros. In nec orci hendrerit, laoreet nunc eu, semper magna. Curabitur eu lorem a enim sodales consequat. Vestibulum eros nunc, congue sed blandit in, maximus eu tellus.',
),
'wp_editor' => array(
'title' => __( 'WP Editor', 'sample-domain' ),
'type' => 'wp_editor',
'value' => 'Pellentesque consectetur volutpat lectus, ac molestie lorem molestie nec. Vestibulum in auctor massa. Vivamus convallis nunc quis lacus maximus, non ultricies risus gravida. Praesent ac diam imperdiet, volutpat nisi sed, semper eros. In nec orci hendrerit, laoreet nunc eu, semper magna. Curabitur eu lorem a enim sodales consequat. Vestibulum eros nunc, congue sed blandit in, maximus eu tellus.',
),
),
),
),
),
);
$option_page = new RationalOptionPages( $pages );Each page stores it's fields in an entry in the database. The key is the array key for your page.
Using the example above as a reference:
// Get all options for the page
$options = get_option( 'sample-page', array() );
// Each field id is a key in the options array
$date = $options['date'];
$tel = $options['telephone'];If you let the class generate the field IDs then they will be "slugified" versions of the title parameter. For example; a field with the title of "Website Address" will have an ID of "website_address". You can also see this key by inspecting the input and looking at the input's name attribute. Within the square ([]) brackets.
- Add
textandincludeparameters to pages.