Sunday, June 26, 2011

Tutorial: Creating Custom Write Panels in WordPress

Thanks to webfunction

Use Custom Write options to easily add any unique data to your post
Function | Create a Custom Write Panel in WordPress Tutorial
Everyone knows that WordPress is one of the most, if not the most, popular blogging systems on the internet today. With its out of the box features, plugins, and great theming community, its no wonder WordPress has been accepted as today’s standard. However, sometimes you just want to add a little more.

It seems the latest fad to hit the WordPress scene is adding thumbnails into a blog post. This is fairly easy to do with some knowledge of custom fields, but can be a little complicated if your client is new to WordPress, or blogging.
Luckily, WordPress has a solution for us. We are going to use a little something called add_meta_box.
Note: This tutorial requires both knowledge of WordPress, as well as PHP.
I shared a link in a comment that WordPress has a little tutorial for this on their site. However, it is a little incomplete, and leaves a little to be desired. So, let’s get started making our own!

Examples of Usage

To see how you can use custom write panels take a look at these couple of examples, or click the image below.
Custom Write Panel Examples - Turorials

functions.php

Please excuse the indention of the code. The WordPress plugin does not like my tabs. :(
All of the code we are about to add will be put in functions.php. This file is included automatically in the Theme, so anything we put in here can be used throughout the theme.
To make this expandable for the future, we are going to declare all of our information in an array. This way, we can add some information to the array, and it will be automatically added to our Admin Panel.

Information Array

1
2
3
4
5
6
7
8
9
10
11
12
13
/*
Plugin Name: Custom Write Panel
Plugin URI: http://wefunction.com/2008/10/tutorial-create-custom-write-panels-in-wordpress
Description: Allows custom fields to be added to the WordPress Post Page
Version: 1.0
Author: Spencer
Author URI: http://wefunction.com
/* ----------------------------------------------*/
 
$new_meta_boxes =
array(
 
);
Inside of that array, we are going to add more arrays which will hold the information of the new meta box.
1
2
3
4
5
6
7
8
$new_meta_boxes =
array(
"image" => array(
"name" => "image",
"std" => "",
"title" => "Image",
"description" => "Using the \"Add an Image\" button, upload an image and paste the URL here.")
);
The array is pretty self explanatory. The first value is the name of field, after that would be a standard value (in this case, it is blank, but this would be useful to store default information), and then the Title of the meta_box, ending with the description.
There are 3 functions that will be the backbone here. Let’s go ahead and declare those now:
1
2
3
4
5
6
7
8
9
10
11
function new_meta_boxes() {
 
}
 
function create_meta_box() {
 
}
 
function save_postdata( $post_id ) {
 
}

Creating the Fields

Lets work on function new_meta_boxes().
This is the function where we are going to build the actual HTML inputs. We first need declare a few variables as global. We will then be able to access them inside the function. We need to be able to access the $post variable, as well as $new_meta_boxes (our array.)
1
2
3
function new_meta_boxes() {
global $post, $new_meta_boxes;
}
Because all of our information is in an array, we need to loop through it all, and create an input box for each one:
1
2
3
4
5
6
function new_meta_boxes() {
global $post, $new_meta_boxes;
 
foreach($new_meta_boxes as $meta_box) {
 
}
Next we need to figure out a default value for the inputs. We can do this by checking the get_post_meta WordPress function.
1
2
3
4
5
6
7
8
9
function new_meta_boxes() {
global $post, $new_meta_boxes;
 
foreach($new_meta_boxes as $meta_box) {
$meta_box_value = get_post_meta($post->ID, $meta_box['name'].'_value', true);
 
if($meta_box_value == "")
$meta_box_value = $meta_box['std'];
}
This is some pretty simple PHP. We define $meta_box_value, and set it equal to get_post_meta. Next, we check to see if our variable == "" (equals nothing) meaning no data has been previously entered. If nothing has been entered, we set the $meta_box_value equal to the std value we defined in the array
Time to start building the inputs. First off, we are going to create a hidden field that we will use to verify the data later on.
1
echo'.$meta_box['name'].'_noncename" id="'.$meta_box['name'].'_noncename" value="'.wp_create_nonce( plugin_basename(__FILE__) ).'" />';
Now we can echo the title of our Custom Input:
1
echo'

'.$meta_box['title'].'

';
Next our actual input box. This gets the value of $meta_box_value we worked out earlier.
1
echo'.$meta_box['name'].'_value" value="'.$meta_box_value.'" size="55" />
';
Finally, just add our little description we defined in the array
1
echo'$meta_box['name'].'_value">'.$meta_box['description'].'
';
(All of that is still in our function new_meta_boxes() function.)

Make it Meta!

Our next function, function create_meta_box(), will actually create each of the meta boxes. We are going to be using WordPress’s add_meta_box
1
2
3
4
5
function create_meta_box() {
if ( function_exists('add_meta_box') ) {
add_meta_box( 'new-meta-boxes', 'Custom Post Settings', 'new_meta_boxes', 'post', 'normal', 'high' );
}
}
if ( function_exists('add_meta_box') ) { is important because this function did not exist in versions of WordPress before version 2.5. You need to on at least version 2.5 before this will work.
From WordPress.org, the function works like this:
1
'id', 'title', 'callback', 'page', 'context', 'priority'); ?>
callback is the most important. That is calling our function (new_meta_boxes). context decides whether or not this field should display on the “Write > Post” page, or the “Write > Page” page. You can read more about the parameters on the WordPress site

Saving the Data

Now here’s the important part, and the part where WordPress.org is pretty vague. This function will save our data.
1
2
3
4
5
6
7
function save_postdata( $post_id ) {
global $post, $new_meta_boxes;
 
foreach($new_meta_boxes as $meta_box) {
 
}
}
This is our function, and we’ve started off with including a few variables. Again, we need to include $post so we have the ID of the WordPress post. Also, we have to include the $new_meta_box array, as we will loop through it again.
This next bit (inside of the foreach loop), will verify that the data we are receiving is genuine.
1
2
3
4
5
6
7
8
9
10
11
12
// Verify
if ( !wp_verify_nonce( $_POST[$meta_box['name'].'_noncename'], plugin_basename(__FILE__) )) {
return $post_id;
}
 
if ( 'page' == $_POST['post_type'] ) {
if ( !current_user_can( 'edit_page', $post_id ))
return $post_id;
} else {
if ( !current_user_can( 'edit_post', $post_id ))
return $post_id;
}
No we are going to define a variable that will get the data out of our fields.
1
$data = $_POST[$meta_box['name'].'_value'];
It gets the $_POST data from our fields we created in the previous functions.
Now the last thing to do is to decide what to do with the new data. To keep WordPress from creating a new database entry each time, a few checks need to be made. First, we try and get any information with the same key and post id. If it returns empty, we know this custom field has not been added before. So, lets add it.
1
2
if(get_post_meta($post_id, $meta_box['name'].'_value') == "")
add_post_meta($post_id, $meta_box['name'].'_value', $data, true);
Next, we check to see if the new data in the field is different from any old data. If it is, we simply update the field.
1
2
elseif($data != get_post_meta($post_id, $meta_box['name'].'_value', true))
update_post_meta($post_id, $meta_box['name'].'_value', $data);
The last thing to do is delete one, if the field is left empty. This will keep our database free of any blank entries.
1
2
elseif($data == "")
delete_post_meta($post_id, $meta_box['name'].'_value', get_post_meta($post_id, $meta_box['name'].'_value', true));
Now, to actually make things work, we need to “hook” WordPress. We can do this by using add_action. This simply adds our functions to a specific area of WordPress. In our case, we need to hook the admin_menu, as well as when the post is saved, save_post.
1
2
add_action('admin_menu', 'create_meta_box');
add_action('save_post', 'save_postdata');

Our Final Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/*
Plugin Name: Custom Write Panel
Plugin URI: http://wefunction.com/2008/10/tutorial-create-custom-write-panels-in-wordpress
Description: Allows custom fields to be added to the WordPress Post Page
Version: 1.0
Author: Spencer
Author URI: http://wefunction.com
/* ----------------------------------------------*/
 
$new_meta_boxes =
array(
"image" => array(
"name" => "image",
"std" => "",
"title" => "Image",
"description" => "Using the \"Add an Image\" button, upload an image and paste the URL here.")
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
function new_meta_boxes() {
global $post, $new_meta_boxes;
 
foreach($new_meta_boxes as $meta_box) {
$meta_box_value = get_post_meta($post->ID, $meta_box['name'].'_value', true);
 
if($meta_box_value == "")
$meta_box_value = $meta_box['std'];
 
echo'.$meta_box['name'].'_noncename" id="'.$meta_box['name'].'_noncename" value="'.wp_create_nonce( plugin_basename(__FILE__) ).'" />';
 
echo'

'.$meta_box['title'].'

';
 
echo'.$meta_box['name'].'_value" value="'.$meta_box_value.'" size="55" />
';
 
echo'$meta_box['name'].'_value">'.$meta_box['description'].'
';
}
}
1
2
3
4
5
6
function create_meta_box() {
global $theme_name;
if ( function_exists('add_meta_box') ) {
add_meta_box( 'new-meta-boxes', 'Brazen Post Settings', 'new_meta_boxes', 'post', 'normal', 'high' );
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
function save_postdata( $post_id ) {
global $post, $new_meta_boxes;
 
foreach($new_meta_boxes as $meta_box) {
// Verify
if ( !wp_verify_nonce( $_POST[$meta_box['name'].'_noncename'], plugin_basename(__FILE__) )) {
return $post_id;
}
 
if ( 'page' == $_POST['post_type'] ) {
if ( !current_user_can( 'edit_page', $post_id ))
return $post_id;
} else {
if ( !current_user_can( 'edit_post', $post_id ))
return $post_id;
}
 
$data = $_POST[$meta_box['name'].'_value'];
 
if(get_post_meta($post_id, $meta_box['name'].'_value') == "")
add_post_meta($post_id, $meta_box['name'].'_value', $data, true);
elseif($data != get_post_meta($post_id, $meta_box['name'].'_value', true))
update_post_meta($post_id, $meta_box['name'].'_value', $data);
elseif($data == "")
delete_post_meta($post_id, $meta_box['name'].'_value', get_post_meta($post_id, $meta_box['name'].'_value', true));
}
}
1
2
add_action('admin_menu', 'create_meta_box');
add_action('save_post', 'save_postdata');

Implementation

Now I bet you are wondering “now how the heck do I get information?!” Well, it’s quite simple really. You do it the same way you would for a normal custom field. We’ve been using the function already in the tutorial, get_post_meta().
So, just open up one of your theme files where you want the custom data to appear. First, let’s check to see if there is anything entered for this post. Because if there isn’t, we shouldn’t show anything (in this case, it would result in a broken image.)
1
2
3
if(get_post_meta($post->ID, "image_value", $single = true) != "") :
?>
Now the actual image:
1
<img src="ID, "image_value", $single = true); ?>" alt="php the_title(); ?>" />
And to end our if statement:
1
2
3
endif;
?>
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)