Custom Admin Menu UI Example: Slideshow

Kamil Grzegorczyk has two fantastic technical write-ups on customizing the Pods user interface in the WordPress admin (the first one has been an invaluable reference for me, personally):

1. Using Pods UI to build custom admin interfaces
2. Building Pods Framework UI Plugin – Basic Setup

I thought a practical "Hello World" example would be helpful to bridge the gap a little. I'll use a Pod named "slides" for this example. It could be used to implement the ever popular slide-show using Pods to manage the data and a little extra polish on the back-end (custom columns and drag/drop reordering). You can copy the package data from here to import the "slides" Pod for the example.

A basic understanding of how the WordPress admin menu system works will help a lot when you get to customizing everything exactly how you want it. You can place the code from this example in your theme's functions.php for testing and experimenting.

Never modify the WordPress core themes or other theme's files directly or you will lose your changes the next time you update the theme. Create [a child theme] (http://codex.wordpress.org/Child_Themes) with its own functions.php file instead.

Implementing your UI customizations in a plugin is arguably a better solution, but this is intended as a quick and simple guide to getting started.

The End Result:

• Pictures from Brenton Little : http://instagram.com/brenton_clarke

---

First, define your custom menu via WordPress.

• Check the codex for add_menu_page() for the appropriate parameters to pass to it for your situation.
• Note: Place all the code from this tutorial in your child theme's functions.php file.

<?php
if (function_exists('pods')) add_action('admin_menu', 'my_custom_menu');
function my_custom_menu() {
	add_menu_page('Slides', 'Slides', 'manage_options', 'slides_menu_slug', 'admin_slides', '', 40);
}
?>

Next, create your menu function.

• The menu system will call the function named in the fifth parameter to add_menu_page(), so create that function (in this case: admin_slides) to configure everything how we want it and call pods_ui():

<?php
function admin_slides() {

	// 'slides' is the Pod name
	$object = pods('slides');

	// We've created a simple number field in the Pod for drag/drop reordering
	// but it is managed automatically.  No need to include it in the list of
	// fields on the "add new" and "edit" pages.  The unset() will remove
	// 'sort_order' from the list of fields Pods gives us.     
	$fields = $object->fields();
	unset($fields['sort_order']); 
	
	// Set the ui parameters to tell Pods how we want to do things
	$object->ui = array(
		'item'    => 'Slide',
		'items'   => 'Slides',
		'orderby' => 'sort_order ASC',
		'fields' => array(
			// This is the field list shown when listing all items
			'manage' => array(
				'name'        => 'Name',
				'slide_image' => 'Slide Image', // An image in the UI is a nice touch
				'slide_text'  => 'Slide Text',
				'link_url'    => 'Link URL',
				'new_window'  => 'Open Link in New Window?'
			),
			// Add and Edit UI will show all fields except for the one we removed
			'add'  => $fields,
			'edit' => $fields
		),
		// Enable drag-drop re-ordering.  'sort_order' is a simple
		// number field added to the Pod to keep track of the order
		'reorder' => array(
			'on'      => 'sort_order',
			'orderby' => 'sort_order ASC'
		)
	);
	
	pods_ui($object);
}
?>

Pods by default creates a menu for the slideshow Pod.

• This menu no longer necessary now that you've created your own.
• To disable the menu Pods creates:

• Pods Admin -> Setup
• Edit the "slides" Pod
• Click the "Advanced Options" bar below the field list to expand it
• Go to the "Pod Options" tab
• Uncheck "Show Admin Menu in Dashboard"

You'll notice now that after disabling the unnecessary slideshow Menu, Pods will create its own menu item.

• You can remove this by adding the below code (via the Pods 2.0 Wiki Page):

  add_filter( 'pods_admin_menu_secondary_content', '__return_false' );