RWMB_Field Class

Overview

In Meta Box plugin, each field is built by a PHP class RWMB_{$field_type}_Field. This class extends the prime class – RWMB_Field. In other words, RWMB_Field is the prime class from which all fields are built on.

RWMB_Field has all necessary methods for fields to use. Fields can overwrite these methods, change them for specific needs or add more methods if necessary.

Note: All methods of this class (and its descendants) are static. It will make all fields use the same code instead of creating multiple class instances, thus increase plugin’s performance.

Class methods

add_actions

This method allows a field to add custom hooks for its needs. For example: callbacks for ajax call (like file), add hook to output custom content in admin footer (like image_advanced), etc.

This method is called when the meta box is loaded.

You can also add custom code to this method or calls to other functions which need to run when code is loaded.

This method doesn’t have any arguments.

admin_enqueue_scripts

This method allows you to enqueue scripts and styles for a field.

This method doesn’t have any arguments.

show

This method outputs field’s HTML markup. Fields should not overwrite this method to output custom HTML. Instead of that, overwrite methods html, begin_html, end_html described below.

This method has 2 arguments:

  • $field: array of field arguments
  • $saved: a param used to detect whether this meta box is saved into database or not

html

This method returns (not echoes, only returns) field’s HTML markup. This is the input controls of the field and is put inside .rwmb-input CSS class. It can be filtered by rwmb_{$field_type}_html and rwmb_{$field_id}_html filters.

Each field must overwrite this method to returns its HTML for inputs.

This method has 2 arguments:

  • $meta: field meta value
  • $field: array of field arguments

begin_html

This method returns the beginning HTML output of a field. The beginning HTML output contains field name and opening tag for inputs. By default it is:

<div class="rwmb-label">
    <label for="{$field_id}">{$field_name}</label>
</div>
<div class="rwmb-input">

This method should not be overwritten by field’s class, unless it’s needed to do so (like heading field). The return value of this function is filtered by rwmb_begin_html filter (and its family).

This method has 2 arguments:

  • $meta: field meta value
  • $field: array of field arguments

end_html

This method returns the ending HTML output of a field. The ending HTML output contains clone button, field description and closing tag for inputs. By default it is:

{$clone_button}
{$field_description}
</div> <!-- .rwmb-input -->

This method should not be overwritten by field’s class, unless it’s needed to do so (like heading field). The return value of this function is filtered by rwmb_end_html filter (and its family).

This method has 2 arguments:

  • $meta: field meta value
  • $field: array of field arguments

add_clone_button

This method returns HTML of the add clone button and has no arguments.

remove_clone_button

This method returns HTML of the remove clone button and has no arguments.

meta

This method retrieves meta value for a field. In most cases, this method does all the job of retrieving meta value of a field. But in some cases, a descendant class may overwrite this method to retrieve meta value for more complicated logic (like user field).

This method has 3 parameters:

  • $post_id: current post ID, from which we retrieve meta value
  • $saved: a param used to detect whether this meta box is saved into database or not
  • $field: array of field arguments

The returned value of this method is filtered by rwmb_field_meta filter (and its family).

value

This method set field meta value before saving in database. By default it just returns the value from $_POST. Field class can overwrite this method to set meta value for more complicated logic (like taxonomy_advanced).

This method has 4 parameters:

  • $new: field meta value which will be saved in the database
  • $old: old meta value of field
  • $post_id: current post ID, from which we retrieve meta value
  • $field: array of field arguments

The returned value of this method is filtered by rwmb_{$field_type}_value filter (and its family).

save

This method saves field meta value in database. In most cases, this method does all the job of saving meta value of a field to database. But in some cases, a descendant class may overwrite this method to handle saving itself (like taxonomy field).

This method has 4 parameters:

  • $new: field meta value which will be saved in the database
  • $old: old meta value of field
  • $post_id: current post ID, from which we retrieve meta value
  • $field: array of field arguments

normalize_field

This method normalizes field arguments, add missing arguments, add default value for fields, etc. Depends on field type, each field class can overwrite this method to define its own defaults value.

This method has 1 parameter:

  • $field: array of field arguments

Filters

This page lists all filters for Meta Box plugin:

General filters

rwmb_meta_boxes

This is the most important filter of the plugin. It is used to add/remove/edit meta boxes. See this documentation for more details on how to use it.

This filter has 1 parameter – array of meta boxes.

apply_filters( 'rwmb_meta_boxes', array() );

rwmb_shortcode

This filter is used to change the output of [rwmb_shortcode] shortcode. It has 1 parameter – output of the shortcode.

apply_filters( 'rwmb_shortcode', $content );

rwmb_meta

This filter is used to change the returned value of helper function rwmb_meta. It accepts 4 parameters:

  • $meta: the meta value returned by rwmb_meta function
  • $key: meta key (custom field ID)
  • $args: arguments passed to rwmb_meta function
  • post_id: post ID
apply_filters( 'rwmb_meta', $meta, $key, $args, $post_id );

Meta Box filters

rwmb_show

This filter is used to change the visibility of a meta box (by default meta box is shown). It accepts 2 parameters:

  • $show: current visibility of the meta box
  • $meta_box: array of a meta box definition
$show = apply_filters( 'rwmb_show', $show, $meta_box );

rwmb_show_{$meta_box_id}

This filter is the same as rwmb_show but is applied to a specific meta box (identified by ID). It accepts same parameters.

rwmb_normalize_meta_box

This filter is used to normalize a meta box’s parameters. It’s useful when you want to set default values for a meta box. It accepts 1 parameter – meta box array of definition.

$meta_box = apply_filters( 'rwmb_normalize_meta_box', $meta_box );

rwmb_normalize_{$meta_box_id}_meta_box

This filter is the same as rwmb_normalize_meta_box but is applied to a specific meta box (identified by ID). It accepts same parameters.

Field general filters

rwmb_normalize_field

This filter is used to normalize a field’s parameters. It’s useful when you want to set default values for a field. It accepts 1 parameter – array of field attributes.

$meta_box = apply_filters( 'rwmb_normalize_field', $field );

rwmb_normalize_{$field_type}_field

This filter is the same as rwmb_normalize_field but is applied to fields with a specific type. It accepts same parameters.

rwmb_normalize_{$field_id}_field

This filter is the same as rwmb_normalize_field but is applied to a specific field (identified by ID). It accepts same parameters.

rwmb_field_meta

This filter is used to change a field meta value before displaying it in the meta box. It accepts 3 parameters:

  • $meta: field meta value
  • $field: array of field attributes
  • $saved: a param used to detect whether this meta box is saved into database or not. It’s useful when you want to set default value for a field
$meta = apply_filters( 'rwmb_field_meta', $meta, $field, $saved );

rwmb_{$field_type}_field_meta

This filter is the same as rwmb_field_meta but is applied to fields with a specific type. It accepts same parameters.

rwmb_{$field_id}_field_meta

This filter is the same as rwmb_field_meta but is applied to a specific field (identified by ID). It accepts same parameters.

rwmb_{$field_type}_value

This filter is used to change a field meta value before saving it in the database. It accepts 3 parameters:

  • $new: field meta value which will be saved in the database
  • $field: array of field attributes
  • $old: old meta value of field
$new = apply_filters( "rwmb_{$field['type']}_value", $new, $field, $old );

rwmb_{$field_id}_value

This filter is the same as rwmb_{$field_type}_value but is applied to a specific field (identified by ID). It accepts same parameters.

Field appearance filters

rwmb_begin_html

This filter is used to change the beginning HTML output of a field. The beginning HTML is defined in field’s begin_html function (see documentation for RWMB_Field class). Each field can overwrite this function and output different HTML.

By default it has the following markup:

<div class="rwmb-label">
    <label for="{$field_id}">{$field_name}</label>
</div>
<div class="rwmb-input">

This filter accepts 3 parameters:

  • $begin: the beginning HTML output of the field
  • $field: array of field attributes
  • $meta: field meta value
$begin = apply_filters( 'rwmb_begin_html', $begin, $field, $meta );

rwmb_{$field_type}_begin_html

This filter is the same as rwmb_begin_html but is applied to fields with a specific type. It accepts same parameters.

rwmb_{$field_id}_begin_html

This filter is the same as rwmb_begin_html but is applied to a specific field (identified by ID). It accepts same parameters.

rwmb_end_html

This filter is similar to rwmb_begin_html and is used to change the ending HTML output of a field. The ending HTML is defined in field’s end_html function (see documentation for RWMB_Field class). Each field can overwrite this function and output different HTML.

By default it has the following markup:

{$clone_button}
{$field_description}
</div> <!-- .rwmb-input -->

This filter accepts 3 parameters:

  • $end: the ending HTML output of the field
  • $field: array of field attributes
  • $meta: field meta value
$end = apply_filters( 'rwmb_end_html', $end, $field, $meta );

rwmb_{$field_type}_end_html

This filter is the same as rwmb_end_html but is applied to fields with a specific type. It accepts same parameters.

rwmb_{$field_id}_begin_html

This filter is the same as rwmb_end_html but is applied to a specific field (identified by ID). It accepts same parameters.

rwmb_{$field_type}_html

This filter is used to changed the HTML output of a field, which is inside rwmb-input class, e.g. after beginning HTML and before ending HTML.

The HTML output of a field is various and depends on field type. For example: a text field simply outputs a input tag, while wysiwyg field outputs a complicated div.

This filter accepts 3 parameters:

  • $field_html: HTML output of a field
  • $field: array of field attributes
  • $meta: field meta value
$field_html = apply_filters( "rwmb_{$field_type}_html", $field_html, $field, $meta );

rwmb_{$field_id}_html

This filter is the same as rwmb_{$field_type}_html but is applied to a specific field (identified by ID). It accepts same parameters.

rwmb_wrapper_html

This filter is used to change the wrapper HTML output of a field. Wrapper HTML is the string concatenation of beginning HTML, field HTML and ending HTML.

This filter accepts 3 parameters:

  • $html: wrapper HTML output of the field
  • $field: array of field attributes
  • $meta: field meta value
$html = apply_filters( 'rwmb_wrapper_html', "{$begin}{$field_html}{$end}", $field, $meta );

rwmb_{$field_type}_wrapper_html

This filter is the same as rwmb_wrapper_html but is applied to fields with a specific type. It accepts same parameters.

rwmb_{$field_id}_wrapper_html

This filter is the same as rwmb_wrapper_html but is applied to a specific field (identified by ID). It accepts same parameters.

rwmb_outer_html

This filter is used to change the outer HTML output of a field. Outer HTML is surrounding div (the most outside) of the field. By default it has the following markup:

$outer_html = $field['before'] . "<div class='{$field_classes}'>{$wrapper_html}</div>" . $field['after'];

This filter accepts 3 parameters:

  • $outer_html: outer HTML output of the field
  • $field: array of field attributes
  • $meta: field meta value
$outer_html = apply_filters( 'rwmb_outer_html', $outer_html, $field, $meta );

rwmb_{$field_type}_outer_html

This filter is the same as rwmb_outer_html but is applied to fields with a specific type. It accepts same parameters.

rwmb_{$field_id}_outer_html

This filter is the same as rwmb_outer_html but is applied to a specific field (identified by ID). It accepts same parameters.

Specific fields’ filters

choice fields (user, post, taxonomy) filters:

  • rwmb_choice_label: which will effect labels for all choice fields
  • rwmb_{$field_type}_choice_label: which will effect all of a particular type
  • rwmb_{$field_id}_choice_label: which will effect all of a the field with a particular id

Example: If you are using a field called some_user and you want to change the label in the select box to user first_name instead of the default display_name:

function some_user_filter( $label, $field, $user ) {
    return $user->first_name ;
}
add_filter( 'rwmb_some_user_choice_label', 'some_user_filter', 10, 3);

wysiwyg filters

rwmb_wysiwyg_settings: This filter is used to changed the options for the editor (which is passed by $field['option']) and is applied to all wysiwyg fields.

This filter accepts 1 param:

  • $settings: editor settings, which will be sent to wp_editor function.

file filters

FilterDefaultDescription
rwmb_file_upload_stringUpload FilesFile upload string
rwmb_file_add_string+ Add new fileAdd new file string
rwmb_file_delete_stringDeleteFile delete string
rwmb_file_edit_stringEditFile edit string

All filters above accept 2 parameters:

  • $string: the string need to be changed
  • $field: array of field attribute

file_advanced filters

FilterDefaultDescription
rwmb_file_advanced_select_stringSelect or Upload FilesThe button text to select or upload files
rwmb_file_delete_stringDeleteFile delete string (same as file)
rwmb_file_edit_stringEditFile edit string (same as file)

All filters above accept 2 parameters:

  • $string: the string need to be changed
  • $field: array of field attribute

image filters

FilterDefaultDescription
rwmb_image_upload_stringUpload ImagesImage upload string
rwmb_image_add_string+ Add new imageAdd new image string
rwmb_image_delete_stringDeleteImage delete string
rwmb_image_edit_stringEditImage edit string

All filters above accept 2 parameters:

  • $string: the string need to be changed
  • $field: array of field attribute

image_advanced filters

FilterDefaultDescription
rwmb_image_advanced_select_stringSelect or Upload ImagesThe button text to select or upload images
rwmb_image_delete_stringDeleteImage delete string (same as image)
rwmb_image_edit_stringEditImage edit string (same as image)

All filters above accept 2 parameters:

  • $string: the string need to be changed
  • $field: array of field attribute

plupload_image filters

FilterDefault
rwmb_plupload_image_drop_stringDrop images here
rwmb_plupload_image_or_stringor
rwmb_plupload_image_select_stringSelect Files

(these strings appear in the drop area of field where users can drop or select images to upload)

All filters above accept 2 parameters:

  • $string: the string need to be changed
  • $field: array of field attribute

thickbox_image filters

FilterDefaultDescription
rwmb_thickbox_image_upload_stringUpload ImagesUpload image string

This filter accepts 2 parameters:

  • $string: the string need to be changed
  • $field: array of field attribute

Actions

This page lists all actions in Meta Box plugin.

rwmb_before

This action runs before any meta box is shown. It takes 1 parameter: the instance of RW_Meta_Box class for current meta box.

do_action( 'rwmb_before', $this );

rwmb_before_{$meta_box_id}

This action is the same as rwmb_before but is applied for a specific meta box (identified by ID). It accepts same parameters.

rwmb_after

This action runs after any meta box is shown. It takes 1 parameter: the instance of RW_Meta_Box class for current meta box.

do_action( 'rwmb_after', $this );

rwmb_after_{$meta_box_id}

This action is the same as rwmb_after but is applied to a specific meta box (identified by ID). It accepts same parameters.

rwmb_before_save_post

This action runs before any meta box is saved into post meta. It takes 1 parameter: current post ID.

do_action( 'rwmb_before_save_post', $post_id );

rwmb_{$meta_box_id}_before_save_post

This action is the same as rwmb_before_save_post but is applied to a specific meta box (identified by ID). It accepts same parameters.

rwmb_after_save_post

This action runs after any meta box is saved into post meta. It takes 1 parameter: current post ID.

do_action( 'rwmb_after_save_post', $post_id );

rwmb_{$meta_box_id}_ after_save_post

This action is the same as rwmb_after_save_post but is applied to a specific meta box (identified by ID). It accepts same parameters.

rwmb_enqueue_scripts

This action is added in version 4.6 and runs after all Meta Box scripts and styles are enqueued to allows developers to enqueue more scripts and styles. It takes 1 parameter: the instance of RW_Meta_Box class for current meta box.

do_action( 'rwmb_enqueue_scripts', $this );