A package to render form fields in WordPress settings pages.

Roel Magdaleno

Last update: Jul 22, 2022

Related tags

Miscellaneous wordpress package settings form elements

Overview

WP Settings Page Fields

A package to render form fields in WordPress settings pages.

You might need a settings page with a form and its fields and you have to render the fields every time you create a custom plugin.

Maybe, you already have some snippets that generates the form fields for you, otherwise this package is for you.

Installation

You can install the package via composer:

composer require roelmagdaleno/wp-settings-page-fields

Usage

Every supported form element extends the Roel\WP\Settings\Element class and must be instantiated with the same constructor:

<?php

$element = new Element( $id, $settings, $option_name );

These are the supported parameters:

$id: The form element id. Use the id() method to get the id.
$settings: The form element settings (Some form elements have specific settings).
$option_name: The database option name where the value is stored.

WordPress

To register and render form elements in your settings page with this package, you can use:

<?php

use Roel\WP\Settings\Elements\{
    Checkbox,
    Text,
};

$settings = array(
    new Checkbox( 'allow-user', array(
        'label'       => 'Allow user?',
        'description' => 'Allow user to do current action.',
    ), 'rmr_settings' ),
    new Text( 'api-key', array(
        'label'       => 'API Key',
        'description' => 'Insert the API Key.',
    ), 'rmr_settings' ),
);

foreach ( $settings as $setting ) {
    add_settings_field(
        $setting->id(),
        $setting->label(),
        array( $setting, 'print' ),
        'your-page'
    );
}

Remember to add the array( $setting, 'print' ) as a callback to render the setting field. The $setting variable is an Roel\WP\Settings\Element instance.

Render

This is how you can create a form element instance and render the HTML:

Using the `render` method

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text->render();

Using the `print` method

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

$text->print();

Using `echo` directly to the instantiated class

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text;

Attributes

`name` attribute

Every form element includes a name attribute. This attribute will be used to assign the current element value to the $_POST variable, so you can manage that value like insert it into the database.

The name attribute value is generated by using the option_name and id. So, in the next example:

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text->render();

The name attribute would be:

<input type="text" name="rmr_settings[api-key]" />

Then, in PHP, you would access the value of that input like this:

$_POST['rmr_settings'] = array(
    'api-key' => 'my-api-key',
);

HTML attributes

You can add HTML attributes to your form elements:

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
    'attributes'  => array(
        'data-value'  => 'value',
        'data-custom' => 'custom',
        'oninput'     => 'myFunction(\'myValue'\)'
    ),
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text->render();

Group

Look at this example:

<?php

use Roel\WP\Settings\Elements\{
    Checkbox,
    Text,
};

$settings = array(
    new Checkbox( 'allow-user', array(
        'label'       => 'Allow user?',
        'description' => 'Allow user to do current action.',
    ), 'rmr_settings' ),
    new Checkbox( 'allow-admin', array(
        'label'       => 'Allow admin?',
        'description' => 'Allow admin to do current action.',
    ), 'rmr_settings' ),
    new Text( 'api-key', array(
        'label'       => 'API Key',
        'description' => 'Insert the API Key.',
    ), 'rmr_settings' ),
);

foreach ( $settings as $setting ) {
    add_settings_field(
        $setting->id(),
        $setting->label(),
        array( $setting, 'print' ),
        'your-page'
    );
}

You see how the rmr_settings option name is repetitive? Now imagine to add more than 10 settings in the same page. For this kind of cases, you can use the Roel\WP\Settings\Group class.

The instance accepts two parameters:

$elements (array): The elements to group.
$option_name (string): The option name for each element.

The passed option name will be set to every passed form element.

<?php

use Roel\WP\Settings\Group;
use Roel\WP\Settings\Elements\{
    Checkbox,
    Text,
};

$elements = array(
    new Checkbox( 'allow-user', array(
        'label'       => 'Allow user?',
        'description' => 'Allow user to do current action.',
    ) ),
    new Checkbox( 'allow-admin', array(
        'label'       => 'Allow admin?',
        'description' => 'Allow admin to do current action.',
    ) ),
    new Text( 'api-key', array(
        'label'       => 'API Key',
        'description' => 'Insert the API Key.',
    ) ),
);

$group = new Group( $elements, 'rmr_settings' );

foreach ( $group->elements() as $element ) {
    add_settings_field(
        $element->id(),
        $element->label(),
        array( $element, 'print' ),
        'your-page'
    );
}

After declaring the Group class with the required parameters, you can get the elements with elements() method, so you can loop and render them.

Settings

Check the available settings and more in the Wiki section.

Filters

Every form element has two filters to change the HTML output:

Change the HTML output for all registered elements.
Change the HTML output for a specific element.

Check the filters for all form elements and more in the Wiki section.

Form Elements

These are the supported form elements so far:

This package provides a wrapper for Google Lighthouse to audit the quality of web pages with Laravel.

laravel-google-lighthouse This package is based on octoper/lighthouse-php. This package provides a wrapper for Google Lighthouse to audit the quality

5 Jun 1, 2022

A PHP/Laravel package to fetch Notion Pages and convert it to HTML!

Generate HTML from Notion Page This package converts all the blocks in a Notion page into HTML using Notion's API. For more details on Notion API, ple

4 Nov 23, 2022

Adds a compact "easy-sort" mode to Repeater and Repeater Matrix, making those fields easier to sort when there are a large number of items.

Repeater Easy Sort Adds a compact "easy-sort" mode to Repeater and Repeater Matrix, making those fields easier to sort when there are a large number o

3 Oct 10, 2021

Silverstripe-searchable - Adds to the default Silverstripe search by adding a custom results controller and allowing properly adding custom data objects and custom fields for searching

SilverStripe Searchable Module UPDATE - Full Text Search This module now uses Full Text Support for MySQL/MariaDB databases in version 3.* Adds more c