It’s so hard to find good advanced WordPress materials nowadays. However, there are still authors and sites that continually publish solid quality articles on WordPress development. As a result, Follow Friday is a new category on WordPress Hardcore where I will share with you one WordPress site or author that you should follow on Twitter or subscribe to RSS. This week’s author is Ben Gillbanks from Binary Moon.

Ben Gillbanks is a WordPress ninja who’s behind Pro Theme Design and WPVote. He’s also the developer in charge of TimThumb, which is one of the most popular thumbnail generator script for WordPress themes. His blog – Binary Moon – which usually was dominated by movie reviews, recently is stocked with lots of hardcore WordPress tutorials and tricks of the trade along with great advices for WordPress developers. Follow him on Twitter and Subscribe to his updates via RSS if you haven’t done so already (which I doubt). Below is 5 of his articles that I hand picked for you to bookmark, seriously quality stuff:

Using the Yahoo Weather API (in your WordPress themes)

While you won’t be using this trick a lot, it still serves as an excellent example on how to use WordPress Http class to work with external API. You can extend this example to interact with other web services, like fetching recent tweets from twitter or loading a text file from a remote server.

10 WordPress query_posts tips you probably don’t know

Some of these tricks I don’t know myself. Reading WordPress’ official documentation on query_posts() is a must, but this article serves as an excellent supplement. I like how concise yet easy to understand his code examples are. By the way, If you’re turned on by really really hardcore stuff, play around with WP_Query object and filter hook parse_query.

Creating Your Own WordPress Permalink Structure For Custom Content

Like I said, stuff involving WP_Query and parse_query is pretty hardcore. I wanted to write something about this, but found out Ben covered it nicely with his article. My approach might be a little bit different, but you should really read Ben’s way, you’ll know how WPVote works behind the scene.

WordPress Caching, Part 1: The Basics

This article is basically an introduction to a series of articles about Caching and WordPress. Judging on the premise, I believe this will be a very informative and useful series. If I were you, I’d subscribe to his RSS in a blink to make sure I won’t miss anything in the future.

Building WPVote Part 7: Almost Done

As you all probably know, WPVote was launched recently and I believe it’s a huge success. Ben even documented each step of his project in a series of 7 blog posts, and I found some of these articles really gave me good ideas about how to plan, design and implement a WordPress project from start to finish.

Enjoy your Friday!

Since Roles and Capabilities are introduced in WordPress 2.0, the User Level approach has been declared deprecated. However, it’s disappointing that most plugins and themes out there still use user levels to control access to admin option pages and other functionalities. This guide shows you how to properly use Roles and Capabilities in your plugins and themes.

Disclaimer: This article is a long one, therefore you should probably bookmark it so that you can always come back later for reference.

Table of Contents

1. What are Roles and Capabilities?
2. Capabilities and administration menus
3. Checking a user’s capability
4. Adding custom user roles
5. Adding custom user capabilities
6. WordPress Capability Classes

What are Roles and Capabilities?

As in other CMS and web applications, WordPress has a built-in system to verify whether a particular user has enough privilege to take a certain action. Users are divided into Roles, and each Role is assigned certain capabilities (or permissions). Here is a summary of WordPress default roles:

Administrator – Somebody who has access to all the administration features

Editor – Somebody who can publish posts, manage posts as well as manage other people’s posts, etc.

Author – Somebody who can publish and manage their own posts

Contributor – Somebody who can write and manage their posts but not publish posts

Subscriber – Somebody who can read comments/comment/receive news letters, etc.

This system of Roles and Capabilities is much more flexible than User Level, since it enables you to add, remove or reassign capabilities among roles. You can even add more roles to the system without destroying the default setup.

Capabilities and administration menus

Almost every plugin needs to have at least one page in the admin area to let users customize how the plugin is used. In order to do this, you need to add your own administration menu items. There are a bunch of WordPress functions which let you do this:

// add top level menu
add_menu_page(page_title, menu_title, capability, handle, [function], [icon_url]);

// add sub-menu pages
add_submenu_page(parent, page_title, menu_title, capability, file/handle, [function]);

// add Options sub-menu
add_options_page(page_title, menu_title, capability, handle, [function]);

// add Management sub-menu
add_management_page(page_title, menu_title, capability, handle, [function]);

// add Pages sub-menu
add_pages_page( page_title, menu_title, capability, handle, [function]);

// add Posts sub-menu
add_posts_page( page_title, menu_title, capability, handle, [function]);

// add Appearances sub-menu
add_theme_page( page_title, menu_title, capability, handle, [function]);

As you can see, there’s always a required parameter called capability for each of those functions. This essentially means the user who logs in to the administration area needs to have a certain capability to see the menu item. You can either use a user level (which is deprecated and not recommended), or a string representing a certain capability (for example, edit_posts).

Many plugins still use user levels (numeric representation of a user’s privilege, from 0 to 10). However, this is deprecated and should not be used anymore. By using capabilities, you won’t have to worry when user levels are not supported by WordPress, and if you want to add and use your custom capabilities, this is the way to go.

If you use the functions above to add menu items to the admin area, only the users who have the specified capability can see the menu items and access the pages associated with those items. If your theme or plugin has an option page, it’s important that you restrict access to that page properly. For example, if it’s a theme option page, you should use edit_themes capability, while if it’s a plugin option, edit_plugins. Another way is to use manage_options for both plugin and theme option pages.

Remember, sometimes the blog administrator wants to share and divide responsibilities among several other users. As a result, using capabilities make your themes and plugins much more customizable.

Checking a user’s capability

If your plugin or theme involves the user making changes to the blog’s data (adding new or editing existing content etc.), it’s very important that you check whether the current user has enough capability to make a certain action. The current_user_can() function lets you do this:

if ( current_user_can( $capability ) ) {
    // do something if the current user has $capability
}

This function also accepts an optional argument for a certain post ID, in case you want to check whether the current user can do something to that post:

// check whether the current can edit a post with the ID $post_id
current_user_can( 'edit_post', $post_id );

There’s another function you can use to check whether the author of a certain post has a certain capability:

if ( author_can( $post, $capability ) ) {
    // do something if the author of the post $post has $capability
}

The first argument can be either a post object, or a post ID. Although this function is rarely used, it’s helpful to know it’s there. I personally never had to use that function, but if you have an interesting example, let me know in the comment!

Adding custom user roles

Sometimes it’s necessary for your plugin to add new roles to the system. Let’s say you’re coding a new gallery plugin where users can register to upload photos to your site, but that’s it – these registered users can’t add or modify any other type of content to your blog (such as posts or pages). The best way to do this, is to add a new custom role:

add_role( $role_name, $display_name, $capabilities );

// for example:

add_role( 'photo_uploader', 'Photo Uploader', array( 'organize_gallery' ) );

What this function does is add a new role to the system with a set of capabilities. The example aboves add a role called “photo_uploader”, with a display name and an array containing a list of default capabilities for that role (in this case, organize_gallery ).

When you process a request to create, edit or upload galleries, you should use current_user_can() to check whether the current user are permitted to take these actions.

if ( current_user_can( 'organize_gallery' ) ) {
    // do something
}

The users who are assigned this role can only organize_gallery, but cannot edit_posts or publish_posts.

To remove a role, you can use remove_role():

remove_role( 'photo_uploader' );

You should have an option somewhere for your plugin users to remove this custom role when they decide to uninstall your plugin.

But what if you want to add capabilities to existing users?

Adding custom user capabilities

This is useful when you develop a plugin that allows users to take actions other than manipulating post contents. Let’s come back to our gallery plugin example above. Say, if you also want to assign organize_gallery capability to existing roles (administrator, editor, author, contributor etc. ), what would you do?

// get the "author" role object
$role = get_role( 'author' );

// add "organize_gallery" to this role object
$role->add_cap( 'organize_gallery' );

WordPress Capability Classes

We’ve covered checking and adding capabilities, as well as adding roles. These are the most frequent used functions for managing user permissions in WordPress. However, as the title of this post contains the word “ultimate”, I’d like to also cover the three WordPress classes that work behind the scene and the API these classes provide, which you can use for advanced permission management in your plugin. These three classes are:

• WP_Roles
• WP_Role
• WP_User

The source code of these three classes can be found in wp-includes/capabilities.php. The source code is documented in great details and I’m sure you can understand it easily, but I’d like to sum up what you can do with these classes.

The WP_Roles Class

This class, as its name suggests, is for managing roles in general. When you use it in your plugin, you actually don’t have to initiate a new object, but use a global object which has been created by WordPress:

global $wp_roles;

The $wp_roles is available as a global object, and can be used anywhere in your functions, as long as it’s declared beforehand in your functions with the global keyword.

As covered before, you can add and remove roles using add_role() and remove_role(). These functions are actually wrappers for $wp_roles->add_role(), and $wp_roles->remove_role. Therefore you can add and remove roles using the $wp_roles object as well:

global $wp_roles;

// add a new role, same arguments as add_role()
$wp_roles->add_role( $role, $display_name, $capabilities )

// remove a role, same arguments as remove_role()
$wp_roles->remove_role( $role );

Likewise, you can also get a role using this method:

global $wp_roles;

// get a role based on role name, does the same thing as get_role()
$wp_roles->get_role( $role );

You can also get a list of available roles, containing pair of role names and role display names. This is useful when you want to provide an interface for the user to change capability assignment.

global $wp_roles;

// get a list of values, containing pairs of: $role_name => $display_name
$roles = $wp_roles->get_names();

Finally, you can add and remove capabilities using $wp_roles too, making this object versatile for almost all roles and capabilities operations.

global $wp_roles;

// add capability $cap to role $role
$wp_roles->add_cap( $role, $cap );

// remove capability $cap from role $role
$wp_roles->remove_cap( $role, $cap );

// for example
$wp_roles->add_cap( 'administrator', 'manage_galleries' );
$wp_roles->remove_cap( 'subscriber', 'view_galleries' );

WP_Role Class

This is a very simple class. All it does is adding and removing capabilities.

// get the the role object
$role_object = get_role( $role_name );

// add $cap capability to this role object
$role_object->add_cap( $capability_name );

// remove $cap capability from this role object
$role_object->remove_cap( $capability_name );

WP_User class

This class lets you manage roles and capabilities per user, which means you can assign multiple roles to a particular user, or add a capability to a certain user regardless of his current role.

First of all, you need to get the user object before manipulating its roles and capabilities:

// get user by user ID
$user = new WP_User( $id );

// or get user by username
$user = new WP_User( null, $name );

As you can see, you can get a user object based on either his user ID or username. With the latter, the first parameter must be empty (either null or an empty string). Examples:

// get the administrator by ID
$admin = new WP_User( 1 );

// get the administrator by username
$admin = new WP_User( null, 'admin' );

Once you have the user object, you can add another role to this user without modifying his current role (which means the user can have as many roles as you want):

$user->add_role( $role_name );

Or you can remove a role from this user, using remove_role():

$user->remove_role( $role_name );

You can also set a role to this user, which means removing all the current roles of this user and assign a new one:

$user->set_role( $role_name );

For manipulating capabilities, you have a bunch of methods that allow you to do various things:

// check whether the user has a certain capability or role name
if ( $user->has_cap( $cap_name ) ) {
    // do something
}

// add a capability to the user and grant access to that capability
$user->add_cap( $cap_name );

// remove a capability from the user
$user->remove_cap( $cap_name );

// remove all capabilities from the user
$user->remove_all_caps();

Conclusion

There, that’s all there is to know about Roles and Capabilities. You might not need to grasp all of this, but it’s definitely helpful to know WordPress has a full-fledged user and role management system, which you can always use for complicated projects. This post has been all theory so far, but in the next tutorial, I’ll show you how to use this knowledge to build a “client login” area for your WordPress portfolio site.

If you have any comment or suggestion, please leave it below!

AJAX is used in many WordPress themes and plugins. However, not all of those themes and plugins implement AJAX properly. This article reveals 5 best practices in developing AJAX for WordPress.

Warning: This is a long and information-packed article. Be sure to bookmark this post so you can always go back for reference! The links below makes it easier to navigate this article.

Table of Content

• Bad ways to implement AJAX
• 1. Use wp_localize_script() to declare javascript global variables
• 2. Use admin-ajax.php to handle AJAX requests
• 3. Use nonces and check for permission
• 4. Use the built-in jQuery Form plugin to submit forms
• 5. Be careful with jQuery default JSON parsing

Bad ways to implement AJAX

I have read the code of many plugins that implement AJAX. While some of them do it the right way, most of them don’t. The common pattern in those plugins is: a PHP file to handle the AJAX request, and another PHP file that spits out javascript code to make the AJAX request.

The PHP file that handles the AJAX almost always begin with this line:

require_once( "../../../../wp-config.php" );
// or require_once( "../../../../wp-load.php" );

What’s wrong with this is that sometimes users set up their folder structure differently, making the relative path declared in the PHP file above invalid. Another downside to this, is if you’re using Object Oriented approach to develop your plugin (wrapping your plugin functions in a class), you won’t have direct access to the necessary properties and private functions of the class.

Along with the PHP file above, another PHP file is necessary to output the javascript that makes the AJAX request. This has to be a PHP file instead of a normal JavaScript file, because (again) it has to include wp-config.php (or wp-load.php), so that it can get the absolute URL to the PHP file that handles the request, or load some additional data from the database. In order to load this “fake” javascript file, the whole WordPress framework needs to be loaded again.

Sorry for keeping you off the good part of the article so long. But avoiding doing things the wrong way is as important as knowing how to do them right. Without further ado, here are 5 crucial tips for implementing AJAX in WordPress properly.

1. Use wp_localize_script() to declare javascript global variables

Although wp_localize_script() is created for localization, it also has another great use. You can declare javascript variables with namespaces to use with your script. Here’s the syntax:

wp_localize_script( $handle, $namespace, $variable_array );

Here’s how you should declare the URL to the file that handles AJAX (in this example, I use admin-ajax.php, which is discussed in tip #2):

// embed the javascript file that makes the AJAX request
wp_enqueue_script( 'my-ajax-request', plugin_dir_url( __FILE__ ) . 'js/ajax.js', array( 'jquery' ) );

// declare the URL to the file that handles the AJAX request (wp-admin/admin-ajax.php)
wp_localize_script( 'my-ajax-request', 'MyAjax', array( 'ajaxurl' => admin_url( 'admin-ajax.php' ) ) );

This way, you won’t have to use PHP to print out JavaScript code, which is both ugly and non-cacheable. If you take a look at the generated HTML in the <head> element, you’ll find this:

<script type="text/javascript" src="http://example.com/wordpress/wp-content/plugins/myajax/js/ajax.js"></script>
<script type="text/javascript">
/* <![CDATA[ */
var MyAjax = {
	ajaxurl: "http://example.com/wordpress/wp-admin/admin-ajax.php"
};
/* ]]> */
</script>

Now, in your ajax.js file, you can use MyAjax.ajaxurl without having to resort to PHP and including wp-load.php. Please refer to tip #2 below for more about setting up the javascript code that sends the request, and how to handle the request properly.

2. Use admin-ajax.php to handle AJAX requests

AJAX requests should be directed to wp-admin/admin-ajax.php. I know the “admin” part of the file name is a bit misleading, but all requests in the front-end (the viewing side) as well as the admin panel can be processed in admin-ajax.php.

There’s a required parameter for a request sent to admin-ajax : it’s called action. This parameter is necessary because when admin-ajax process the request, it will fire one of these hooks, depending on whether the current viewer is logged in or not:

// this hook is fired if the current viewer is not logged in
do_action( 'wp_ajax_nopriv_' . $_REQUEST['action'] );

// if logged in:
do_action( 'wp_ajax_' . $_POST['action'] );

The JavaScript code that submits the AJAX request should look something like this:

jQuery.post(
	// see tip #1 for how we declare global javascript variables
	MyAjax.ajaxurl,
	{
		// here we declare the parameters to send along with the request
		// this means the following action hooks will be fired:
		// wp_ajax_nopriv_myajax-submit and wp_ajax_myajax-submit
		action : 'myajax-submit',

		// other parameters can be added along with "action"
		postID : MyAjax.postID
	},
	function( response ) {
		alert( response );
	}
);

Now all we have to do is hook our existing plugin or theme file up with those provided ajax actions without having to create a separate file to process the request:

// if both logged in and not logged in users can send this AJAX request,
// add both of these actions, otherwise add only the appropriate one
add_action( 'wp_ajax_nopriv_myajax-submit', 'myajax_submit' );
add_action( 'wp_ajax_myajax-submit', 'myajax_submit' );

function myajax_submit() {
	// get the submitted parameters
	$postID = $_POST['postID'];

	// generate the response
	$response = json_encode( array( 'success' => true ) );

	// response output
	header( "Content-Type: application/json" );
	echo $response;

	// IMPORTANT: don't forget to "exit"
	exit;
}

3. Use nonces and check for permission

It can’t be stressed enough that you need to check for permission for every action a user takes. Developers often neglect this, and the results are disastrous, because without layers that checks for sufficient permissions, a malicious user could escalate his privilege and do all sorts of naughty things with your website that you have spent so much effort to build. There are two layers of security that you need to apply to all AJAX request most of the time.

Nonces

Nonces are Numbers that are generated and used once. Nonces are used to make sure the action is initiated by the authorized user from a certain location. Here’s an interesting analogy by Jon Sykes, which makes everything easier to understand:

When you arrive at a deli counter you’re asked to take a ticket. Once the counter reaches your number you had the ticket back to the server (who throws it away) and they serve you. They then move onto serving the next person in the who’s ticket matches the number of the digital screen.

If someone comes along and tries to jump the line (queue) they can’t unless they have a ticket.

If they manage to get hold of someones old ticket, they can’t use it, as it’s already been used and the digital counter has moved on.

To further extend the analogy, you then make every customer sign for the ticket when they take one, and you then check not only that there ticket matches but also make them sign again to check that their first signature matches the one they have before they get served.

Taking it to a silly level, you’d only allow users to get a ticket when they walked in the front door of the store (that they have to sign for). This then prevents someone climbing in a window and trying to forge your signature to get served. Because they didn’t come in the front door, they don’t have any access to the tickets, so they have no way of jumping ahead of you and ordering the last of the Bologna.

Mark Jaquith and Vladimir Prelovac also covered Nonces and how to use them generally. Make sure you read those articles because you’ll definitely need them for almost all kinds of WP development (not only AJAX related).

However, it should be stressed that nonces are useful only in situations where the AJAX request has something to do with data or content manipulation. If the request is only for retrieving comment count, or post content for example, nonces are not required. AJAX requests to post / edit / delete contents definitely need nonce checking.

OK, enough theory. Here’s how to implement nonces in your AJAX request.

First, you need to generate a nonce, and use wp_localize_script() to include it as a javascript variable:

// embed the javascript file that makes the AJAX request
wp_enqueue_script( 'my-ajax-request', plugin_dir_url( __FILE__ ) . 'js/ajax.js', array( 'jquery' ) );

wp_localize_script( 'my-ajax-request', 'MyAjax', array(
	// URL to wp-admin/admin-ajax.php to process the request
	'ajaxurl'          => admin_url( 'admin-ajax.php' ),

	// generate a nonce with a unique ID "myajax-post-comment-nonce"
	// so that you can check it later when an AJAX request is sent
	'postCommentNonce' => wp_create_nonce( 'myajax-post-comment-nonce' ),
	)
);

Now your JavaScript can use the global variable MyAjax.postCommentNonce to get the nonce. You have to send the nonce along with your request so that the AJAX handler can check it:

jQuery.post(
	MyAjax.ajaxurl,
	{
		action : 'myajax-submit',
		postID : MyAjax.postID,

		// send the nonce along with the request
		postCommentNonce : MyAjax.postCommentNonce
	},
	function( response ) {
		alert( response );
	}
);

Here’s essentially the same code as in tip #2, except that I’ve added nonce validation to make sure the request is valid:

// if both logged in and not logged in users can send this AJAX request,
// add both of these actions, otherwise add only the appropriate one
add_action( 'wp_ajax_nopriv_myajax-submit', 'myajax_submit' );
add_action( 'wp_ajax_myajax-submit', 'myajax_submit' );

function myajax_submit() {

	$nonce = $_POST['postCommentNonce'];

	// check to see if the submitted nonce matches with the
	// generated nonce we created earlier
	if ( ! wp_verify_nonce( $nonce, 'myajax-post-comment-nonce' ) )
		die ( 'Busted!')

	// get the submitted parameters
	$postID = $_POST['postID'];

	// generate the response
	$response = json_encode( array( 'success' => true ) );

	// response output
	header( "Content-Type: application/json" );
	echo $response;

	// IMPORTANT: don't forget to "exit"
	exit;
}

There, all done. Now here’s an important note. If you want to allow the user to initiate the AJAX request multiple times (like posting multiple comments on the same page) , you need to regenerate a new nonce, include it in your response, and then reassign that new nonce to MyAjax.postCommentNonce. Otherwise, the same nonce would be used over and over again, and the subsequent AJAX requests will fail.

Check for permissions

Lots of plugins neglect to check for sufficient permission for AJAX requests. Always use current_user_can() to make sure the request is made by an authorized user. Here’s the final bulletproofed version of the request handling code:

// if both logged in and not logged in users can send this AJAX request,
// add both of these actions, otherwise add only the appropriate one
add_action( 'wp_ajax_nopriv_myajax-submit', 'myajax_submit' );
add_action( 'wp_ajax_myajax-submit', 'myajax_submit' );

function myajax_submit() {

	$nonce = $_POST['postCommentNonce'];

	// check to see if the submitted nonce matches with the
	// generated nonce we created earlier
	if ( ! wp_verify_nonce( $nonce, 'myajax-post-comment-nonce' ) )
		die ( 'Busted!')

	// ignore the request if the current user doesn't have
	// sufficient permissions
	if ( current_user_can( 'edit_posts' ) ) {
		// get the submitted parameters
		$postID = $_POST['postID'];

		// generate the response
		$response = json_encode( array( 'success' => true ) );

		// response output
		header( "Content-Type: application/json" );
		echo $response;
	}

	// IMPORTANT: don't forget to "exit"
	exit;
}

4. Use the built-in jQuery Form plugin to submit forms

Most of the time you use AJAX to avoid page reload when submitting forms. Not everyone knows that WordPress also provide a jQuery plugin to deal with AJAX form submission. To use this jQuery plugin, include it by using “jquery-form” as the handle:

wp_enqueue_script( 'json-form' );

Then, submitting form using AJAX is a breeze:

jQuery('#myForm1').ajaxForm({
	data: {
		// additional data to be included along with the form fields
	},
	dataType: 'json',
	beforeSubmit: function(formData, jqForm, options) {
		// optionally process data before submitting the form via AJAX
	},
	success : function(responseText, statusText, xhr, $form) {
		// code that's executed when the request is processed successfully
	}
});

There are a lot more options for you to configure. Check out jQuery Form plugin documentation for more details.

5. Be careful with jQuery default JSON parsing

At the moment of this writing, the latest stable version of WordPress is 2.9.2 . In this version of WordPress, the default jQuery version is 1.3.2 .

In jQuery 1.3.2 or earlier, jQuery uses eval to convert a JSON string into an object. While this is fast, it’s not safe:

The eval function is very fast. However, it can compile and execute any JavaScript program, so there can be security issues. The use of eval is indicated when the source is trusted and competent. It is much safer to use a JSON parser. In web applications over XMLHttpRequest, communication is permitted only to the same origin that provide that page, so it is trusted. But it might not be competent. If the server is not rigorous in its JSON encoding, or if it does not scrupulously validate all of its inputs, then it could deliver invalid JSON text that could be carrying dangerous script. The eval function would execute the script, unleashing its malice.

from json.org

jQuery 1.3.3 and later will automatically check if there’s already a JSON parser, and use that parser instead of eval(). WordPress also provides the javascript JSON parser in wp-includes/js/json2.js. Including it is simple:

wp_enqueue_script( 'json2' );

Then, to make sure your script parses JSON the safe way, there are two ways:

The first way is to include your own version of jQuery (equal or later than 1.3.3)

wp_enqueue_script( 'json2' );
// don't forget to specify dependency
wp_enqueue_script( 'myjQuery', plugin_dir_url( __FILE__ ) . 'js/jquery.1.4.2.js', array( 'json2' ) );

The second way is to use WordPress supplied jQuery, but make sure that you don’t specify “json” as the response type, and use the included JSON parser to do the dirty job. You need to set the dependency first:

// embed the javascript file that makes the AJAX request
// don't forget to specify 'json2' as the dependency
wp_enqueue_script( 'my-ajax-request', plugin_dir_url( __FILE__ ) . 'js/ajax.js', array( 'jquery', 'json2' ) );

Then use JSON parser to parse the response string:

jQuery.post( MyAjax.ajaxurl, { action : 'myajax-submit' },
	function( jsonString ) {
		// use JSON parser on the response string instead of
		// specifying the response type as json
		var object = JSON.parse(jsonString);
	}
);

Conclusion

AJAX makes interaction with users more smooth and responsive, and is highly recommended for consideration when you develop your own plugins or themes. However, it’s vital that AJAX is implemented correctly and securely, otherwise the consequence could be disastrous. This article covers 5 most essential tips that all serious WordPress developers should employ to make sure their AJAX plugins or themes function well and safe.

Do you have other AJAX tips or tricks that you want to share? Drop in a comment below. Your input is always appreciated!

Since WordPress 2.5, Shortcode has proven to be one of the most powerful features that allows lots of room for flexibility and customization. However, as anything that has the word “code” in it, shortcodes are not very user friendly. For people who are used to using WYSIWYG, shortcode usage can be confusing sometimes. This article shows you how to make shortcodes in your themes and plugins more accessible and user friendly.

Usability Problems

Take the gallery shortcode for instance. It allows users to include a WordPress gallery in a post or page. Here’s its simplest form:

[ gallery ]

But if the user wants to set more advanced options, such as the number of columns, or the thumbnail size, they’ll have to type in some attributes, which look similar to HTML attributes

[ gallery columns="4" size="medium" ]

This is not user friendly, because of the following three reasons:

1. To customize a shortcode, most of the time you have to look at the documentation. It’s hard to memorize all the available attributes and values.
2. Not all users are familiar with HTML syntax, as a result they might get confused about specifying attributes.
3. It’s easy to make a typo, or specify the wrong value for an attribute.

Solution

Shortcode is, after all, code. And code is not user friendly. The less end-users have to “code”, the better.

Therefore, it’s essential that WordPress developers provide a user interface for everything that’s supposed to be customized by users. Shortcode is no exception. The best solution to deal with shortcode, is to add a button to the visual editor’s toolbar, and display a nice GUI to configure all available shortcode attributes.

What we’re going to do next, is create a small plugin that provides such an interface for the gallery shortcode.

Note: WordPress already has an UI to customize the gallery shortcode, but it’s buried deep inside the Media Manager.

So, let’s start with the bare bones of a plugin file. I’ll assume that you already know how to develop your own plugin. Otherwise, here’s your bible.

I prefer the Object Oriented approach, so here’s what I’ve got:

/*
Plugin Name: mygallery
Plugin URI: http://wphardcore.com
Description: A simple user interface for Gallery shortcode
Version: 0.1
Author: Gary Cao
Author URI: http://garyc40.com
*/

if ( ! defined( 'ABSPATH' ) )
	die( "Can't load this file directly" );

class MyGallery
{
	function __construct() {
	}

}

$mygallery = new MyGallery();

Now, there are two WordPress filters that we’ll be using to add a button to the visual editor’s toolbar.

• mce_external_plugins: registers our javascript file that implements our button.
• mce_buttons: registers our button.

Go back to your WordPress admin panel, activate your plugin and hook our plugin up with these filters:

function __construct() {
	add_action( 'admin_init', array( $this, 'action_admin_init' ) );
}

function action_admin_init() {
	// only hook up these filters if we're in the admin panel, and the current user has permission
	// to edit posts and pages
	if ( current_user_can( 'edit_posts' ) && current_user_can( 'edit_pages' ) ) {
		add_filter( 'mce_buttons', array( $this, 'filter_mce_button' ) );
		add_filter( 'mce_external_plugins', array( $this, 'filter_mce_plugin' ) );
	}
}

function filter_mce_button( $buttons ) {
	// add a separation before our button, here our button's id is "mygallery_button"
	array_push( $buttons, '|', 'mygallery_button' );
	return $buttons;
}

function filter_mce_plugin( $plugins ) {
	// this plugin file will work the magic of our button
	$plugins['mygallery'] = plugin_dir_url( __FILE__ ) . 'mygallery_plugin.js';
	return $plugins;
}

Here’s the hard part. Create a new javascript file in the same folder as your plugin file, and name it mygallery_plugin.js.

// closure to avoid namespace collision
(function(){
	// creates the plugin
	tinymce.create('tinymce.plugins.mygallery', {
		// creates control instances based on the control's id.
		// our button's id is "mygallery_button"
		createControl : function(id, controlManager) {
			if (id == 'mygallery_button') {
				// creates the button
				var button = controlManager.createButton('mygallery_button', {
					title : 'MyGallery Shortcode', // title of the button
					image : '../wp-includes/images/smilies/icon_mrgreen.gif',  // path to the button's image
					onclick : function() {
						// do something when the button is clicked :)
					}
				});
				return button;
			}
			return null;
		}
	});

	// registers the plugin. DON'T MISS THIS STEP!!!
	tinymce.PluginManager.add('mygallery', tinymce.plugins.mygallery);
})()

We’re using tinyMCE’s API to register our editor plugin, and create the button. If you don’t understand what the hell happened above, just close your eyes, and forget about it for a minute (seriously), then proceed with our next step. You can always come back and dig into tinyMCE’s documentation to get a grasp of what the snippet above means.

Now go to your WordPress admin panel, edit or create a new post (or page). You’ll see our tiny little button in the toolbar, preceded by a separator:

If you click the button, nothing happens because you haven’t written any code that handles that part yet. If I cover that part in this article too, it’s going to be too long. So Download the Sourcecode and take a look for yourself. The code is abundant with documentation, but if you have any questions, shoot me a comment!

Here’s a screenshot of the final results:

mygallery.zip