README

Dependency-less helpers for a faster Wordpress metaboxes setup.

Installation

via composer:

> composer require gebruederheitz/wp-meta-fields

Make sure you have Composer autoload or an alternative class loader present.

Usage

Use these helpers anywhere in the WP administration backend where you want to render "metaboxes", or input fields for editors.

WP-Meta-Fields comes with no frontend dependencies – no extra stylesheets or client-side scripts that could cause trouble with installation. This also means, however, that it doesn't come with fancy features like asnyc search, validation or fancy styles for the various input types. It merely provides an intuitive interface to create DRY code when creating metaboxes.

use Gebruederheitz\Wordpress\MetaFields\MetaForms;

function render($value) 
{
    // Use the "render{$type}" static methods:
    MetaForms::renderTextInputField('ghwp_favourite_color', $value, 'Favourite color');
    // ...or the more verbose "make{$type}" methods, which support chaining:
    MetaForms::makeTextInputField()
        ->setName('ghwp_favourite_food')
        ->setValue($value)
        ->setLabel('Your favourite food')
        ->render();
}

Label i18n

Labels are automatically translated using Wordpress' __() internationalisation function. By default, the namespace "ghwp" is applied. To customize this text domain, call one of the setter method on the singleton:

MetaForms::updateTextDomain('my-textdomain');
// or
MetaForms::getInstance()->setTextDomain('my-textdomain');

Inputs API

All field require at least one name attribute (as noted for each type below) to be set, otherwise an InvalidFieldConfigurationException will be thrown.

TextInput

For rendering a regular text input field.

MetaForms::renderTextInputField(string $name, string $label, $value = '', bool $required = false)

NumberInput

For rendering a an <input type="number" />.

MetaForms::renderNumberInputField()

same as TextInput

TextArea

Renders a <textarea>.

MetaForms::renderTextArea()

same as TextInput

MediaPicker

Renders the inputs required for a Wordpress media picker, with a preview of the currently selected medium.

For this to work, make sure the WP media scripts are enqueued. If you're using gebruederheitz/wp-easy-cpt this is easily achieved by setting protected $withMedia = true; on your PostType implementation. Otherwise you will need to add a callback to the appropriate action hook:

class UsesMetaForms
{
    public function __construct() 
    {
        add_action('admin_enqueue_scripts', [$this, 'onAdminEnqueueScripts']);
    }
    
    public function onAdminEnqueueScripts()
    {
        wp_enqueue_media();
    }
}

MetaForms::renderMediaPicker()

Using custom templates

You can override the default templates provided by simply putting a template file with the correct name into template-parts/meta/forms/ within your theme's root directory:

Customizing the template override location

If you want to use a custom location (other than template-parts/meta/forms/) you can provide your own override base path using one of the singleton's setter methods. You can not change the names of the template files.

// Make sure to end with a trailing slash
MetaForms::updateOverridePath('partials/vendor/gebruederheitz/meta-forms/override/')
// or
MetaForms::getInstance()->setOverridePath('partials/vendor/gebruederheitz/meta-forms/override/');

Development

Dependencies

• PHP >= 7.4
• Composer 2.x
• NVM and nodeJS LTS (v16.x)
• Nice to have: GNU Make (or drop-in alternative)