The Set-Up

This tutorial covers a couple semi-advanced topics. I will, therefore, assume you have a firm grasp of PHP, JavaScript, CSS, and WordPress actions. Because of this, I will not going in depth at every step but have made an attempt to reference blog posts and codex articles that may be of help. Despite this lack of depth, you should be able to copy and paste the code and adapt to your own use without much trouble.

One of the best ways to cut down on development time in your projects is to create reusable code. In order to achieve this goal, we will keep all of our PHP, CSS, and JavaScript code in separate files to be easily ported from project to project. I generally keep code of this nature in a /library sub-directory underneath my theme folders.

We will begin by defining our custom post type. In this example, will be creating and working with a Video custom post type. There are numerous other tutorials on the net explaining this process, so I will not cover it in depth. I recommend you read this post over at NetTuts to get started. The code that defines our custom post type is below.

/**
 * Register Video custom post type
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_videos_register() {
	$labels = array(
	    'name' => _x('Videos', 'post type general name'),
	    'singular_name' => _x('Video', 'post type singular name'),
	    'add_new' => _x('Add New', 'release'),
	    'add_new_item' => __('Add New Video'),
	    'edit_item' => __('Edit Video'),
	    'new_item' => __('New Video'),
	    'view_item' => __('View Video'),
	    'search_items' => __('Search Videos'),
	    'not_found' =>  __('No videos found'),
	    'not_found_in_trash' => __('No videos found in Trash'), 
	    'parent_item_colon' => ''
	  );
 
	$args = array(
    	'labels' => $labels,
    	'public' => true,
    	'show_ui' => true,
    	'capability_type' => 'post',
    	'hierarchical' => false,
    	'rewrite' => true,
    	'supports' => array('title', 'editor', 'comments'),
    	'menu_position' => 20,
    	'menu_icon' => get_bloginfo('template_url').'/images/menu-videos.png'
    );
	register_post_type( 'video' , $args );
}
add_action('init', 'soulsizzle_videos_register');

As stated above, it is best to keep this in a separate file, so it may be reused again later in other projects. I recomend you create a videos.php file in the library folder underneath your theme directory, and place this and any additional PHP code in it. Then, be sure to include it in your theme by referencing it in the functions.php file as so:

require_once('library/video.php');

Creating the Sort Menu

We will now create a Sort sub-menu item that will appear underneath the menu for our Video post type we defined above.

<?php
/**
 * Enable Sort menu
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_enable_video_sort() {
    add_submenu_page('edit.php?post_type=video', 'Sort Videos', 'Sort', 'edit_posts', basename(__FILE__), 'soulsizzle_sort_videos');
}
add_action('admin_menu' , 'soulsizzle_enable_video_sort'); 
 
 
/**
 * Display Sort admin
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_sort_videos() {
	$videos = new WP_Query('post_type=video&posts_per_page=-1&orderby=menu_order&order=ASC');
?>
	<div class="wrap">
	<h3>Sort Videos <img src="<?php bloginfo('url'); ?>/wp-admin/images/loading.gif" id="loading-animation" /></h3>
	<ul id="video-list">
	<?php while ( $videos->have_posts() ) : $videos->the_post(); ?>
		<li id="<?php the_id(); ?>"><?php the_title(); ?></li>			
	<?php endwhile; ?>
	</div><!-- End div#wrap //-->
 
<?php
}

The first function simply adds a submenu underneath the Video menu using WordPress’s add_submenu_page(). It is then enabled using add_action().

The second function is what we told WordPress to call for the sub-menu we defined above. It begins by getting a list of all the posts with type video. By setting posts_per_page to -1, we are telling WordPress to return all of them.

We then create a unordered list with an ID of video-list. Finally, we loop through all the videos and output them as list items. The important thing to note here is that we are setting the ID of the list item to the ID of the post. This will be important later.

Additionally, we placed a reference to loading.gif in the page’s header. This file is included with WordPress and will be used to let users know when they are waiting on AJAX actions to complete.

Styling the List

If you click on the Sort menu item now, it should list all our videos. However, it doesn’t exactly look pretty. Let’s work on that. Begin by telling WordPress to queue up our CSS file, which we will create in a moment, by adding the following to our videos.php.

/**
 * Queue up administration CSS
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_videos_print_styles() {
	global $pagenow;
 
	$pages = array('edit.php');
	if (in_array($pagenow, $pages))
		wp_enqueue_style('soulsizzle_videos', get_bloginfo('template_url').'/library/videos.css');
}
add_action( 'admin_print_styles', 'soulsizzle_videos_print_styles' );

The appearence of our list is going to be somewhat of a personal preference. However, by putting the following in a video.css file in the /library directory, you will have something that is simple but meshes well with the WordPress UI.

#video-list { margin-top: 20px; }
 
	#video-list li {
		padding: 10px;	
		width: 50%;	
		font-weight: bold;
 
		background: #f0f0f0; /* for non-css3 browsers */
		filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#f7f7f7', endColorstr='#e7e7e7'); /* for IE */
		background: -webkit-gradient(linear, left top, left bottom, from(#f7f7f7), to(#e7e7e7)); /* for webkit browsers */
		background: -moz-linear-gradient(top,  #f7f7f7,  #e7e7e7); /* for firefox 3.6+ */
		cursor: move;
 
		border: 1px solid #ddd;
		border-raidus: 10px;
		-moz-border-radius: 10px;
		-webkit-border-radius: 10px;
	}
 
#loading-animation { display: none; }

The JavaScript

Thanks to the power of jQuery, which is automatically included in a WordPress install, we can do powerful DOM manipulation and AJAX with very little code. We will be using jQuery to allow our list items to be sorted by drag-and-drop and automatically updating the menu order of our posts each time the order of the list is changed. Let’s begin by enabling the necessary JavaScript files. We will need to enable jQuery UI’s Sortable plugin to handle the drag-and-drop functionality. Additionally, we will need to create and enable our own JavaScript file to handle the AJAX and tell Sortable what to do. Place the following in your videos.php.

/**
 * Queue up administration JavaScript file
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_videos_print_scripts() {
	global $pagenow;
 
	$pages = array('edit.php');
	if (in_array($pagenow, $pages)) {
		wp_enqueue_script('jquery-ui-sortable');
		wp_enqueue_script('soulsizzle_videos', get_bloginfo('template_url').'/library/videos.js');
	}
}
add_action( 'admin_print_scripts', 'soulsizzle_videos_print_scripts' );

The above works just like enable our CSS did above. Place the following in video.js in the /library folder.

jQuery(document).ready(function($) {		
	var videoList = $('#video-list');
 
	videoList.sortable({
		update: function(event, ui) {
			$('#loading-animation').show(); // Show the animate loading gif while waiting
 
			opts = {
				url: ajaxurl, // ajaxurl is defined by WordPress and points to /wp-admin/admin-ajax.php
				type: 'POST',
				async: true,
				cache: false,
				dataType: 'json',
				data:{
					action: 'video_sort', // Tell WordPress how to handle this ajax request
					order: videoList.sortable('toArray').toString() // Passes ID's of list items in	1,3,2 format
				},
				success: function(response) {
					$('#loading-animation').hide(); // Hide the loading animation
					return; 
				},
				error: function(xhr,textStatus,e) {  // This can be expanded to provide more information
					alert('There was an error saving the updates');
					$('#loading-animation').hide(); // Hide the loading animation
					return; 
				}
			};
			$.ajax(opts);
		}
	});	
});

The code above tells jQuery UI’s Sortable plug-in that the unordered-list with the ID #video-list should be sortable. We also tell Sortable that everytime the user changes the order of the list items, it should preform the function assigned to the update option. Most of the function should be self-explanatory. If you have any questions, be sure to reference jQuery’s documentation on .ajax.

The first important thing to note is that we set the url option to ajaxurl. This is defined by WordPress and always points to /wp-admin/admin-ajax.php, which is somewhat of a traffic cop for AJAX requests. By making our request through this file, we will have access to all the functions and variable defined by WordPress when we handle the AJAX request below.

The data option contains the variables that we want to send our PHP AJAX handler. The first variable is action and tells admin-ajax.php how to handle the request. The second variable we are using is one we define ourselves. It is named order and contains a list of ID’s of our videos in the order they currently our in our list. Calling .sortable('toArray') will create an array of these ID’s and .toString() will put it in a format that is easy to pass through AJAX.

Handling the AJAX Request

We must now create our custom PHP AJAX handler. When using custom handlers, admin-ajax.php will execute an action in the form of wp_ajax_[action] where [action] is the name of the action value we pass in our JavaScript. From that point, it’s just a matter of assigning a function to that action. Add this last bit of PHP to our videos.php.

function soulsizzle_save_video_order() {
	global $wpdb; // WordPress database class
 
	$order = explode(',', $_POST['order']);
	$counter = 0;
 
	foreach ($order as $video_id) {
		$wpdb->update($wpdb->posts, array( 'menu_order' => $counter ), array( 'ID' => $video_id) );
		$counter++;
	}
	die(1);
}
add_action('wp_ajax_video_sort', 'soulsizzle_save_video_order');

If you notice, any variables we sent in our JavaScript as data now exists in the $_POST variable. The above code takes the order value and splits it into an array. In then iterates over each ID, and updates the menu_order column of the posts database table with an increasing value.

After rearranging your list of videos, you should be able to the Videos menu and see these changes reflected.

Wrap-up

In only a short amount of code, we were able to create a custom Video post type that is both reusable and goes beyond the basics to make it sortable. Not only do we make it easier on our clients but also on ourselves. We covered a lot of information very quickly, so if you have any questions, feel free to ask in the comments section below. For simplicity’s sake, I’ve included the full contents of our videos.php file below.

<?php
 
/**
 * Register Video custom post type
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_videos_register() {
	$labels = array(
	    'name' => _x('Videos', 'post type general name'),
	    'singular_name' => _x('Video', 'post type singular name'),
	    'add_new' => _x('Add New', 'release'),
	    'add_new_item' => __('Add New Video'),
	    'edit_item' => __('Edit Video'),
	    'new_item' => __('New Video'),
	    'view_item' => __('View Video'),
	    'search_items' => __('Search Videos'),
	    'not_found' =>  __('No videos found'),
	    'not_found_in_trash' => __('No videos found in Trash'), 
	    'parent_item_colon' => ''
	  );
 
	$args = array(
    	'labels' => $labels,
    	'public' => true,
    	'show_ui' => true,
    	'capability_type' => 'post',
    	'hierarchical' => false,
    	'rewrite' => true,
    	'supports' => array('title', 'editor', 'comments'),
    	'menu_position' => 20,
    	'menu_icon' => get_bloginfo('template_url').'/images/menu-videos.png'
    );
	register_post_type( 'video' , $args );
}
add_action('init', 'soulsizzle_videos_register');
 
 
/**
 * Enable Sort menu
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_enable_video_sort() {
    add_submenu_page('edit.php?post_type=video', 'Sort Videos', 'Sort', 'edit_posts', basename(__FILE__), 'soulsizzle_sort_videos');
}
add_action('admin_menu' , 'soulsizzle_enable_video_sort'); 
 
 
/**
 * Display Sort admin
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_sort_videos() {
	$videos = new WP_Query('post_type=video&posts_per_page=-1&orderby=menu_order&order=ASC');
?>
	<div class="wrap">
	<h3>Sort Videos <img src="<?php bloginfo('url'); ?>/wp-admin/images/loading.gif" id="loading-animation" /></h3>
	<ul id="video-list">
	<?php while ( $videos->have_posts() ) : $videos->the_post(); ?>
		<li id="<?php the_id(); ?>"><?php the_title(); ?></li>			
	<?php endwhile; ?>
	</div><!-- End div#wrap //-->
 
<?php
}
 
 
/**
 * Queue up administration JavaScript file
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_videos_print_scripts() {
	global $pagenow;
 
	$pages = array('edit.php');
	if (in_array($pagenow, $pages)) {
		wp_enqueue_script('jquery-ui-sortable');
		wp_enqueue_script('soulsizzle_videos', get_bloginfo('template_url').'/library/videos.js');
	}
}
add_action( 'admin_print_scripts', 'soulsizzle_videos_print_scripts' );
 
 
/**
 * Queue up administration CSS
 *
 * @return void
 * @author Soul
 **/
function soulsizzle_videos_print_styles() {
	global $pagenow;
 
	$pages = array('edit.php');
	if (in_array($pagenow, $pages))
		wp_enqueue_style('soulsizzle_videos', get_bloginfo('template_url').'/library/videos.css');
}
add_action( 'admin_print_styles', 'soulsizzle_videos_print_styles' );
 
 
function soulsizzle_save_video_order() {
	global $wpdb; // WordPress database class
 
	$order = explode(',', $_POST['order']);
	$counter = 0;
 
	foreach ($order as $video_id) {
		$wpdb->update($wpdb->posts, array( 'menu_order' => $counter ), array( 'ID' => $video_id) );
		$counter++;
	}
	die(1);
}
add_action('wp_ajax_video_sort', 'soulsizzle_save_video_order');

Where This May Come In Handy

Especially with version 3.0′s new CMS features, WordPress is easily used to manage content beyond the traditional posts and pages. For example, I personally do a lot of work with musicians. While the Thumb, Medium, and Large image sizes may work well in the context of their blog, these may not apply to other types of content. Album covers may be one size and show fliers may be another. Additionally, I may want to make available larger promo photos while still avoiding the 8 megapixel originals that the client may upload. Hence, we need to define a few additional image resolutions for WordPress to generate when uploading new pictures.

Defining The New Image Sizes

WordPress includes a simple function for achieving this goal, add_image_size(). It requires 4 parameters to do its job: the size’s name, width, height, and whether to crop it. As a personal preference, I place these size definitions (along with any other theme setup) in a function that is hooked onto the after_setup_theme action hook. Below is an example that defines two additional sizes. The first would be used in a front page featured news rotator, and the second is a larger size that is served if visitors want to download an image. This, and any additional code shown, goes in your theme’s functions.php file.

function mytheme_setup() {
	add_image_size('featured-thumbnail',640,320, true);
	add_image_size('x-large',800,800, false);
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Rather simple, eh? Now when a new image is uploaded into WordPress, a cropped 640×320 version and one that fits within 800×800 dimensions will be created.

Using The Sizes in Your Theme

These sizes will not be accessible to the client for insertion into posts and pages. Their strength lies in how they are implemented into your themes. For example, for a recent project I created a front page news rotator that was independent of the blog posts. Therefore, the Thumbnail size was not applicable. So I registered a ‘featured-thumbnail’ size similar to above and created a custom post type for managing the news items. Each news item was given a Featured Image in WordPress’s dashboard.

Then it’s just a matter of using WordPress’s the_post_thumbnail() function to insert the image in our defined dimensions. Generally, the only parameter you need to pass is the name of our newly defined image size. The resulting code is as follows:

<ul>
	<?php
	$featured = new WP_Query("post_type=featured&post_status=publish");
	while ( $featured->have_posts() ) : $featured->the_post();
	?>
	<li>
		<?php the_post_thumbnail('featured-thumbnail'); // Inserts image with our defined dimensions ?> 
		<div class="newsDescription">
			<h3><?php the_title(); ?></h3>
			<p><?php the_content(); ?></p>
		</div>
	</li>
	<?php endwhile; ?>
</ul>

Conclusion

The team of developers behind WordPress are well aware of its evolution from a simple blogging platform to a strong content management system. With the release of version 3.0, managing a wide range of content types has never been easier. Each content type will have its own requirements for display, and being able to define additional image sizes is just one of many tools for meeting those requirements.

Fleshing Out The Solution

Before writing any code, I like to flesh out the basics to my solution on paper. Some simple brainstorming lead me to the following goals:

1. Create an array of all the widget areas available
2. Hide all the listed widget areas besides the first
3. Insert into the Widget page a drop-down box containing a list of the widget areas in our array
4. Whenever a user selects a widget area from the drop-down box, show that one and hide the  rest

Loading Our Javascript File

We’ll begin by creating a file named widget-admin.js. Save this file somewhere in your theme directory. I prefer to keep all my JavaScript files in the js/ sub-directory. We only want this code to be loaded if we are on the Widgets page of the WordPress dashboard. To achieve this, add the following code to your functions.php file.

// Custom Admin Sidebar Switcher
function sidebar_switcher() {
	global $pagenow;
 
	if ($pagenow == 'widgets.php')
		wp_enqueue_script('fca_admin', get_bloginfo('template_url').'/js/widget-admin.js');
}
add_action('admin_print_scripts', 'sidebar_switcher');

By latching onto WordPress’s admin_print_scripts hook, our sidebar_switcher() function will only be run when we are in the dashboard. The sidebar_switcher() function checks if we are on the Widgets page. If we are, it tells WordPress to queue up our widget-admin.js file.

Letting jQuery Work It’s Magic

The following code goes into the widget-admin.js that we created earlier. The comments should make it self-explanatory.

jQuery("document").ready(function(){
	var sidebars = new Array(); // Create array to hold our list of widget areas
	var selectorHTML, name; // Declaring variables isn't necessary in JavaScript, but it's good practice
 
	jQuery('.widget-liquid-right .sidebar-name h3').each(function(index) {
		name = jQuery(this).html(); // Get the name of each widget area
		name = name.replace(/\s*<span>.*<\/span>/,''); // Remove extra <span> block from name
		sidebars.push(name); // Add the name to our array
	});
 
	jQuery('.widget-liquid-right .widgets-holder-wrap').hide(); // Hide all the widget areas in list
	jQuery('.widget-liquid-right .widgets-holder-wrap:first').show(); // Show the first
 
	// Start <select> block. Position to the right of the "Widgets" heading.
	selectorHTML = "<select id=\"sidebarSelector\" style=\"position: absolute; left: 400px; top: 68px;\">\n";
 
	var count = 0;
	for ( var i in sidebars ) // Add option for each widgetized area
		selectorHTML = selectorHTML + "<option value=\"" + count++ + "\">" + sidebars[i] + "</option>\n"; // Store the index of the widget area in the 'value' attribute
 
	selectorHTML = selectorHTML + "</select>"; // Close the <select> block
 
	jQuery('div.wrap').append(selectorHTML); // Insert it into the DOM
 
	jQuery('#sidebarSelector').change(function(){ // When the user selects something from the select box...
		index = jQuery(this).val(); // Figure out which one they chose
		jQuery('.widget-liquid-right .widgets-holder-wrap').hide(); // Hide all the widget areas
		jQuery('.widget-liquid-right .widgets-holder-wrap:eq(' + index + ')').show(); // And show only the corresponding one
	});
});

Conclusion

When pushing WordPress to it’s limit, it may occasionally be necessary to enhance its user interface. With the power of jQuery and WordPress’s action and filter hooks, the sky is the limit.

I have made some changes to the original code that appeared in this article. The new solution is nearly identical to Keith’s below. Though I did arrive at this solution independently, he does deserve some acknowledgment for beating me to the punch.

The Goal

The basic goal of a site search is to find information quickly; however, it is becoming more and more commonplace to see increasingly stylized post listings. In my eyes, this runs the risk of becoming counter-intuitive to this goal. Because of this, it is my personal preference to simplify my search results and to show more results. Because searches rely on the same setting (found in Settings » Reading » Blog pages show at most) as any other WordPress page when determining the number of listings to show, we have to get a little creative in order to show a different am amount.

How Not to Do It

Most blog posts or WordPress.org forum posts will recommend using the query_posts() function in order to alter the number of search listings shown. They advise inserting something similar before the loop in your themes search.php.

However, this neglects one important fact. WordPress already runs the query once before it even gets to this query_posts() call. This means that you are essentially doubling the number of database calls WordPress needs to do in order to retrieve the correct number of posts. If an efficient, quickly-loading site is important to you (I know it is to me), this should be a concern. This is even more important with the recent news that Google is now incorporating page-load time into its pagerank algorithm.

A Better Solution

The obvious solution is to alter the original query before it is executed. This is made fairly simple with WordPress filters (noticing a common theme in our WordPress-related posts?). Using the pre_get_posts filter, we can change the query parameters before it is translated into an actual MySQL query. Simply insert the following code into the functions.php file of your theme. It’s so simple, I hope this technique will become more commonplace.

function change_wp_search_size($query) {
	if ( $query->is_search ) // Make sure it is a search page
		$query->query_vars['posts_per_page'] = 10; // Change 10 to the number of posts you would like to show
 
	return $query; // Return our modified query variables
}
add_filter('pre_get_posts', 'change_wp_search_size'); // Hook our custom function onto the request filter

Any function that is hooked into the pre_get_posts filter will automatically be passed an WP_Query Object containing any parameters that intends to use to generate the database query. All we have to do is change the posts_per_page parameter to the number of results we would like to show.

We must first determine if we are even on the search results page. This is as easy as testing to see if $query->is_search is set. Then, it’s simply a matter of returning our modified query paramaters to WordPress and letting WordPress do it’s magic.

A few additional notes

If you don’t want to limit the number of posts shown at all, simply set $query->query_varts['posts_per_page'] to -1. Also, this technique is not limited to the search page only. You can also test for $query->is_cateogry, $query->is_tag, $query->is_archive, $query->is_date, and etc. And if you want to test for a specific category you can use a conditional statement similar to the following:

if ($query->query_vars['cateogry_name'] == 'category_slug')

The Wrap-up

Though this solution may contain a few more lines of code than a query_posts() solution, it is still superior for two reasons.

1. It is quicker by nearly halving the number of database calls
2. We separate logic and presentation as much as possible, which should be a ever-present goal in web programming and design