WP Metaboxer

WordPress metabox builder plugin

• Created: 03/10/2011
• latest Update: 10/14/2012
• By: Nico Amarilla
• Email: kosinix@codefleet.net

Create WordPress metaboxes with ease. Provides an easy to use interface for building metaboxes with many field types to choose from.

Introduction

Create WordPress metaboxes with ease. Provides an easy to use interface for building metaboxes with many field types to choose from.

Features:

• Easy to use interface for creating metaboxes and custom fields.
• Metabox can be added to Post, Page or Custom Posts.
• Metabox position is configurable.
• Metabox priority is configurable.
• Textboxes, Textareas and Sortable textboxes can be set to allow/disallow HTML or accept raw data.
• Selectboxes, Radio, and Checkbox Group can use a data source to get their options. A data source is a callable user defined function that returns an array of value and texts.
• Add unlimited number of images by using Sortable Image field. The order can be changed via drag and drop.
• Add unlimited number of files by using Sortable File field. The order can be changed via drag and drop.
• Add unlimited number of textboxes by using Sortable Textbox field. The order can be changed via drag and drop.
• Utility functions for fetching the custom field values.
• Ability to export the metaboxes and include it in your theme without the need for the plugin.

The following field types are available:

• Textbox
• Textarea
• Selectbox
• Checkbox
• Radio
• Date
• Time
• Datetime
• Checkbox Group
• Sortable Images
• Sortable Files
• Sortable Textboxes
• Youtube Videos
• Vimeo Videos

Installation

Install via WordPress Admin

1. Ready the zip file of the plugin
2. Go to Admin > Plugins > Add New
3. On the upper portion click the Upload link
4. Using the file upload field, upload the plugin zip file here and activate the plugin

Install via FTP

1. First unzip the plugin file
2. Using FTP go to your server's wp-content/plugins directory
3. Upload the unzipped plugin here
4. Once finished login into your WP Admin and go to Admin > Plugins
5. Look for WP Metaboxer and activate it

Adding a MetaBox

The steps for adding a metabox is simple and straightforward. It is similar to adding a WordPress post or page. Below are steps to add a metabox:

1. Go to Admin > WP Metaboxer.
2. Click "Add Metabox". You will be taken to the Add New Metabox screen.
3. In the title area type the name of your metabox.
4. On the right side, look for the "Properties" panel.
5. In the "Properties" panel choose in what admin area would you like to show the metabox.
   1. Page - Show your metabox when adding or editing a page in Admin > Pages
   2. Post - Show your metabox when adding or editing a post in Admin > Posts
   3. [Custom Posts] - The options here will depend on what other custom posts your site is using.
6. Now choose your "Metabox Position". The default value should be ok no need to change it.
7. Choose your "Metabox Priority". The default value should also be ok.
8. Thats it! Now click "Publish".

To check your newly added metabox, go to Admin > Pages > Add New if you checked Page in the Properties panel. If you checked Post then go to Admin > Posts > Add New. You should now see your metabox with the title that you specified. 

However, the metabox has no fields yet. To add fields, head over to the Adding Fields section.

Adding Fields

Note: If you have not created a metabox yet, please check the Adding a Metabox section.

In this example we will be adding a Textbox and Textarea to our metabox.

1. Inside the metabox builder screen, click the Textbox button.
2. A new box with a name "Textbox" will appear.
3. Now add a "Label" for the textbox. As the name implies, it will serve as a label for your field. For example: My Sample Textbox
4. Now add a "Unique Key". WP Metaboxer will automatically suggest a Unique Key based on the Label. You can change it if you like. Note: unique keys can only have alphanumeric and underscore characters.
5. Thats it! You can hit Update button and see your Textbox field in action.

Note: Textboxes and other fields have additional options that can be accessed by clicking "More Settings" in a fields box. For more info on what these options are, check the Field Settings Referrence section.

Adding a Textarea

1. Inside the metabox builder screen, click the Textarea button.
2. A new box with a name "Textarea" will appear.
3. Now add a "Label" for the textbox. As the name implies, it will serve as a label for your field. For example: My Sample Textarea
4. Now add a "Unique Key". WP Metaboxer will automatically suggest a Unique Key based on the Label. You can change it if you like. Note: unique keys can only have alphanumeric and underscore characters.
5. Thats it! You can hit Update button and see your Textarea field in action.

WP Metaboxer in Action

Working With Fields

Whereas the previous sections refer to the WP Metaboxer's builder screen, this section refers to the actual usage of your custom metabox and custom fields inside the Post or Page edit screen.

Note: If you have not added the fields yet, please check the Adding Fields section.

To add data to your custom fields:

1. In the Page/Post edit screen, look for the metabox that you have added.
2. Add the data for the textbox. Eg. "Hello world!"
3. Add the data for the textarea. Eg. "Hello universe!"
4. Click Update. Thats it!

Custom Metabox With Fields and Data

Using the Sortable Images

This field uses WordPress Media Uploader. To add an image:

1. Click the Add Image button.
2. The WordPress Media Uploader pop-up form will appear.
   1. Upload from computer
      1. To add an image from your computer click Select Files button
      2. Choose the image(s) you want to upload.
      3. When the upload is done, click Insert to Metabox button
   2. Add from Media Library
      1. On the Media Uploader pop-up form, click the "Media Library" tab
      2. Inside this tab, click "Show" for the image you wish to add.
      3. Click the Insert to Metabox button
3. Repeat steps to add more images

Using the Sortable Files

1. Click the Add File button.
2. The WordPress Media Uploader pop-up form will appear.
   1. Upload from computer
      1. To add a file from your computer click Select Files button
      2. Choose the file(s) you want to upload.
      3. When the upload is done, click Insert to Metabox button
   2. Add from Media Library
      1. On the Media Uploader pop-up form, click the "Media Library" tab
      2. Inside this tab, click "Show" for the file you wish to add.
      3. Click the Insert to Metabox button
3. Repeat steps to add more files

Using the Sortable Textboxes

1. Click Add Textbox.
2. Type data inside the textboxes similar to a regular textbox.
3. Repeat step 1 to add more.

Using the Vimeo and Youtube Fields

1. Click the Add Vimeo Video or Add Youtube Video.
2. Paste the url of the video in the textbox. Examples:
   
   1. For Youtube: http://www.youtube.com/watch?v=PNZXXqmc-KA
   2. For Vimeo: http://vimeo.com/29144891
3. Repeat to add more videos

WP Metaboxer will fetch the thumbnail for the videos. Invalid urls will have no thumbnails returned.

Deleting a Custom Field's Data

Each field has a "Delete" checkbox at the right side. Check it on every field you wish to delete and click Update. This will delete the custom field data from the database.

Note: For selectboxes, it is important to add a blank option (option with value set to nothing) if you want its data to remain deleted on every Post/Page save.

Accessing Your Data

This section describes how to access the data from the custom fields. It assumes you have a good understanding of WordPress themes and PHP.

WP Metaboxer utilizes WordPress Custom Fields API. WP Metaboxer provides two utility functions:

mtbxr_val - Get a single field's value by passing the Unique Key. Returns whatever value is saved for a field.

mtbxr_all - Get all fields from a post. Returns an array of values.

Function mtbxr_val

Using mtbxr_val, pass the field's Unique Key. For example, inside the WordPress loop, you can do this:

$my_textbox_value = mtbxr_val("my_textbox");
echo $my_textbox_value;

Optionally, you can specify the ID of a post. It is handy if you are using it outside the WordPress Loop:

$my_textbox_value = mtbxr_val("my_textbox", $post_id);
echo $my_textbox_value;

Function mtbxr_all

The mtbxr_all on the other hand will return an array of values of all custom fields associated with a post:

$my_fields = mtbxr_all();
$my_textbox_value = $my_fields['my_textbox'];

The advantage of mtbxr_all is you only need to call this function once to get all the field values.

Note: Since WP Metaboxer is using Custom Fields API you can still use the built-in WP functions like: get_post_meta and get_post_custom. However mtbxr_all, compared to get_post_custom, will simplify the array and will automatically unserialize the values for you.

Function mtbxr_video

This function applies only to Youtube and Vimeo fields.  It will display the video in embedded format. That means it will show the video and its player in your page as if the video was embedded in your page.

To use it you need to pass along the Unique Key of your field. For example inside your template file:

echo mtbxr_video('vimeo_sample');

Since the Youtube and Vimeo fields are stored as an array, by default it will return the first video associated with the custom field. To specify a different video, use the index parameter. The index starts at 0.

Example - Display first video:

echo mtbxr_video('vimeo_sample', 0);

Example - Display second video:

echo mtbxr_video('vimeo_sample', 1);

Function mtbxr_videos

This function applies only to Youtube and Vimeo fields.  It will return an array of videos in embedded format. You can use a loop to display the videos.

if($youtube_videos = mtbxr_videos('youtube_sample')){
    foreach($youtube_videos as $youtube_video){
        echo $youtube_video;
    }
}

Or you can point to a specific video to display by specifying the array index:

if($youtube_videos = mtbxr_videos('youtube_sample')){
    echo $youtube_videos[0]; //First video
    echo $youtube_videos[1]; //Second video
}

Date, Time and Datetime

Date, time and datetime are stored as timestamp. You can use PHP's date function to output it to your preferred format.

Example 1 - Display Date:

$timestamp = mtbxr_val("my_custom_date");
echo date('M d, Y', $timestamp);

Will output date in this format: Oct 08, 2012. Of course the date will depend on the value of timestamp.

Example 2 - Display Time:

$timestamp = mtbxr_val("my_custom_time");
echo date('h:i:s A', $timestamp);

Will output time in this format: 07:25:10 AM. The time will depend on the value of timestamp.

Example 3 - Display Datetime:

$timestamp = mtbxr_val("my_custom_datetime");
echo date('F d, Y h:i:s A', $timestamp);

Will output something like October 08, 2012 07:28:49 AM. Output will depend on value of timestamp.

Sortable Images and Sortable Files

Sortable Images and Files are stored as an array of attachment ID.

Example 1 - Display Images:

$images = mtbxr_val('sortable_images_sample');
if( is_array($images) ){
    foreach($images as $attachment_id){
        $attachment_data = wp_get_attachment_image_src( $attachment_id, 'large' );
        $image_url = $attachment_data[0];
        ?>
        <img src="<?php echo $image_url; ?>" alt="" />
        <?php
    }
}

Here we loop thru the attachment IDs and used WP's wp_get_attachment_image_src function to fetch the url of the image.

Example 2 - Display Files:

$files = mtbxr_val('sortable_files');
if( is_array($files) ){
    foreach($files as $attachment_id){
        $file_url = wp_get_attachment_url( $attachment_id );
        ?>
        <p><?php echo $file_url; ?></p>
        <?php
    }
}

Here we loop again thru the attachment IDs and used wp_get_attachment_url function to fetch the url of the files and display it.

Tip: A very handy method in inspecting what custom fields are associated with a post is by using print_r, or better yet, WP Metaboxer's mtbxr_debug:

echo mtbxr_debug( mtbxr_all() );

You can place this code inside your template files (eg. single.php, page.php...) preferably inside The Loop.

Youtube and Vimeo Videos

You can use mtbxr_video and mtbxr_videos function to display the videos in embedded format.  You can also use mtbxr_all or mtbxr_val if you want to return the videos the way you entered it, that is in url format.

Example 1

echo mtbxr_video('vimeo_sample');

Example 2

if($youtube_videos = mtbxr_videos('youtube_sample')){
    foreach($youtube_videos as $youtube_video){
        echo $youtube_video;
    }
}

Example 3 - First video, 500x300 dimension, with post ID specified

echo mtbxr_video('vimeo_sample', 0, 500, 300, $post_id); 

Field Settings Reference

This section contains the description of each field settings.

function mytheme_custom_options(){
	return array(
		array(
			'value'=>'',
			'text'=>''
		),
		array(
			'value'=>'1',
			'text'=>'Male'
		),
		array(
			'value'=>'2',
			'text'=>'Female'
		)
	);
}

Field Type Reference

This section contains the field types that can be added to your custom metabox.

Filters

Filters allow you to easily alter the data of WP Metaboxer.

function mytheme_filter_select_options($options, $field){
    if($field['uid']=='countries'){
        $options = array(
            array(
                'value'=> 'au',
                'text'=> 'Australia'
            ),
            array(
                'value'=> 'us',
                'text'=> 'United States'
            ),
            array(
                'value'=> 'uk',
                'text'=> 'United Kingdom'
            )
        );
    }
    return $options;
}
add_filter( 'mtbxr_select_options', 'mytheme_filter_select_options', 10, 2 );

if($field['uid']=='countries'){

return $options;

function mytheme_filter_radio_options($options, $field){
    if($field['uid']=='radio_sample'){
        $options = array(
            array(
                'value'=> 'opt1',
                'text'=> 'Option 1'
            ),
            array(
                'value'=> 'opt2',
                'text'=> 'Option 2'
            ),
            array(
                'value'=> 'opt3',
                'text'=> 'Option 3'
            )
        );
    }
    return $options;
}
add_filter( 'mtbxr_radio_options', 'mytheme_filter_radio_options', 10, 2 );

if($field['uid']=='radio_sample'){

return $options;

function mytheme_filter_checkbox_group_options($options, $field){
    if($field['uid']=='checkbox_group_sample'){
        $options = array(
            array(
                'value'=> '1',
                'text'=> 'Checkbox 1'
            ),
            array(
                'value'=> '2',
                'text'=> 'Checkbox 2'
            ),
            array(
                'value'=> '3',
                'text'=> 'Checkbox 3'
            )
        );
    }
    return $options;
}
add_filter( 'mtbxr_checkbox_group_options', 'mytheme_filter_checkbox_group_options', 10, 2 );

function mtbxr_field_notes( $note, $field ) {

    $note .= ' Meta Key: '.esc_attr($field['uid']);

    return $note;
}
add_filter( 'mtbxr_field_note', 'mtbxr_field_notes', 10, 2 );

function mytheme_field_notes( $note, $field ) {
    if($field['uid'] == 'checkbox_group_sample') {
        $note = 'Please specify the correct value...';
    }
    return $note;
}
add_filter( 'mtbxr_field_note', 'mytheme_field_notes', 10, 2 );

Utility Functions

Contain details about the utility functions. You can check the Accessing Your Data section for examples of using these functions.

mtbxr_val

mtbxr_val($key, $post_id=null)

Parameters:

string $key - Required. The uid of the field to fetch.

int $post_id - Optional. The Post ID to fetch the custom field from.

Returns mixed

mtbxr_all

mtbxr_all($post_id=null)

Parameters:

int $post_id - Optional. The Post ID to fetch the custom field from.

Returns array

mtbxr_debug

mtbxr_debug($s)

Parameters:

mixed $s - Required. Any variable to print out in a readable way.

Returns string

mtbxr_video

mtbxr_video( $key, $index=0, $width=null, $height=null, $post_id=null )

Parameters:

string $key - Required. The uid of the field to fetch.

int $index - Optional. The index of the video.

int $width - Optional. The width of the embedded video.

int $height - Optional. The height of the embedded video.

int $post_id - Optional. The Post ID to fetch the custom field from.

Returns string

mtbxr_videos

mtbxr_videos( $key, $width=null, $height=null, $post_id=null )

Parameters:

int $index - Optional. The index of the video.

int $width - Optional. The width of the embedded video.

int $height - Optional. The height of the embedded video.

int $post_id - Optional. The Post ID to fetch the custom field from.

Returns array