custom_metadata_examples.php

<?php
/**
 * Example field, group and multifield registrations for the Custom Metadata Manager plugin.
 *
 * Copyright 2010-2013 The Contributors
 *
 * GNU General Public License, Free Software Foundation <http://creativecommons.org/licenses/GPL/2.0/>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * @package Automattic\CustomMetadata
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

add_action( 'init', 'x_init_custom_post_types' );
/**
 * Registers a test post type just for the examples.
 *
 * @return void
 */
function x_init_custom_post_types() {

	$labels = array(
		'name'               => _x( 'Tests', 'post type general name', 'custom-metadata' ),
		'singular_name'      => _x( 'Test', 'post type singular name', 'custom-metadata' ),
		'add_new'            => _x( 'Add New', 'Test', 'custom-metadata' ),
		'add_new_item'       => __( 'Add New Test', 'custom-metadata' ),
		'edit_item'          => __( 'Edit Test', 'custom-metadata' ),
		'new_item'           => __( 'New Test', 'custom-metadata' ),
		'all_items'          => __( 'All Tests', 'custom-metadata' ),
		'view_item'          => __( 'View Test', 'custom-metadata' ),
		'search_items'       => __( 'Search Tests', 'custom-metadata' ),
		'not_found'          => __( 'No Tests found', 'custom-metadata' ),
		'not_found_in_trash' => __( 'No Tests found in Trash', 'custom-metadata' ),
		'parent_item_colon'  => '',
		'menu_name'          => 'Tests',

	);
	$args = array(
		'labels'             => $labels,
		'public'             => true,
		'publicly_queryable' => true,
		'show_ui'            => true,
		'show_in_menu'       => true,
		'query_var'          => true,
		'rewrite'            => true,
		'capability_type'    => 'post',
		'has_archive'        => true,
		'hierarchical'       => false,
		'menu_position'      => null,
		'supports'           => array( 'title' ),
	);
	register_post_type( 'x_test', $args );
}


add_action( 'custom_metadata_manager_init_metadata', 'x_init_custom_fields' );
/**
 * Registers custom metadata groups and fields.
 *
 * This is the example code that you should use. Make sure to use the
 * 'custom_metadata_manager_init_metadata' hook as below.
 */
function x_init_custom_fields() {

	// adds a new group to the test post type.
	x_add_metadata_group(
		'x_metaBox1',
		'x_test',
		array(
			'label' => 'Group with Multiple Fields',
		) 
	);

	// adds another group to the test post type + posts + users.
	x_add_metadata_group(
		'x_metaBox2',
		array( 'x_test', 'post', 'user' ),
		array(
			'label'       => 'Group for Post and User',
			'description' => "Here's a group with a description!",
		) 
	);

	// adds a text field to the first group.
	x_add_metadata_field(
		'x_fieldName1',
		'x_test',
		array(
			'group'          => 'x_metaBox1', // the group name.
			'description'    => 'This is field #1. It\'s a simple text field.', // description for the field.
			'label'          => 'Text Field', // field label.
			'display_column' => true, // show this field in the column listings.
		) 
	);

	// adds a text field to the 2nd group.
	x_add_metadata_field(
		'x_fieldName2',
		'x_test',
		array(
			'group'                   => 'x_metaBox1',
			'display_column'          => 'My Column (with Custom Callback)', // show this field in the column listings.
			'display_column_callback' => 'x_field_name2_callback', // custom function to display the column results (see below).
			'label'                   => 'Text with Custom Callback',
		) 
	);


	// adds a cloneable textarea field to the 1st group.
	x_add_metadata_field(
		'x_fieldTextarea1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'textarea',
			'multiple'   => true,
			'label'      => 'Repeatable Text Area',
		) 
	);

	// adds a readonly textarea field to the 1st group.
	x_add_metadata_field(
		'x_fieldTextareaReadOnly1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'textarea',
			'readonly'   => true,
			'label'      => 'Read Only Text Area',
		) 
	);

	// adds a readonly text field to the 1st group.
	x_add_metadata_field(
		'x_fieldTextReadOnly1',
		'x_test',
		array(
			'group'    => 'x_metaBox1',
			'readonly' => true,
			'label'    => 'Read Only Text Area',
		) 
	);

	// adds a wysiwyg (full editor) field to the 2nd group.
	x_add_metadata_field(
		'x_fieldWysiwyg1',
		array( 'x_test', 'user' ),
		array(
			'group'      => 'x_metaBox2',
			'field_type' => 'wysiwyg',
			'label'      => 'TinyMCE / Wysiwyg field',
		) 
	);

	// adds a datepicker field to the 1st group.
	x_add_metadata_field(
		'x_fieldDatepicker1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'datepicker',
			'label'      => 'Datepicker field',
		) 
	);

	// adds a datetimepicker field to the 1st group.
	x_add_metadata_field(
		'x_fieldDatetimepicker1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'datetimepicker',
			'label'      => 'Datetimepicker field',
		) 
	);

	// adds a timepicker field to the 1st group.
	x_add_metadata_field(
		'x_fieldTimepicker1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'timepicker',
			'label'      => 'Timepicker field',
		) 
	);

	// adds a colorpicker field to the 1st group.
	x_add_metadata_field(
		'x_fieldColorpicker1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'colorpicker',
			'label'      => 'Colorpicker field',
		) 
	);

	// adds an upload field to the 1st group.
	x_add_metadata_field(
		'x_fieldUpload1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'upload',
			'readonly'   => true,
			'label'      => 'Upload field',
		) 
	);

	// adds a checkbox field to the first group.
	x_add_metadata_field(
		'x_fieldCheckbox1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'checkbox',
			'label'      => 'Checkbox field',
		) 
	);

	// adds a radio button field to the first group.
	x_add_metadata_field(
		'x_fieldRadio1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'radio',
			'values'     => array(     // set possible value/options.
				'option1' => 'Option #1', // key => value pair (key is stored in DB).
				'option2' => 'Option #2',
			),
			'label'      => 'Radio field',
		) 
	);

	// adds a select box in the first group.
	x_add_metadata_field(
		'x_fieldSelect1',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'select',
			'values'     => array(     // set possible value/options.
				'option1' => 'Option #1', // key => value pair (key is stored in DB).
				'option2' => 'Option #2',
			),
			'label'      => 'Select field',
		) 
	);

	// adds a multi-select field in the first group.
	x_add_metadata_field(
		'x_field_multi_select',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'multi_select',
			'values'     => array(     // set possible value/options.
				'option1' => 'Option #1', // key => value pair (key is stored in DB).
				'option2' => 'Option #2',
				'option3' => 'Option #3',
				'option4' => 'Option #4',
			),
			'label'      => 'Multi Select field',
		) 
	);

	// adds a multi-select field with chosen in the first group
	// note: `select2` and `chosen` args do the exact same (add select2)
	// but for the purposes of testing, we're using chosen here.
	x_add_metadata_field(
		'x_field_multi_select_chosen',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'multi_select',
			'values'     => array(     // set possible value/options.
				'option1' => 'Option #1', // key => value pair (key is stored in DB).
				'option2' => 'Option #2',
				'option3' => 'Option #3',
				'option4' => 'Option #4',
			),
			'label'      => 'Multi Select field (with chosen)',
			'chosen'     => true,
		) 
	);

	// adds a select field with select2 in the first group.
	x_add_metadata_field(
		'x_field_select_select2',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'select',
			'values'     => array(     // set possible value/options.
				'option1' => 'Option #1', // key => value pair (key is stored in DB).
				'option2' => 'Option #2',
				'option3' => 'Option #3',
				'option4' => 'Option #4',
			),
			'label'      => 'Select field (with select2)',
			'select2'    => true,
		) 
	);

	// adds a taxonomy checkbox field in the first group.
	x_add_metadata_field(
		'x_field_taxonomy_checkbox',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'taxonomy_checkbox',
			'taxonomy'   => 'category',
			'label'      => 'Category checkbox field',
		) 
	);

	// adds a taxonomy select field in the first group.
	x_add_metadata_field(
		'x_field_taxonomy_select',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'taxonomy_select',
			'taxonomy'   => 'category',
			'label'      => 'Category select field',
		) 
	);

	// adds a taxonomy multiselect field in the first group.
	x_add_metadata_field(
		'x_field_taxonomy_multi_select',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'taxonomy_multi_select',
			'taxonomy'   => 'category',
			'label'      => 'Category multiselect field',
		) 
	);

	// adds a taxonomy multiselect w/ select2 field in the first group.
	x_add_metadata_field(
		'x_field_taxonomy_multi_select2',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'taxonomy_multi_select',
			'taxonomy'   => 'category',
			'label'      => 'Category multiselect w/ select2 field',
			'select2'    => true,
		) 
	);

	// adds a number field in the first group (with no min/max).
	x_add_metadata_field(
		'x_field_number',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'number',
			'label'      => 'Number field',
		) 
	);

	// adds a number field in the first group (with min/max).
	x_add_metadata_field(
		'x_field_number_with_min_max',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'number',
			'min'        => '-3',
			'max'        => '25',
			'multiple'   => true,
			'label'      => 'Number field (with min/max + cloneable)',
		) 
	);

	// adds an email field in the first group.
	x_add_metadata_field(
		'x_field_email',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'email',
			'label'      => 'Email field',
		) 
	);

	// adds a link field in the first group.
	x_add_metadata_field(
		'x_field_link',
		'x_test',
		array(
			'group'      => 'x_metaBox1',
			'field_type' => 'link',
			'label'      => 'Link field',
		) 
	);

	// adds a telephone field in the first group (with default value).
	x_add_metadata_field(
		'x_field_telephone',
		'x_test',
		array(
			'group'         => 'x_metaBox1',
			'field_type'    => 'tel',
			'label'         => 'Telephone field',
			'default_value' => '123-4567',
		) 
	);

	// adds a text field with a default value.
	x_add_metadata_field(
		'x_field_text_default',
		'x_test',
		array(
			'group'         => 'x_metaBox1',
			'field_type'    => 'text',
			'label'         => 'Text field with default value',
			'default_value' => 'lorem ipsum',
		) 
	);

	// adds a text field with placeholder.
	x_add_metadata_field(
		'x_field_textarea_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'textarea',
			'label'       => 'Textarea field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds a password field with placeholder.
	x_add_metadata_field(
		'x_field_password_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'password',
			'label'       => 'Password field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds a number field with placeholder.
	x_add_metadata_field(
		'x_field_number_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'number',
			'label'       => 'Number field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds an email field with placeholder.
	x_add_metadata_field(
		'x_field_email_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'email',
			'label'       => 'Email field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds a link field with placeholder.
	x_add_metadata_field(
		'x_field_link_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'link',
			'label'       => 'Link field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds an telephone field with placeholder.
	x_add_metadata_field(
		'x_field_telephone_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'tel',
			'label'       => 'Telephone field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds an upload field with placeholder.
	x_add_metadata_field(
		'x_field_upload_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'upload',
			'label'       => 'Upload field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds an datepicker field with placeholder.
	x_add_metadata_field(
		'x_field_datepicker_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'datepicker',
			'label'       => 'Datepicker field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds a datetimepicker field with placeholder.
	x_add_metadata_field(
		'x_field_datetimepicker_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'datetimepicker',
			'label'       => 'Datetimepicker field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds a timepicker field with placeholder.
	x_add_metadata_field(
		'x_field_timepicker_placeholder',
		'x_test',
		array(
			'group'       => 'x_metaBox1',
			'field_type'  => 'timepicker',
			'label'       => 'Timepicker field with placeholder',
			'placeholder' => 'some placeholder text',
		) 
	);

	// adds a mulitifield.
	x_add_metadata_multifield(
		'x_test_multifield',
		'x_test',
		array(
			'group'       => 'x_metabox1',
			'label'       => 'Multifield test',
			'description' => 'This is a great multifield',
		) 
	);

	// adds a text field to the multifield.
	x_add_metadata_field(
		'multifield_field_1',
		'x_test',
		array(
			'group'       => 'x_metabox1', // the group name.
			'multifield'  => 'x_test_multifield',
			'description' => 'This is field #1 of the multifield.',
			'label'       => 'Text Field', // field label.
			'field_type'  => 'text',
		) 
	);

	// adds an upload text field to the multifield.
	x_add_metadata_field(
		'multifield_field_2',
		'x_test',
		array(
			'group'       => 'x_metabox1', // the group name.
			'multifield'  => 'x_test_multifield',
			'description' => 'This is field #2 of the multifield.',
			'label'       => 'Upload Field', // field label.
			'field_type'  => 'upload',
		) 
	);


	// adds an upload text field to the multifield.
	x_add_metadata_field(
		'multifield_field_3',
		'x_test',
		array(
			'group'       => 'x_metabox1', // the group name.
			'multifield'  => 'x_test_multifield',
			'description' => 'This is field #4 of the multifield.',
			'label'       => 'Telephone Field', // field label.
			'field_type'  => 'tel',
		) 
	);

	// adds a text field to the multifield.
	x_add_metadata_field(
		'multifield_field_4',
		'x_test',
		array(
			'group'       => 'x_metabox1', // the group name.
			'multifield'  => 'x_test_multifield',
			'description' => 'This is field #4 of the multifield.',
			'label'       => 'Password Field', // field label.
			'field_type'  => 'password',
		) 
	);


	// adds a field to posts and users.
	x_add_metadata_field(
		'x_fieldName2',
		array( 'post', 'user' ),
		array(
			'group' => 'x_metaBox2',
			'label' => 'Text field',
		) 
	);

	// adds a field with a custom display callback (see below).
	x_add_metadata_field(
		'x_fieldCustomHidden1',
		'x_test',
		array(
			'group'            => 'x_metaBox1',
			'display_callback' => 'x_field_customhidden1_callback', // this function is defined below.
			'label'            => 'Hidden field',
		) 
	);


	// field with capabilities limited.
	x_add_metadata_field(
		'x_cap-limited-field',
		'x_test',
		array(
			'label'        => 'Cap Limited Field (edit_posts)',
			'required_cap' => 'edit_posts', // limit to users who can edit posts.
		) 
	);

	// field with role limited.
	x_add_metadata_field(
		'x_author-cap-limited-field',
		'user',
		array(
			'label'        => 'Cap Limited Field (author)',
			'required_cap' => 'author', // limit to authors.
		) 
	);

	// comment field.
	x_add_metadata_field(
		'x_commentField1',
		'comment',
		array(
			'label'          => 'Field for Comment',
			'display_column' => true,
		) 
	);

	// field that exludes posts.
	x_add_metadata_field(
		'x_fieldNameExcluded1',
		'post',
		array(
			'description' => 'This field is excluded from Post ID#2476',
			'label'       => 'Excluded Field',
			'exclude'     => 2476, // phpcs:ignore WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_exclude -- Plugin field-visibility config key, not a WP_Query argument.
		) 
	);

	// field that includes certain posts only.
	x_add_metadata_field(
		'x_fieldNameIncluded1',
		'post',
		array(
			'description' => 'This field is only included on Post ID#2476',
			'label'       => 'Included Field',
			'include'     => 2476,
		) 
	);

	x_add_metadata_field(
		'x_fieldExcludeCallback',
		'post',
		array(
			'description' => 'This field is excluded using a custom callback; will be excluded from posts in the "aside" category',
			'label'       => 'Excluded Field (with callback)',
			'exclude'     => 'x_custom_exclude_callback', // phpcs:ignore WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_exclude -- Plugin field-visibility config key, not a WP_Query argument.
		) 
	);

	/**
	 * Determines whether a field should be excluded because the post is in the "aside" category.
	 *
	 * @param string     $thing_slug Slug of the field or group.
	 * @param object     $thing Field or group args set up when registering.
	 * @param string     $object_type Type of object (post, comment, user).
	 * @param int|string $object_id ID of the object.
	 * @param string     $object_slug Slug of the object.
	 * @return bool Whether the field should be excluded.
	 */
	function x_custom_exclude_callback( $thing_slug, $thing, $object_type, $object_id, $object_slug ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Example callback showing the full signature the plugin provides.
		// exclude from all posts that are in the aside category.
		return in_category( 'aside', $object_id );
	}

	x_add_metadata_field(
		'x_fieldIncludedCallback',
		'post',
		array(
			'description' => 'This field is included using a custom callback; will only be included for posts that are not published',
			'label'       => 'Included Field (with callback)',
			'include'     => 'x_custom_include_callback',
		) 
	);

	/**
	 * Includes a field only for posts that are not published.
	 *
	 * @param string     $thing_slug Slug of the field or group.
	 * @param object     $thing Field or group args set up when registering.
	 * @param string     $object_type Type of object (post, comment, user).
	 * @param int|string $object_id ID of the object.
	 * @param string     $object_slug Slug of the object.
	 * @return bool Whether the field should be included.
	 */
	function x_custom_include_callback( $thing_slug, $thing, $object_type, $object_id, $object_slug ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Example callback showing the full signature the plugin provides.
		$post = get_post( $object_id );
		return 'publish' != $post->post_status;
	}
}

/**
 * Example of a column callback function.
 *
 * It echoes out a bogus description, but it is just so you can see how it works.
 *
 * @param string $field_slug The slug/ID of the field.
 * @param object $field The field object.
 * @param string $object_type The object type the field is associated with.
 * @param int    $object_id The ID of the current object.
 * @param string $value The value of the field.
 * @return void
 */
function x_field_name2_callback( $field_slug, $field, $object_type, $object_id, $value ) {
	// Escape the dynamic values on output; the surrounding markup is our own, so it stays.
	printf( 'The value of field "%s" is %s. <br /><a href="http://icanhascheezburger.files.wordpress.com/2010/10/04dc84b6-3dde-45db-88ef-f7c242731ce3.jpg">Here\'s a LOLCat</a>', esc_html( $field_slug ), $value ? esc_html( $value ) : 'not set' );
}

/**
 * Another example of a custom callback function.
 *
 * We have chosen not to include all of the params this time.
 *
 * @param string $field_slug The slug/ID of the field.
 * @param object $field The field object.
 * @param mixed  $value The value of the field.
 * @return void
 */
function x_field_customhidden1_callback( $field_slug, $field, $value ) {
	if ( ! $value ) {
		$value = 'This is a secret hidden value! Don\'t tell anyone!';
	}
	?>
	<hr />
	<p>This is a hidden field rendered with a custom callback. The value is "<?php echo esc_html( $value ); ?>".</p>
	<input type="hidden" name="<?php echo esc_attr( $field_slug ); ?>" value="<?php echo esc_attr( $value ); ?>" />
	<hr />
	<?php
}