Metapress Framework

Options page ​

The options page is a page that allows users of your plugin to configure the plugin. Metapress provides a set of classes and functions to help you build this page.

WARNING

The framework supports only one single options page. You cannot instantiate multiple options pages. Additional pages will need to be created manually.

How it works ​

The options page is made of tabs. Each tab can have multiple sections. Each section can have multiple fields. Options are then saved in the database via the OptionsRoute REST API class and make use of the Options service class.

Defining sections ​

Sections are defined by using the Section class. Each section takes a title and Form class as arguments. The Form class is used to define the fields of the section.

php
$form = Form::make(
    [
        [
            'type' => 'toggle',
            'name' => 'toggle-field-example',
            'label' => __('Toggle Field'),
            'description' => __('This is a toggle field'),
            'tooltip' => [
                'text' => __( 'This is a tooltip' ),
            ]
        ]
    ]
);

$section = Section::make( 'My section', $form );

Defining tabs ​

Tabs are defined by using the Tab class. Each tab takes a title, a slug and an array of sections as arguments.

php
$tab = new Tab( 'My tab', 'my-tab', [ $section ] );

Once you have defined your tabs, you can add them to the Tabs class that serves as collection of all the tabs.

php
$tabs = new Tabs( [ $tab ] );

Defining the options page ​

The options page is defined by using the SettingsPage class. The constructor takes two arguments: the instance of the Plugin class and an instance of the Tabs class.

php
$page = new SettingsPage( $plugin, $tabs );

Now that you have defined your options page, you can register it by using the register_hooks method.

php
$page->register_hooks();

This will fire the hooks that will add the options page to the WordPress admin menu.

You may adjust this behavior by creating your own SettingsPage class and overriding the register_hooks method.

php
class MySettingsPage extends SettingsPage
{
    public function register_hooks()
    {
        add_action( 'admin_menu', [ $this, 'add_page' ] );
    }

    public function add_page()
    {
        // Add the page to the WordPress admin menu.
    }
}

Supported fields ​

The following fields are supported by the framework:

  • checkbox
  • input
  • multicheckbox
  • multiselect
  • radio
  • select
  • textarea
  • toggle

Defining the fields ​

Fields are defined through the Form class. Each field takes the following arguments:

  • name: The name of the field.
  • type: The type of the field.
  • label: The label of the field.
  • description: The description of the field.
  • tooltip: The tooltip of the field. This is an optional argument. The argument is an array with the following keys:
    • text: The text of the tooltip.
  • rule: The rules of the field. This is an optional argument.
  • options: The options of the field. This argument is only used for the select, multiselect, multicheckbox and radio types.
php
$form = Form::make(
    [
        [
            'type' => 'toggle',
            'name' => 'toggle-field-example',
            'label' => __('Toggle Field'),
            'description' => __('This is a toggle field'),
            'tooltip' => [
                'text' => __( 'This is a tooltip' ),
            ]
        ]
    ]
);

When setting the options argument for the select, multiselect, multicheckbox and radio types, you can pass an array of options. Each option is an array with the following keys:

  • value: The value of the option.
  • label: The label of the option.

Dynamic options ​

Some fields can dynamically load options via the rest API. This is useful when you want to load options from a third-party API or when you want to load from long-running processes.

To dynamically load options, you can use the callable parameter when defining the field. The callable parameter is a PHP callable that will be called when the field is rendered.

php
$form = Form::make(
    [
        [
            'type' => 'select',
            'name' => 'select-example',
            'label' => __('Select Field'),
            'callable' => fn() => dynamic_options()
        ]
    ]
);

No other configuration is required for the field to be dynamically loaded. The framework will handle the rest of the process.

Validating the form ​

Forms in the options page are automatically validated as long as fields have a rule argument. If a validation error occurs, the error will be displayed in the form.

For more information on how to define validation rules, see the Validation documentation.