Downloads
Stars
Version
A simple framework for creating WordPress options page.
#Basic Usage
Here is an example for creating an options page.
use Laraish\Options\OptionsPage;
$optionsPage = new OptionsPage([
'menuSlug' => 'my_options_page',
'menuTitle' => 'My Options Page',
'pageTitle' => 'My Options Page',
'iconUrl' => 'dashicons-welcome-learn-more',
'optionGroup' => 'my_options_page',
'optionName' => 'my_options',
'capability' => 'manage_categories',
'sections' => [
[
'id' => 'section-id',
'title' => 'Section title',
'description' => 'Section Description',
'fields' => [
[
'id' => 'my-avatar',
'type' => 'media',
'title' => 'Avatar',
'description' => 'Choose an image for your avatar.'
],
[
'id' => 'my-email',
'type' => 'email',
'title' => 'E-mail',
],
[
'id' => 'my-nice-name',
'type' => 'text',
'title' => 'Nice name',
'attributes' => [
'placeholder' => 'your nice name',
'maxlength' => 10,
'class' => 'regular-text'
],
],
[
'id' => 'my-description',
'type' => 'textarea',
'title' => 'About Me',
],
]
]
],
'helpTabs' => [
[
'title' => 'tab-1',
'content' => '<p>description here</p>',
],
[
'title' => 'tab-2',
'content' => '<p>description here</p>',
]
],
'scripts' => ['https://unpkg.com/vue/dist/vue.js'],
'styles' => ['/my-css.css'],
]);
$optionsPage->register();
The example code above is going to create an options page looks like this
OptionsSection
and OptionsField
You can also replace the value of 'sections'
with an array of OptionsSection
objects and replace the value of 'fields'
with an array of OptionsField
objects.
use Laraish\Options\OptionsPage;
/*------------------------------------*\
# Field objects
\*------------------------------------*/
$avatarField = new OptionsField([
'id' => 'my-avatar',
'type' => 'media',
'title' => 'Avatar',
'description' => 'Choose an image for your avatar.'
]);
$emailField = new OptionsField([
'id' => 'my-email',
'type' => 'email',
'title' => 'E-mail',
]);
$niceNameField = new OptionsField([
'id' => 'my-nice-name',
'type' => 'text',
'title' => 'Nice name',
'attributes' => [
'placeholder' => 'your nice name',
'maxlength' => 10,
'class' => 'regular-text'
]
]);
$descriptionField = new OptionsField([
'id' => 'my-description',
'type' => 'textarea',
'title' => 'About Me',
]);
$demoField = new OptionsField([
'id' => 'my-demo',
'type' => 'text',
'title' => 'Demo text field',
]);
/*------------------------------------*\
# Section object
\*------------------------------------*/
$demoSection = new OptionsSection([
'id' => 'section-id',
'title' => 'Section title',
'description' => 'Section Description',
'fields' => [
$demoField,
]
]);
/*------------------------------------*\
# Page object
\*------------------------------------*/
$optionsPage = new OptionsPage([
'menuSlug' => 'my_options_page',
'menuTitle' => 'My Options Page',
'pageTitle' => 'My Options Page',
'iconUrl' => 'dashicons-welcome-learn-more',
'optionGroup' => 'my_options_page',
'optionName' => 'my_options',
'capability' => 'manage_categories',
'sections' => [
[
'id' => 'section-id',
'title' => 'Section title',
'description' => 'Section Description',
'fields' => [
$avatarField,
$emailField,
$niceNameField,
$descriptionField,
]
],
$demoSection,
],
'helpTabs' => [
[
'title' => 'tab-1',
'content' => '<p>description here</p>',
],
[
'title' => 'tab-2',
'content' => '<p>description here</p>',
]
],
'scripts' => ['https://unpkg.com/vue/dist/vue.js'],
'styles' => ['/my-css.css'],
]);
/*------------------------------------*\
# register page/section/field
\*------------------------------------*/
// register page
$optionsPage->register();
// register a section to a page(Settings -> General)
$demoSection->register('general', 'demo-section-group', 'demo-section-options');
// register a field to a section of page(Settings -> General -> `default` section)
$demoField->register('general', 'default', 'demo-section-group', 'demo-section-options');
You can use the OptionsRepository
to get the value of an option.
use Laraish\Options\OptionsRepository;
// Get the value of 'my-nice-name' in 'my_options'.
// 'my_options' is the option name.
$myOptions = new OptionsRepository('my_options');
echo $myOptions->get('my-nice-name');
// also you can set the value by calling the set() method.
$myOptions->set('my_options','new value');
OptionsPage
menuSlug
Type | required |
---|---|
string | yes |
The slug name to refer to the menu by (should be unique for this menu).
menuTitle
Type | required |
---|---|
string | yes |
The text to be used for the menu.
pageTitle
Type | required |
---|---|
string | yes |
The text to be displayed in the title tags of the page when the menu is selected.
optionGroup
Type | required |
---|---|
string | yes |
The option group you wish to use in the page.
optionName
Type | required |
---|---|
string | yes |
The option name you wish to use in the page.
capability
Type | Default |
---|---|
string | 'manage_options' |
The capability required for this menu to be displayed to the user.
position
Type | Default |
---|---|
int | null |
The position in the menu order this one should appear.
iconUrl
Type | Default |
---|---|
string | '' |
The URL (or icon name) to the icon to be used for the menu.
parent
Type | Default |
---|---|
null / string / OptionsPageContract | null |
If you wish to make the page as a sub-page of a top-level page, set the top top-level page here.
sections
Type | Default |
---|---|
array | [] |
Settings-Sections to be inserted into the page. Every element of this array represents a Settings-Section.
See Options for OptionsSection for more details.
renderFunction
Type | Default |
---|---|
callable | null |
The function to be called to output the content for the page.
This function retrieves two arguments; the first one is an instance of OptionsPage
, the second one is an instance of OptionsForm
. By using the OptionsForm
object you can create form input elements much easier than by hard coding.
Below is an example of customizing the output of an options page.
use Laraish\Options\OptionsPage;
$optionsPage = new OptionsPage([
'menuSlug' => 'my_options_page',
'menuTitle' => 'My Options Page',
'pageTitle' => 'My Options Page',
'optionGroup' => 'my_options_page',
'optionName' => 'my_options',
'renderFunction' => function (OptionsPage $page, OptionsForm $form) {
?>
<div class="wrap">
<h1><?php echo $page->pageTitle(); ?></h1>
<form action="options.php" method="post" enctype="multipart/form-data">
<?php
// output security fields for the registered setting "{{ $this->optionGroup }}"
settings_fields($page->optionGroup());
// output fields
?>
<p><?php echo $form->email('email', ['attributes' => ['placeholder' => '[email protected]']]); ?></p>
<p><?php echo $form->textarea('about-us'); ?></p>
<?php
// output save settings button
submit_button();
?>
</form>
</div>
<?php
}
]);
helpTabs
Type | Default |
---|---|
array | [] |
The help tabs to be added to the page. Every tab represented by an array.
scripts
Type | Default |
---|---|
array | [] |
The scripts to be enqueued to the page.
styles
Type | Default |
---|---|
array | [] |
The styles to be enqueued to the page.
register()
Register the settings page.
OptionsSection
id
Type | required |
---|---|
string | yes |
ID of the section.
title
Type | required |
---|---|
string | yes |
Title of the section.
description
Type | Default |
---|---|
string | null |
Description of the section.
renderFunction
Type | Default |
---|---|
callable | null |
Function that fills the section with the desired content. The function should echo its output.
fields
Type | Default |
---|---|
array | [] |
settings fields in the section. See Options for OptionsField for more details.
capability
Type | Default |
---|---|
string | 'manage_options' |
The capability required for this section to be displayed to the current user.
register()
Register the settings page.
OptionsField
Type | Default |
---|---|
string | '' |
The ID of this field.
Type | Default |
---|---|
string | null |
The title of this field.
Type | Default |
---|---|
string | 'text' |
The type of the field. Default is 'text'. See Field types for more details.
Type | Default |
---|---|
string | 'manage_options' |
The capability required for this field to be displayed to the current user.
Type | Default |
---|---|
callable | null |
Function that fills the field with the desired content. The function should echo its output.
This function will be given an argument(array) with two elements field
(OptionsField) and form
(OptionsForm) object.
Type | Default |
---|---|
callable | null |
The sanitize function called before saving option data.
['placeholder'=> 'Type your name', 'class'=> 'foo bar baz']
.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
Same as Common Options.
false
if you want to put the checkboxes vertically.['Red'=> '#f00', 'Green'=> '#0f0', 'Blue'=> '#00f']
.Same as Checkboxes.
Same as Checkboxes.
true
if you are going to upload a json file.false
.