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.

Email

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 is false.

Media

button_text (string)

The text of the media uploader button.

media_uploader_title (string)

The title of media uploader.