laraish / options
Package for creating options page in WordPress.
Installs: 4 958
Dependents: 2
Suggesters: 0
Security: 0
Stars: 10
Watchers: 3
Forks: 4
Open Issues: 2
Requires
- php: ^8.1
- laraish/contracts: ^3.0
- laraish/support: ^3.0
README
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
Usage of 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');
Get the value of an option
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
Options
menuSlug
The slug name to refer to the menu by (should be unique for this menu).
menuTitle
The text to be used for the menu.
pageTitle
The text to be displayed in the title tags of the page when the menu is selected.
optionGroup
The option group you wish to use in the page.
optionName
The option name you wish to use in the page.
capability
The capability required for this menu to be displayed to the user.
position
The position in the menu order this one should appear.
iconUrl
The URL (or icon name) to the icon to be used for the menu.
parent
If you wish to make the page as a sub-page of a top-level page, set the top top-level page here.
sections
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
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' => 'foo@example.com']]); ?></p> <p><?php echo $form->textarea('about-us'); ?></p> <?php // output save settings button submit_button(); ?> </form> </div> <?php } ]);
helpTabs
The help tabs to be added to the page. Every tab represented by an array.
scripts
The scripts to be enqueued to the page.
styles
The styles to be enqueued to the page.
Methods
register()
Register the settings page.
OptionsSection
Options
id
ID of the section.
title
Title of the section.
description
Description of the section.
renderFunction
Function that fills the section with the desired content. The function should echo its output.
fields
settings fields in the section. See Options for OptionsField for more details.
capability
The capability required for this section to be displayed to the current user.
Methods
register()
Register the settings page.
OptionsField
Options
id
The ID of this field.
title
The title of this field.
type
The type of the field. Default is 'text'. See Field types for more details.
capability
The capability required for this field to be displayed to the current user.
renderFunction
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.
sanitizeFunction
The sanitize function called before saving option data.
Field types
Common Options
- attributes (array)
- The attributes of the field element.
For example['placeholder'=> 'Type your name', 'class'=> 'foo bar baz']
. - defaultValue (mixed)
- The default value of the field.
Color
Same as Common Options.
Date
Same as Common Options.
Same as Common Options.
Hidden
Same as Common Options.
Number
Same as Common Options.
Password
Same as Common Options.
Range
Same as Common Options.
Search
Same as Common Options.
Textarea
Same as Common Options.
Text
Same as Common Options.
Time
Same as Common Options.
Url
Same as Common Options.
Checkboxes
- horizontal (true)
- The layout of the checkboxes. Set to
false
if you want to put the checkboxes vertically. - options ([])
- An array of options.
For example['Red'=> '#f00', 'Green'=> '#0f0', 'Blue'=> '#00f']
.
Checkbox
- text (string)
- The text of the checkbox.
- value (string)
- The value of the checkbox.
Radios
Same as Checkboxes.
Select
Same as Checkboxes.
File
- maxFileSize (string)
- The maximum file size (byte) of the file.
- isJson (bool)
- Set to
true
if you are going to upload a json file.
Default value isfalse
.
Media
- button_text (string)
- The text of the media uploader button.
- media_uploader_title (string)
- The title of media uploader.