Usage - AleksandarPredic/psm-fields GitHub Wiki

Usage

Installation

Please finish the installation process described in this file.

Create a new class for each metabox

Then create a new class in your project and extend the \PSMFields\Facades\PSMFieldsMetabox class from this library. The IDE will prompt you to create init method where you can register the new metabox and all the needed fields.

For the reference, please see the example ExampleMetaboxController class file in this library. You can also copy the example to your child theme and edit the file.

Call the created init method

In your child theme, in the __construct() method, call the created metabox class init method no later than admin_init WP action hook. It is recommended to use the init hook if you are not highly advanced in WordPress.

It is also recommended calling the init method only on admin pages as we don't need to register the fields on the frontend. There we will just pull data from post_meta table.

// We don't need to add fields on frontend, just read post_meta there
if (! is_admin()) {
    return;
}

ExampleMetaboxController::getInstance()->init();

Add fields dynamically

You can add fields using the created metabox class before or after you call the init method. It is recommended to keep all the fields inside the metabox class you created to allow future developers to easily find them.

Example how to add a new field outside the created metabox class and perform some logic:

// One way to add fields using general WP hooks
add_action('admin_head', function () {
    global $post_type;

    // Add field only for the post, even if we registered metabox for the post type
    if ('post' !== $post_type) {
        return;
    }

    ExampleMetaboxController::getInstance()->addInputTextField(
        'prefix_input_text_field_2',
        esc_html__('Example input text field', 'textdomain')
    );
});

It is recommended to keep this dynamic added fields in the same metabox class for the ease of the code understanding.

You can view WordPress action hooks reference here

The latest hook you can use to add fields is: psmfields_metabox_prerender_{metabox_id}

// Fire just before rendering the metabox
add_action('psmfields_metabox_prerender_example_metabox_id', function () {

    // Display only for posts with id 7
    if (get_the_ID() != 7) {
        return;
    }

    ExampleMetaboxController::getInstance()->addInputTextField(
        'prefix_input_text_field_2',
        esc_html__('Example input text field', 'textdomain')
    );
});

Get the field value from the database

When you create the metabox class and extend library class, it will inherit some methods. One of them is the getFieldValue method which accepts Post ID as the first parameter and meta_key, the name for the field you registered.

/**
 * Retrieve the field value from the database
 * @param int $postId Post object ID
 * @param string $name Name of the field (meta_key)
 * @return mixed
 */
public function getFieldValue($postId, $name);

The example:

ExampleMetaboxController::getInstance()->getFieldValue($postId, 'meta_key')

It is recommended to use the created metabox class method and avoid calling the get_post_meta directly.

Using the repeater field

To add some fields to the repeater field, you first need to call the startRepeaterField method and than add all the fields for the repeater as you would normaly add them. When you are done adding the fields, you must call the endRepeaterField method to stop adding fields to the repeater.