Simple Fields

Installation

Plugin installation is pretty simple – once you have downloaded it as a zip archive, please go to Plugins > Add new and click the Upload Plugin button.

Fields

Below is the description for all the available fields. No matter if you’re going to use them for meta boxes, option pages, or the Gutenberg sidebars, all the parameters are the same.

Text Field

Usage:

array(
	'id' => 'my_field',
	'name' => 'my_field_name', // by default the same as "id"
	'label' => 'Label',
	'type' => 'text',
	'default' => '',
	'placeholder' => '',
	'class' => 'my-class-1 my-class-2', // CSS classes, space-separated or an array
)

Also supports maxlength and show_if parameters (more about conditional fields below).

Textarea

array(
	'id' => 'my_textarea_field',
	'label' => 'Label',
	'type' => 'textarea',
	'default' => '',
	'placeholder' => '',
	'cols' => '',
	'rows' => '',
	'class' => array( 'my-class-1', 'my-class-2' ),
),

Also supports name, maxlength and show_if.

Number

array(
	'id' => 'my_num_field',
	'label' => 'Label',
	'type' => 'number',
	'min' => 1,
	'max' => 10000,
	'step' => 2,
)

Also supports name, class, placeholder, default, short_description and show_if.

Editor

The editor field allows you to save data with HTML tags.

Usage:

array(
	'id' => 'my_editor',
	'label' => 'Label',
	'type' => 'editor',
	'description' => '',
	'editor_args' => array(
		'textarea_rows' => 5,
		'teeny' => true,
		'tinymce' => false,
		'media_buttons' => false,
		'drag_drop_upload' => false,
		'quicktags' => array( 
			'buttons' => 'strong,em,link,ul,ol,li,code',
		),
	),
	'default' => '',
)

Also supports class, name and show_if.

This field also allows you to specify the list of allowed HTML tags and their attributes for sanitizing with wp_kses() function with simple_sanitize_editor_allowed_html filter hook.

Checkbox

array(
	'id' => 'my_checkbox',
	'label' => 'Label',
	'type' => 'checkbox',
	'short_description' => 'Yes'
	'default' => '', // 1 or 0, true or false
)

Also supports name, class and show_if.

Checklist

Sometimes you need multiple values to be selected, and the Checklist field is the best and most elegant way to do it.

Usage:

array(
	'id' => 'my_checklist',
	'name' => 'my_checklist_field',
	'label' => 'Label',
	'type' => 'checklist',
	'default' => array( 'val1', 'val2' ),
	'options' => array(
		'val1' => 'Option 1',
		'val2' => 'Option 2',
		'val3' => 'Option 3',
		'val4' => 'Option 4',
	),
)

Select

array(
	'id' => 'my_select_field',
	'label' => 'Label',
	'type' => 'select',
	'placeholder' => 'Select...',
	'options' => array(
		'val1' => 'Option 1',
		'val2' => 'Option 2',
	),
)

Also supports name, class, show_if and multiple.

If you provide 'multiple' => true and enqueue the Select2 library in the WordPress admin, then it will be automatically activated for this field. A good example is here.

Radio

array(
	'id' => 'my_radio',
	'name' => 'my_radio_bnts',
	'label' => 'Label',
	// 'inline' => true, // you can display radio buttons inline
	'type' => 'radio',
	'options' => array(
		'val1' => 'Option 1',
		'val2' => 'Option 2',
	),
	'default' => 'val1',
)

Color

You can also create a color picker field inside your custom meta boxes and settings pages. The plugin uses WordPress default color picker library for that.

array(
	'id' => 'my_color',
	'label' => 'Label',
	'type' => 'color',
)

Image

array(
	'id' => 'my_img',
	'label' => 'Label',
	'type' => 'image',
)

You can provide a default value as an image ID, name and description parameters are also supported.

Gallery

This field allows not only to choose multiple images but also to change their order using drag and drop.

Usage:

array(
	'id' => 'my_gallery',
	'label' => 'Label',
	'type' => 'gallery',
),

You can provide a default value as an array of image IDs, name and description parameters are also supported.

File

array(
	'id' => 'my_file',
	'label' => 'Label',
	'type' => 'file',
)

You can provide a default value as an attachment ID, name and description parameters are also supported.

Post

This field allows you to add a “Select2”-type post selection (with AJAX search). Example:

array(
	'id' => 'my_post_id',
	'label' => 'Label',
	'type' => 'post',
	'multiple' => false,
	'post_type' => 'post',
	'placeholder' => 'Select post',
)

You can provide a default value as a post ID (or an array of IDs, if multiple is set to true); name and description parameters are also supported.

Taxonomy term (category, tag, etc)

Similar to the “Post” field, but allows you to work with custom taxonomy terms. Example with the multiple parameter set to true:

array(
	'id' => 'my_category',
	'label' => 'Label',
	'type' => 'taxonomy_term',
	'multiple' => false,
	'taxonomy' => 'category',
)

Repeater field

Since version 2.5, my plugin allows you to use repeater fields. Here is what it looks like in Gutenberg sidebar settings:

In order to use a repeater field, please provide the field type repeater and then just the fields into subfields parameter.

An example of code:

array(
	'id' => 'my_repeater',
	'label' => 'Repeater',
	'type' => 'repeater',
	'subfields' => array(
		array(
			'type' => 'text',
			'id' => 'name',
			'label' => 'Name',
		),
		array(
			'type' => 'text',
			'id' => 'url',
			'label' => 'URL',
		),
		array(
			'type' => 'image',
			'id' => 'logo',
			'label' => 'Logo',
		)
	)
)

Sections and Tabs

There is also a possibility to organize fields in your meta boxes or settings pages. Depending on the meta box type, it can be implemented in different ways.

It is quite easy to use:

• In order to use sections, just provide 'sections' => array() with arrays of sections and put the 'fields' => array() with arrays of fields in it. You can find examples here.
• In order to use tabs, just provide 'tabs' => array() with an array of tabs and put either 'sections' => array() or 'fields' => array() in it. Here is an example for meta boxes and options pages.

And, of course, you can put any field types in sections or tabs.

Conditional Logic

You can easily configure one field to be displayed depending on the value of another field. Just add show_if parameter.

Example:

add_filter( 'simple_register_metaboxes', 'misha_product_metabox' );
 
function misha_product_metabox( $metaboxes ) {
 
	$metaboxes[] = array(
 		'id'	=> 'my_product_metabox',
 		'name'	=> 'Meta Box',
 		'post_type' => array( 'product' ),
 		'fields' => array(
			array(
				'id' => 'product_type',
				'label' => 'Product type',
				'type' => 'radio',
				'default' => 'virtual',
				'options' => array(
					'virtual' => 'Virtual',
					'physical' => 'Physical',
				),
			),
			array(
				'id' => 'items_in_stock',
				'label' => 'Items in stock',
				'type' => 'number',
				'default' => 1,
				'show_if' => array(
					'id' => 'product_type',
					'value' => 'physical',
				),
			)
 		)
 	);
 
	return $metaboxes;
 
}

Take a look at this piece:

'show_if' => array(
	'id' => 'product_type', // ID of another field it depends on
	'value' => 'physical', // value of another field
),

How to Get (and Print) Custom Fields Values?

In order to get any custom field value, you can use WordPress default functions.

• get_post_meta() – for posts, pages, and custom post types.
• get_term_meta() – for categories, tags, and custom taxonomies.
• get_option() – for fields in site option pages.
• get_user_meta() – for users’ custom fields.
• get_comment_meta() – for comments custom fields.

You can find the detailed description of all these functions in the official WordPress documentation easily. The usage of all of them is quite similar (maybe except get_option()).

echo get_post_meta( $id, 'my_field', true );
// here we are printing the value of "my_field" custom field

So, as for get_post_meta(), get_term_meta(), get_comment_meta(), get_user_meta() you just have to pass an element ID in the first parameter and the field name in the second one. That’s pretty much it.

echo get_option( 'my_option' );
// here we are printing the value of "my_option" settings field

For website settings, all we need is a settings field name.

How to get the ID of an element we want to print a custom field for?

Well, it depends on what type of element it is and where you are going to print the field’s value. But there are some common rules.

• For posts, pages, and custom types, in most cases, you can use get_the_ID() function.
• For terms on their archive pages – get_queried_object_id().
• In order to get the current user ID, you can use get_current_user_id().

In the example below, we are going to print a taxonomy’s additional content:

// term title (the standard way of printing it)
single_term_title();

// term content
echo wpautop( get_term_meta( get_queried_object_id(), 'my_content', true ) );

I used wpautop() function above as well to add paragraphs and new lines.

How to print an image?

When you work with the Image or Gallery field, please keep in mind that the plugin only stores image IDs in the database.

So, when you are going to use any of the functions to get the field value, you will get a number.

Then you have to use one of these WordPress functions:

• wp_get_attachment_image() – to get the HTML tag of an image.
• wp_get_attachment_url(), wp_get_attachment_image_src() – to get an attachment URL.

Once again, these functions are well documented in official WordPress docs. Here is a simple example:

$image_id = get_term_meta( get_queried_object_id(), 'my_img', true );

echo wp_get_attachment_image( $image_id, 'full' );

You can also see that I added one more argument to the function, full means that we have to use the original image size, but there are some more of them that could exist on your website, like thumbnail, medium, large etc.