Using Meta Boxes on Plugin Admin Pages
Meta Boxes are boxes that appear on the dashboard and for custom features on edit page/post pages. They can also be used in plugins too. Here’s how to create meta boxes on an admin page that will remember whether you have opened/closed them and the order you have dragged them into.
They are relatively easy to create!
1) Enqueue the scripts that will allow toggling open and closed and the order to be changed. They need to be hooked in at the ‘init’ stage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
add_action('init',apmbt_init'); function apmbt_init() { /** * * Initialises js scripts and css * * @author Andy Moyle * @param null * @return * @version 0.1 * */ wp_enqueue_script('common'); wp_enqueue_script('wp-lists'); wp_enqueue_script('postbox'); } |
2) Create the page the boxes will appear on
1 2 3 4 5 6 7 8 |
<div class="wrap"><!-- wraps the page and allows styling to occur--> <div id="poststuff"> <!-- #post-body .metabox-holder goes here --> <div id="post-body" class="metabox-holder columns-2"> <!-- page content here --> </div><!--post-body--> </div><!--poststuff--> </div><!-- wrap--> |
Those classes and ids allow the meta box styling to happen
3) Create functions for each meta_box’s content
4) The meta boxes need nonce fields to allow any open/close toggling and order changes to be saved
1 2 3 4 |
<form method="get" action=""> <?php wp_nonce_field('closedpostboxes', 'closedpostboxesnonce', false ); ?> <?php wp_nonce_field('meta-box-order', 'meta-box-order-nonce', false ); ?> </form> |
5) The meta boxes are then “added” and “done”
1 2 3 4 5 6 7 |
add_meta_box( $id, $title, $callback, $post_type); //have as many of these as you want //$id is a unique id for the meta box //$title is the title //$callback is the function with the content //$post_type for our implemntation is the name of the plugin //There are other optional arguments which we aren't using |
add_meta_box prepares the meta box and can be placed in your content stream or as in an add_action hook
do_meta_boxes tells wordpress to render the meta box
1 2 3 4 |
do_meta_boxes( $page, $context, $object ); //$page is our plugin name //$context is advanced //$object is NULL |
6) Lastly we need some jquery to initialise previously saved open/close toggles and order
1 2 3 4 5 6 |
<script type="text/javascript"> jQuery(document).ready(function($){$(".if-js-closed").removeClass("if-js-closed").addClass("closed"); postboxes.add_postbox_toggles( 'pluginame'); }); </script> |
pluginname is your plugin name that you have used above. Other tutorials used pagenow but it didn’t work for me on custom admin pages in v3.5
Here’s the code bundled up…
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 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 |
<?php /* Plugin Name: admin_page_meta_box_tutorial Plugin URI: http://www.themoyles.co.uk/web-development/meta-box-tutorial Description: Example plugin to use meta boxes on a plugin page Version: 0.1 Author: Andy Moyle Author URI:http://www.themoyles.co.uk */ //avoid direct calls to this file where wp core files not present if (!function_exists ('add_action')) { header('Status: 403 Forbidden'); header('HTTP/1.1 403 Forbidden'); exit(); } add_action('init','apmbt_init');//initialise required javascripts add_action('admin_menu','apmbt_admin_menu');//adds menu link function apmbt_init() { /** * * Initialises js scripts and css * * @author Andy Moyle * @param null * @return * @version 0.1 * */ wp_enqueue_script('common'); wp_enqueue_script('wp-lists'); wp_enqueue_script('postbox'); } function apmbt_admin_menu() { /** * * Creates Admin Menu link * * @author Andy Moyle * @param null * @return * @version 0.1 * */ add_menu_page('Meta Box Demo', 'Meta Box Demo', 'administrator', 'apmbt/index', 'apmbt_admin_page'); } function apmbt_admin_page() { ?> <div class="wrap" id="church-admin"> <div id="icon-index" class="icon32"><br/></div><h2>Meta Box Tutorial Plugin</h2> <div id="poststuff"> <!-- #post-body .metabox-holder goes here --> <div id="post-body" class="metabox-holder columns-2"> <!-- meta box containers here --> <form method="get" action=""> <?php wp_nonce_field('closedpostboxes', 'closedpostboxesnonce', false ); ?> <?php wp_nonce_field('meta-box-order', 'meta-box-order-nonce', false ); ?> <?php add_meta_box("id-for-meta-box1", "Title of meta box1", "ampbt_meta_box1", "apmbt");?> <?php add_meta_box("id-for-meta-box2", "Title of meta box2", "ampbt_meta_box2", "apmbt");?> <?php do_meta_boxes('apmbt','advanced',null);?> </form> </div> </div> </div> <script type="text/javascript"> jQuery(document).ready(function($){$(".if-js-closed").removeClass("if-js-closed").addClass("closed"); postboxes.add_postbox_toggles( 'apmbt'); }); </script> <?php } function ampbt_meta_box1() { /** * * Content for meta box 1 * * @author Andy Moyle * @param null * @return * @version 0.1 * */ ?> <p>You can put anything in here, change the order and even close it Wordpress will remember!</p> <?php } function ampbt_meta_box2() { /** * * Content for meta box 1 * * @author Andy Moyle * @param null * @return * @version 0.1 * */ ?> <p>You can put anything in here too</p> <?php } ?> |
Very nicely done.
Thank you for the effort, it is much appreciated.
hi
you saved my tons of hour.
i m searching for 2 days.
thank you so much
I don’t understand why we need this code (on line 73):
$(“.if-js-closed”).removeClass(“if-js-closed”).addClass(“closed”)
It doesn’t seem to make a difference on the behavior of the page. Without it, metaboxes are still rendered in their previously open/closed state. Can you explain the downside to omitting this snippet of code?
If I remember rightly it’s to do with if you have set the box closed in screen options.
Thanks for this, a real time-saver. I made one change so scripts load only on specific settings page (replacing the ‘init’ add_action and its callback):