README

WP Meta Box

This package aims to make it easier to create meta boxes for WordPress plugins.

⚠️ Untill the first stable release, the API is subject to change. Use at your own risk.

Installation

composer require jeffreyvanrossum/wp-meta-box

Usage

Basic example

use Jeffreyvr\WPMetaBox\WPMetaBox;

$meta_box = WPMetaBox::post('Post settings')
    ->set_post_type('post');

$meta_box->add_option('text', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'description' => __('Some additional description', 'textdomain')
]);

$meta_box->make();

// Or for taxonomies:
$meta_box = WPMetaBox::taxonomy('Taxonomy settings')
    ->set_taxonomies(['category']);

Available types

Text
Date
Number
Textarea
Checkbox
Choices (Radio Buttons)
Color
Select
Select2
Media
Image
Code Editor
WP Editor
Repeater

Text

$meta_box->add_option('text', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Date

$meta_box->add_option('date', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Number

$meta_box->add_option('number', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

You may also pass min and max.

Textarea

$meta_box->add_option('textarea', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Checkbox

$meta_box->add_option('checkbox', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Choices (radio buttons)

$meta_box->add_option('checkbox', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'options' => [
        1 => 'option 1',
        2 => 'option 2'
    ]
]);

Color

$meta_box->add_option('color', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Select

$meta_box->add_option('select', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'options' => [
        1 => 'option 1',
        2 => 'option 2'
    ]
]);

You can allow multiple values too.

$meta_box->add_option('select', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'multiple' => true,
    'options' => [
        1 => 'option 1',
        2 => 'option 2'
    ]
]);

Select2

Select2 gives you a customizable select box with support for searching.

You can use select2 the same way you use the regular select.

$meta_box->add_option('select2', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'options' => [
        1 => 'option 1',
        2 => 'option 2'
    ]
]);

If you would like to search the options through ajax, you can do this by defining two callbacks (or function names). One for fetching and filtering the options and one for getting the value callback.

The below example is using select2 to select a page.

$meta_box->add_option('select2', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'ajax' => [
        'value' => function($pageId) {
            return get_the_title($pageId) ?? null;
        },
        'action' => function() {
            $results = array_reduce(get_posts(['post_type' => 'page', 's' => $_GET['q']]), function($item, $page) {
                $item[$page->ID] = $page->post_title;

                return $item;
            }, []);

            echo json_encode($results);

            die();
        }
    ]
]);

You may allow multiple values by settings the multiple value in config to true. If you want to use the ajax functionality here, be sure to define value callback here as well.

$meta_box->add_option('select2', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain'),
    'multiple' => true,
    'ajax' => [
        'value' => function($ids) {
            foreach($ids as $id) {
                $titles[$id] = get_the_title($id) ?? $id;
            }
            return $titles ?? [];
        },
        'action' => function() {
            $results = array_reduce(get_posts(['post_type' => 'page', 's' => $_GET['q']]), function($item, $page) {
                $item[$page->ID] = $page->post_title;

                return $item;
            }, []);

            echo json_encode($results);

            die();
        }
    ]
]);

You can pass anything you'd like to the select2 configuration using config, the exception being the ajax part of the configuration.

A list of options can be found here.

The Select2 that comes with the package is loaded from the Cloudflare CDN. You can overwrite this using the wmb_select2_assets filter hook.

Media

$meta_box->add_option('media', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Image

$meta_box->add_option('image', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

Code editor

$meta_box->add_option('code-editor', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

WP Editor

$meta_box->add_option('wp-editor', [
    'name' => 'name_of_option',
    'label' => __('Label of option', 'textdomain')
]);

You can provide a config array to customize the editor. For more information on this config check out the wp.editor documentation.

Repeater

Example of a gallery using the repeater option:

$meta_box->add_option('repeater', [
    'name' => 'gallery',
    'label' => __('Gallery', 'textdomain'),
])->add_repeater_option('image', [
    'name' => 'image',
    'label' => __('Image', 'textdomain'),
]);

Sanitize

If you want to sanitize the values of the input, you can pass a sanitize callback.

For example:

$meta_box->add_option('number', [
    'name' => 'some_number',
    'label' => __('Some number', 'textdomain'),
    'description' => __('Must be positive', 'textdomain'),
    'min' => 0,
    'max' => 10,
    'sanitize' => function($value) {
        return abs($value);
    }
]);

Contributors

License

MIT. Please see the License File for more information.

jeffreyvanrossum / wp-meta-box

Maintainers

Details