Super_Custom_Post_Meta Reference

Super_Custom_Post_Meta is both a wrapper for, and significantly extends upon WordPress' native add_meta_box. It allows you to easily customize the Admin editing UI to support custom data.

Method Reference

Constructor

$meta = new Super_Custom_Post_Meta( $post_type )

Construct a new Super_Custom_Post_Meta object for the given post type.

Parameters

string $post_type

The post type for which the object's meta boxes will exist. Can be 'post', 'page', or the slug of any custom post type.

add_meta_box, add_meta_boxes

$meta->add_meta_box( $attr = array() )
$meta->add_meta_boxes( $attr1[, $attr2][, ...] )

Add custom meta box or many boxes.

Parameters

array $attr

The meta box attributes. See http://codex.wordpress.org/Function_Reference/add_meta_box for details. If using `add_meta_boxes`, simply pass it multiple $attr arrays.

Array Attributes

string 'id'

(required) HTML 'id' attribute of the edit screen section

string 'title'

(optional) Title of the edit screen section, visible to user. If absent, 'id' is converted to words.

string | array 'callback'

(optional) Function that prints out the HTML for the edit screen section. Pass function name as a string. Within a class, you can instead pass an array to call one of the class's methods. By default, `Super_Custom_Post_Meta` provides this for you, but you can pass this to override it. If you do that, there's practically no point to using this class.

string 'page'

(optional) The type of Write screen on which to show the edit screen section ('post', 'page', 'link', or 'custom_post_type' where `custom_post_type` is the custom post type slug). Default: `$this->type` (the type provided when instantiating the class)

string 'context'

(optional) The part of the page where the edit screen section should be shown ('normal', 'advanced', or 'side'). Default: 'advanced'. If side, fields may display slightly different to fit (e.g. wysiwyg editors have reduced toolbars)

string 'priority'

(optional) The priority within the context where the boxes should show ('high', 'core', 'default' or 'low'). Default: 'default'

array 'fields'

(required) Associative array of fields, indexed by meta_key. See below.

Fields

Fields are created through add_meta_box and have many (intuitive) options. The options are passed as an associative array, within another associative array of multiple fields. The latter array of fields is indexed by meta_key (truthfully, this is optional -- it can be numerically indexed and you can set 'meta_key' explicitly). Since this becomes a triple-nested array, it sounds confusing, but I promise it isn't. Here is an example:

$meta->add_meta_box( array(
	'id' => 'staff_details',
	'fields' => array(
		'name' => array( 'type' => 'text' ),
		'bio' => array( 'type' => 'textarea' )
	)
)

Field array attributes

string 'meta_key'

(semi-optional) If this array's parent array is associative, the key becomes the meta key. If the parent array is numeric, you have to specify the meta_key directly. The `meta_key` is the field name and the data is stored in the database under this key name

string 'type'

(optional) The field type. Defaults to 'text', otherwise can be one of

• text
• textarea
• wysiwyg
• media
• boolean (a checkbox and a hidden field; the value is explicitly stored as 0 or 1)
• checkbox*
• radio*
• select*
• date -- gets a jQuery datepicker
• Any HTML5 input type (email, url, tel, etc.)

string 'label'

(optional) The content of the <label> tag. If false, a label is not displayed.

array 'options'

(optional) This applies to the field types above with a *. you can pass options an array of fields to create many checkboxes, radio buttons, or select options. If associative, the "value" is populated by the array key. Otherwise, "value" is the same as the text/label. Examples: 'options' => array('Vermont','New Hampshire','Maine'), 'options' => array('VT' => 'Vermont', 'NH' => 'New Hampshire', 'ME' => 'Maine'). If a radio button has no options, it becomes a checkbox. If a checkbox has no options, it becomes a boolean.

string 'data'

(optional) The name of a post type to allow one-to-one, one-to-many, or many-to-many associations. See The Wiki Homepage for an example of this.

string|bool 'prompt'

(optional) For select dropdowns, by default, the first option is "Choose one". You can override this by passing another string through this key, or disable it by passing false.

bool 'column'

(optional) If true, adds a hook for `manage_posts_custom_column` and adds the field to the lists in the admin panel.

mixed 'default'

(optional) If set, the field will default to this value. For boolean fields, pass `'default' => 'checked'`. For radio buttons and select dropdowns, pass the value (that would be in the "value" attribute) that should be selected. For multi-select fields and lists of checkboxes, pass an array of values (that would be in the "value" attribute.

Anything passed through this array not in the above will become html attributes as $key=>"$val". For instance, to make a select box a multiple select, you would include 'multiple' => 'multiple' in your array. Try to avoid setting 'value', 'id', 'class', and 'name', as SuperCPT sets these, unless you actually want to override them.

add_to_columns

$meta->add_to_columns( $meta_key );
$meta->add_to_columns( $taxonomy_slug );
$meta->add_to_columns( array( $key => $label, ... ) );

Add to the columns in the post type list in wp-admin (manage edit columns). You can add post meta or term relationships for a taxonomy.

Parameters

string|array $key

The data to include in a column. It can be any post meta key, the slug for a taxonomy (like 'post_tag', 'category', or a custom taxonomy), or an associative array with $key => $label pairs.

Columnizing a field generated with SuperCPT can be done more easily by setting `'column' => true` in the add_meta_box fields array (see Fields above).

For the most part, SuperCPT only knows how to display post meta for fields it created, but you can use any meta key here and its contents will be output as stored in the postmeta table. The only exception is `_thumbnail_id` (core's featured image meta key), which will be output as a thumbnail image.

Labels are derived automatically from `$key`. Again, the only exception is `_thumbnail_id` which becomes "Thumbnail". You can override the automatically derived labels if `$key` is an associative array, e.g. `array( 'my_meta' => 'My Label' )`.