Introduction

For our online radio website, we will feature some DJ’s/hosts that play on the air. We will create a custom post type for them, where we can add a picture, biography and other useful information. We will also create a show schedule using the WordPress custom post type again. Mixed with some custom metaboxes, we’re going to make the show administration simple to manage.

Step 1 Creating DJ/Host Custom Post Type

To avoid files cluttered with code, we’ll separate our snippets and by using the PHP function include, we’ll include them to our file. Open your functions.php file, located in your current theme folder and add the following snippet:

include('schedule.php');

Once complete, create a new file called schedule.php, then we add our functions to register our new post type.

For more information on custom post types, try this page custom post type

// Register DJs Post Type
add_action( 'init', 'register_my_radios_djs' );

function register_my_radios_djs() {
	$labels = array(
		'name' => _x( 'Radio Djs', 'radios_djs' ),
		'singular_name' => _x( 'Radio Dj', 'radios_djs' ),
		'add_new' => _x( 'Add New', 'radios_djs' ),
		'add_new_item' => _x( 'Add New Dj', 'radios_djs' ),
		'edit_item' => _x( 'Edit Dj', 'radios_djs' ),
		'new_item' => _x( 'New Dj', 'radios_djs' ),
		'view_item' => _x( 'View Dj', 'radios_djs' ),
		'search_items' => _x( 'Search Dj', 'radios_djs' ),
		'not_found' => _x( 'No dj  found', 'radios_djs' ),
		'not_found_in_trash' => _x( 'No dj  found in Trash', 'radios_djs' ),
		'parent_item_colon' => _x( 'Parent Dj:', 'radios_djs' ),
		'menu_name' => _x( 'Radio Djs', 'radios_djs' )
	);
	$args = array(
		'labels' => $labels,
		'hierarchical' => true,
		'description' => 'WordPress Radio DJS',
		'supports' => array( 'title', 'editor', 'thumbnail' ),
		'taxonomies' => array( 'category', 'radios_djs' ),
		'public' => true,
		'show_ui' => true,
		'show_in_menu' => true,
		'show_in_nav_menus' => true,
		'publicly_queryable' => true,
		'exclude_from_search' => false,
		'has_archive' => true,
		'query_var' => true,
		'can_export' => true,
		'rewrite' => true,
		'capability_type' => 'post'
	);

	register_post_type( 'radios_djs', $args );
}

Adding Post Thumbnails

For this tutorial, we will be using formatted images for the schedule. Therefore, we’re going to add the WordPress post thumbnail functionality.

if ( function_exists( 'add_theme_support' ) ) {
	add_theme_support( 'post-thumbnails' );
	set_post_thumbnail_size( 150, 150, true );
	add_image_size( 'dj-pic', 260, 160 );
}

Notice that we’ve added the function add_image_size and some parameters. We’ll be using the post thumbnail size of 260×160 for our end result.

Step 2 Creating Schedule Custom Post Type

Just like the previous step, we’re going to create a next post type using the same method and simply changing some names and variables.

// Register Schedule Post Type
add_action( 'init', 'register_my_dj_schedule' );

function register_my_dj_schedule() {

	$labels = array(
		'name' => _x( 'Dj Schedule', 'dj_schedule' ),
		'singular_name' => _x( 'Dj Schedule', 'dj_schedule' ),
		'add_new' => _x( 'Add New', 'dj_schedule' ),
		'add_new_item' => _x( 'Add New Schedule', 'dj_schedule' ),
		'edit_item' => _x( 'Edit Dj Schedule', 'dj_schedule' ),
		'new_item' => _x( 'New Dj Schedule', 'dj_schedule' ),
		'view_item' => _x( 'View Dj Schedule', 'dj_schedule' ),
		'search_items' => _x( 'Search Dj Schedule', 'dj_schedule' ),
		'not_found' => _x( 'No dj schedule found', 'dj_schedule' ),
		'not_found_in_trash' => _x( 'No dj schedule found in Trash', 'dj_schedule' ),
		'parent_item_colon' => _x( 'Parent Dj Schedule:', 'dj_schedule' ),
		'menu_name' => _x( 'Dj Schedule', 'dj_schedule' )
	);

	$args = array(
		'labels' => $labels,
		'hierarchical' => true,
		'description' => 'WordPress DJ Schedule',
		'supports' => array( 'title', 'editor', 'thumbnail' ),
		'taxonomies' => array( 'category', 'dj_schedule' ),
		'public' => true,
		'show_ui' => true,
		'show_in_menu' => true,
		'show_in_nav_menus' => true,
		'publicly_queryable' => true,
		'exclude_from_search' => false,
		'has_archive' => true,
		'query_var' => true,
		'can_export' => true,
		'rewrite' => true,
		'capability_type' => 'post'
	);

	register_post_type( 'dj_schedule', $args );
}

Step 3 Adding Custom Meta Boxes

This tutorial won’t explain every aspect of creating custom metaboxes, but we’ll highlight the most significant. With that said, we’ll begin by calling two add_action hooks for our metaboxes.

add_action( 'add_meta_boxes', 'rschedule_box' );
add_action( 'save_post', 'dj_schedule_save_postdata' );

In you’re interested in learning more about custom meta boxes. This is a great read: How to Create Custom WordPress Write/Meta Boxes

Add the Meta-Boxes

The function rschedule_box which was previously mentioned in the hook, will register a group of metaboxes to our post edit screen. We will use these metaboxes on our Schedule Edit page.

function rschedule_box() {
	add_meta_box(
		'time_slot_id',
		__( 'Time Slots', 'time_slot_text' ),
		'radio_time_slots',
		'dj_schedule'
	);
	add_meta_box(
		'dj_select_id',
		__( 'Select DJ', 'dj_select_text' ),
		'radio_get_dj_select_box',
		'dj_schedule',
		'side'
	);
}

Creating a DJ Select List

In this step, we create a function that will generate a select list on our screen. This list will display all the DJs/Hosts added to our custom post type, that we created in Step 1. This function will query the post type and return the items as an array, then we will loop though the array and mix it with some HTML. This way, we can reference the DJ post ID, which we will need in generating our output later.

function radio_get_dj_select_box($post) {
	wp_nonce_field( 'radio_schedule', 'schedule_noncename' );
	echo '<label for="dj_id">';
	_e("DJ/Host", 'dj_id' );
	echo '</label> ';
	$args = array( 'post_type' => 'radios_djs');
	$loop = new WP_Query( $args );
	echo '<select name="dj_id" id="dj_id">';
	foreach ( $loop->posts as $dj ) {
		if ( $dj->ID == get_post_meta( $post->ID, 'dj_id', true ) ) {
			$select = 'selected';
		}
		else {
			$select = '';
		}
		echo '<option value="'.$dj->ID.'" '.$select.'>'.$dj->post_title.'</option>';
	}
	echo '</select>';
}

Creating Time Slots

The next function is our function that will display the days of the week and options to choose the time when the show will be live. In order for us to get the days of the week, we’ll create an array.

$days = array(
	'sun' => 'Sunday',
	'mon' => 'Monday',
	'tue' => 'Tuesday',
	'wed' => 'Wednesday',
	'thu' => 'Thursday',
	'fri' => 'Friday',
	'sat' => 'Saturday'
);

Now that’s done, let’s create our time slot function. Add the following code to your file.

/* Prints the box content */
function radio_time_slots($post) {

	global $days;
	// Use nonce for verification
	wp_nonce_field( 'radio_schedule', 'schedule_noncename' );

	foreach ( $days as $key => $value ) {
		$selected_start  = get_post_meta( $post->ID, 'schdule_dj-start-'.$key, true );  //Start Time
		$selected_end  = get_post_meta( $post->ID, 'schdule_dj-end-'.$key, true );  	  //End Time

		echo '<strong>'.$value.'</strong><br />';
		echo '<label for="schdule_dj-start-'.$key.'">';
		_e("Start", 'schdule_dj-start-'.$key );
		echo '</label> ';
		echo '<select name="schdule_dj-start-'.$key.'" id="schdule_dj-start-'.$key.'">';
		schedule_time_select($selected_start);
		echo '</select>';
		echo '<label for="schdule_dj-end-'.$key.'">';
		_e("End", 'schdule_dj-end-'.$key );
		echo '</label> ';
		echo '<select name="schdule_dj-end-'.$key.'" id="schdule_dj-end-'.$key.'">';
		schedule_time_select($selected_end);
		echo '</select>';
		echo '<br />';
	}
}

As you will notice we referenced our array of days by using global $days. We could have placed it inside of the function but we will be referencing it occasionally, so we’ll leave it on the outside. Also, take a look at how the array of days is used, we have chosen to loop some select fields using the days, so we should have several select fields for the 7 days of the week. The variables $selected_start and $selected_end use the WordPress function get_post_meta, in order to get the currently selected value for our list. We are also strategically using the key of our array in our list to name our form field, label and get our selected value. When PHP interprets the field name, it will look similar to this schdule_dj-start-sun where sun will be changed according to the current day in the loop. This will be quite useful to us in other parts of the tutorial. Lastly, you will realise that we’ve referenced the function schedule_time_select, that we have not created as yet. Let’s create that function now.

function schedule_time_select($selected) {
	$start = 8*60+0;
	$end = 24*60+0;
	echo '<option vlaue="0">N/A</option>'; //Default Value
	for($time = $start; $time<=$end; $time += 15) {
		$minute = $time%60;
		$hour = ($time-$minute)/60;
		if ( $selected == sprintf( '%02d:%02d', $hour, $minute ) ) {
			$select = 'selected';
		}
		else {
			$select = '';
		}
		echo '<option value='.sprintf('%02d:%02d', $hour, $minute).' '.$select.'>'.sprintf('%02d:%02d', $hour, $minute).'</option>';
	}
}

This function will generate the options for our select list. Each option will be incremented by 15 minutes and is based on the the 24 hour system. For the first option, we set a value of 0 for the days that we wish to neglect. Within the loop, there is a small if statement that checks the value sent from our radio time slot function to determine if the option should be set to selected.

Step 3 Saving the Meta Boxes

Finally, it’s time to save all of our metabox information. WordPress has a very simple and straight forward way of saving these options but we’re going to make it more dynamic. Add the following snippet to your file.

// Save Meta Data
function dj_schedule_save_postdata( $post_id ) {
	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE )
		return;

	if ( !wp_verify_nonce( $_POST['schedule_noncename'], 'radio_schedule' ) )
		return;

	if ( 'page' == $_POST['post_type'] ) {
		if ( !current_user_can( 'edit_page', $post_id ) )
			return;
	}
	else {
		if ( !current_user_can( 'edit_post', $post_id ) )
			return;
	}

	if( isset( $_POST['dj_id'] ) ) {
		update_post_meta( $post_id,'dj_id', esc_attr( $_POST['dj_id'] ) );
	}

	global $days;

	foreach($days as $key=>$value) {

		if( isset( $_POST['schdule_dj-start-'.$key] ) ) {
			update_post_meta( $post_id,'schdule_dj-start-'.$key, esc_attr( $_POST['schdule_dj-start-'.$key] ) );
		}

		if( isset( $_POST['schdule_dj-end-'.$key] ) ) {
			update_post_meta( $post_id,'schdule_dj-end-'.$key, esc_attr( $_POST['schdule_dj-end-'.$key] ) );
		}
	}
}

Once again, you see the usefulness of our global days variable. In this function, we loop through each day and we save our options from our select field by changing the name as the days loops through.

Step 3 Saving the Meta Boxes

Wow! If you’re still with me, let’s put all these codes to work, shall we? Ok, great! The snippet below demonstrates how we’re going to loop through each schedule that we created and place in divs. Add that bit of code and let’s break it down.

function show_schedule() {
	global $days;
	$html='';
	$html.= '<div>';
	$args = array( 'post_type' => 'dj_schedule');
	$loop = new WP_Query( $args );
	foreach ( $loop->posts as $item ):
		$html.= '<div class="scheduleBox">';
		$html.= '<h3>'.$item->post_title.'</h3>';
		$dj_id = get_post_meta($item->ID, 'dj_id', true);
		$dj = get_post($dj_id);
		$html.= '<div>'.$dj->post_title.'</div>';
		$html.= '<div>'.get_the_post_thumbnail($dj->ID, 'dj-pic').'</div>';
		foreach( $days as $key => $value ) {
			$start = get_post_meta($item->ID, 'schdule_dj-start-'.$key, true);
			$end = get_post_meta($item->ID, 'schdule_dj-end-'.$key, true);
			if ( $start <> 0 )
				$html.= '<div id="time">'.$value.'   '.$start.'-'.$end.'</div>';
		}
		$html.= '</div>';
	endforeach;
	$html.= '<div style="clear:both;"></div>';
	$html.='</div>';
	return $html;
}

Firstly, we make a loop for our custom post type dj_schedule, create a div and list the title. While inside the div, we fetch the DJ ID we added in the admin using the get_post_meta function. Then we use that same ID and call the WordPress function get_post for the values of that post and assign them to a variable which we then use to get the DJ’s name and photo.

Getting the Time Slots

Directly below our DJ, we have our day loop which loops through each day while making a check to see if any start time exists for that day. If they do exist, then we output the start and end time into a div.

Adding Our Schedule to a Page

We can do many things to add the schedule to a page, but for this tutorial, we will simply use a shortcode. So, with just one line of code, we will create a short code that we can call add on any page and voila! We have a working radio schedule!

add_shortcode('show_schedule', 'show_schedule');

Conclusion

This is the first phase of adding more great features to your WP radio website. I have chosen some simple styling for the layout, you can add these styles to your style.css file. In another tutorial, I will explain how to create a nice live stream pop-up with current show, DJ and radio player.

.scheduleBox { background-color: #333333; border: #000000 1px solid; color: #fafafa; float: left; margin-left: 10px; height: 100%; }
.scheduleBox h3 { font-size: 14px; }
.scheduleBox #time { background: #666666; border-bottom: #000000 1px solid; }

.scheduleBox:hover { background-color: #000; border: #000000 1px solid; color: #FFCC00; float: left; margin-left: 10px; }
.scheduleBox h3:hover { color: #FF9900; }
.scheduleBox #time:hover { background: #333333; border-bottom: #000000 1px solid; }

Your feedback is much appreciated. Let me know what you think in the comments below. Happy coding!

Psdtuts+ — Photoshop Tutorials

• 

  Quick Tip: Create a Metallic Copper Text Effect Using Layer Styles in Photoshop

  In this tutorial we will explain how to create a metallic copper text effect using layer styles in Photoshop. Let’s get started!

  Visit Article

• 

  How to Draw a Leica Camera in Photoshop

  Leica is considered one of the most prestigious camera brands. In this tutorial, we will draw one of the most notable Leica cameras in Photoshop, the Leica M1. Let’s get started!

  Visit Article

• 

  Create a Tasty 3D Typographic Illustration – Tuts+ Premium Tutorial

  If you’ve got a sweet tooth, then we’ve got a mouth-watering tutorial for you. In this Tuts+ Premium tutorial, author Mark Mayers will show you how Photoshop CS6 Extended’s new 3D tools can be utilized to create a typographic illustration that includes lots of sugary treats. This tutorial is available exclusively to Tuts+ Premium Members.

  Visit Article

---

Nettuts+ — Web Development Tutorials

• 

  Things I Learned While Interning at YUI

  For eight months, I had the opportunity to intern with the YUI Team at Yahoo, while I was completing my engineering degree. Today, I’d like to share the top ten things that I learned from my experience with YUI.

  Visit Article

• 

  Coda 2: Reviewed

  Well, it happened; Panic finally released the long-awaited version two of their popular code editor, Coda. But does it live up to the hype? Well, that depends on what type of coder you are. Read the full review after the jump!

  Visit Article

• 

  Key Software Principles You Must Understand

  If you’re in software development, new techniques, languages and concepts pop up all of the time. We all feel those nagging doubts every now and then: “can I keep up with the changes and stay competitive?” Take a moment, and sum a line from my favourite movie, Casablanca: “The fundamental things apply, as time goes by.”

  Visit Article

---

Vectortuts+ — Illustrator Tutorials

• 

  Create a Vintage Vector Framed Silhouette Design

  In today’s tutorial I’m going to collaborate with a great friend of mine, Ashley Benson and show you how to create a Victorian styled Silhouette. She’s been great to give me this wonderful sketch specifically for our vintage vector art tutorial, so feel free to download it as part of your Tuts+ Premium membership to practice on. Learn basic techniques on creating a detailed, framed silhouette inspired by Victorian vintage postcard designs using scatter brushes, patterns and more. Using these techniques you can create your own vintage illustrations.

  Visit Article

• 

  Quick Tip: Microstock Illustrations with Corel Draw, Tricks and Tips

  With the vector software Corel Draw you are able to draw everything you can imagine. However, if you are using it to create illustrations for the microstock agencies – there are some issues that you must take into consideration. The problem comes with the industry requirement to provide an EPS (Encapsulated PostScript) file, which is mandatory for almost all agencies. See, EPS is Adobe standard and Corel developers don’t like Adobe standards very much…

  Visit Article

• 

  Logo and Identity Design Session

  Audiences identify with effective logos and well composed brand identities. Learn how to craft creative logo designs with impact. In this Creative Session, we have a compilation of inspiring logo design and branding material.

  Visit Article

---

Webdesigntuts+ — Web Design Tutorials

• 

  Quick Tip: Rounded Corners Done Right

  This is going to seem like a no-brainer to many of you, but I see it happening so often I figured it was worth bringing up. We’ll call this issue improperly nested corners; a small detail which can ruin an otherwise brilliant design!

  Visit Article

• 

  Create a Customized HTML5 Audio Player

  During this tutorial I’m going to be introducing you to HTML5 audio and showing you how you can create your own player.

  Visit Article

• 

  Employing AIDA Principles in Web Design

  In this article we’ll discuss how we can use design to implement the principles laid out by AIDA (the marketing acronym, not the Italian opera) and help create sales-orientated web pages.

  Visit Article

---

Phototuts+ — Photography Tutorials

• 

  Simplify and Challenge Your Creativity Using a Single Lens – Tuts+ Premium

  We have another Photo Premium tutorial exclusively available to Premium members today. In this tutorial, try going out on a shoot with only one lens to limit us and force us to think creatively. Luckily, we’ll be guided by professional photographer Simon Plant. Learn more after the jump!

  Visit Article

• 

  Easy Tips for Shooting the Moon

  Pictures of a big moon over a landscape are many times the result of a double exposure. Even when the moon comes closer to Earth, as it did recently, it is too small to fill the frame with normal gear. Still, there are ways to get around the thousands of miles that separate us and our big nightlight.

  Visit Article

• 

  Building a Narrative Through Photojournalism

  Telling visual stories is the work and craft of the photojournalist. I remember it from the first hard news story I covered, back in 1980: a bank robbery that completely defined my future.

  Visit Article

---

Cgtuts+ — Computer Graphics Tutorials

• 

  Building The Caterpillar 797 In 3D Studio Max – Creating The Tires, Rims, Cabin And Bridge

  Today we’re kicking off an awesome new tutorial series by Sasa Posloncec where you’ll learn how to model the ridiculously huge Caterpillar 797B mining dump truck. Spanning three parts this series will give you an in-depth look at what it takes to create a fully realized vehicle model in 3D Studio Max using blueprints and photo reference. As Sasa walks you through the creation of each part, you’ll learn how to work with Max’s Edit Poly modifier, spline tools and much more!

  Visit Article

• 

  Image Based Lighting: The Complete Workflow with Maya, HDR Shop & Photoshop

  So Image Based Lighting…. What is it, and how can you use it to your advantage? Get the answers in this tutorial from James Whiffin where you’ll not only learn about implementing IBL into your projects, but how to setup and shoot your very own high dynamic range images, a topic rarely seen in tutorials.

  Visit Article

• 

  Modeling A Modern Interior Scene In Blender

  In this tutorial we will be modeling an interior scene from a reference photo. It is written for the complete beginner, you’ll learn how to setup a background image and how to match the camera to it, as we follow a very simple workflow for building up the scene with a variety of basic modeling techniques that will give you a very good basis on how to approach any kind of modeling.

  Visit Article

---

Aetuts+ — After Effects Tutorials

• 

  Fantastic Facial Motion Capture – Tuts+ Premium

  In this tutorial, I will be sharing with you how to achieve 2D facial motion capture in After Effects. The technique involves acquiring motion data from dots on a face, and using that motion data to manipulate the position of puppet pins on an image that you want to animate. It’s a very useful way of quickly creating detailed animations, and characterizing inanimate objects, like the rock face in the intro. It’s also possible to do face replacement.

  Visit Article

• 

  Muted Color Grading And A Vintage Film Burn Using Fractal Noise

  In today’s tutorial I’ll be showing how to take DSLR footage and give it the popular “Muted” color grade. After we cover the color grading, I’m gonna show you how to create a film burn effect from scratch using “Fractal Noise.”

  Visit Article

• 

  How To Create A Stupendous Stuttering Jumper Punch

  In this tutorial we will learn how to create an advanced and well composited Jumper Punch by using a matte, some displacement, and smoke to add style to the final effect. Throughout the tutorial, we will be using basic expressions. We’ll learn to position the jumps in time and space and give the illusion of a jumper disappearing and reappearing with a trajectory. Let’s “Jump” in… :)

  Visit Article

---

Audiotuts+ — Audio & Production Tutorials

• 

  D Mixing Part 7: Mastering, The Final Chapter (Part 2)

  In the final installment of the series, we are going to look at the final effects on the signal chain (Master EQ, Master Reverb, Master Limiter), and discuss the various final print options.

  Visit Article

• 

  Quick Tip: How to Make a Snare Roll Generator

  Today I will show you my new gadget, and teach you how to make it. A snare roll is an important part of a song. It can be used in many situations: as a creative element of a song or introducing something important like a breakdown. My new toy will reduce the time it takes to create one.

  Visit Article

• 

  Cures For A Songwriting Slump

  Sooner or later, even the most inspired and prolific songwriter will stumble into that dreadful and frightening abyss known as writer’s block. To call it frightening is truly not an overstatement when one is attempting to land a writing deal, keep a publisher happy, or best-case scenario, keep the already lucrative royalties flowing. The voice of defeat stirs in every songwriter at some point, first as a murmur and then as a blood-curdling scream.

  Visit Article

---

Wptuts+ — WordPress Tutorials

• 

  The Complete Guide To The WordPress Settings API, Part 8: Validation, Sanitisation, and Input II

  We’ve reached the final article of the series. In the last post, we took a look at introducing validation, sanitization, and a couple of basic input elements that we can take advantage of when building option pages.

  Visit Article

• 

  Quick Tip: Conditionally Including JS and CSS With get_current_screen

  As many stated before me: “A good WordPress citizen only loads their files where they’re needed”. This principle applies both to front-end and back-end (admin). There’s no justification for loading CSS and JS files on every admin page when you only need them on one single page you created. Thankfully doing things the right way is only one function call away.

  Visit Article

• 

  Adding Post Series Functionality to WordPress With Taxonomies

  Ever wrote a “post series” on your blog? If you did, you probably needed to add the links of the other parts of the series into the latest post you wrote. Each time you finished a new part, you had to update the link list of the other parts. There has to be an easier way, right?

  Visit Article

---

Mobiletuts+ — Mobile Development Tutorials

• 

  iOS SDK: UIKit Theme Customization

  Theme customization is a great way to stand out in the App Store, but it isn’t always easy to achieve. This tutorial will teach you several basic UIKit customization tricks that will help distinguish your applications and create more memorable user experiences.
  

  Visit Article

• 

  Introduction to Unity3D

  Unity3D is a powerful cross-platform 3D engine and a user-friendly development environment. Learn how Unity3D can help you create games in this article!
  

  Visit Article

• 

  Analyzing Android Network Traffic

  Network traffic analysis can be a vital part of the software debugging and testing process. This tutorial will teach you how to monitor all incoming and outgoing traffic on an Android device in order to better debug your applications!
  

  Visit Article

BuddyPress like other plugins expands on the core functionality WordPress offers. Although it is important as a freelancer or company to recognise that BuddyPress unlike other plugins adds functionality of epic proportions.

This tutorial aims to show you how to demonstrate a proof of concept quickly and functionally without making any best practice cardinal sins.

Introduction

Over the course of this tutorial we will use a combination of PHP, jQuery and WordPress functions to extend BuddyPress far enough to demonstrate a concept.

Working on member profiles we will without any recourse add a link that allows users to visit a member bookmarks area.

The bookmarks area will be populated with a list of bookmarks a member has decided to save whilst browsing any BuddyPress enabled site.

The scope of bookmarks which can be saved will only be applied to WordPress posts for now, however you may look to build on this further and apply it to other areas of a WordPress powered web site that produces a permalink.

Step 1 The Essentials

We will be building upon the bp-default theme today and creating our own child theme. Below is the structure you should have created.

• style.css – Some additional styles for icons, buttons and lists (this will not be discussed).
• sidebar.php – We will call our widget from here.
• header.php – One modification required.
• functions.php – Register scripts and a apply a filter.
• _inc/img/ – A number of image files to be used.
• _inc/js/bookmarks.js – jQuery and AJAX.
• members/single/home.php – Some PHP logic to enable the template loader.
• members/single/bookmarks/ajax.php – Used for our AJAX calls.
• members/single/bookmarks/loop.php – Retrieval of bookmarks via member profiles.
• members/single/bookmarks/remove.php – Deletion of bookmarks via my member profile.
• members/single/bookmarks/save.php – Storage of bookmarks via my member profile.
• members/single/bookmarks/view.php – Hacky bookmark template loader.
• members/single/bookmarks/widget.php – Called into site sidebar.php.

style.css – Within style.css we need a bare minimum amount of code to allow for theme selection via wp-admin. Let’s do that now.

/*
Theme Name: Bookmark theme
Description: Child theme from bp-default with added support for member bookmarks.
Version: 1.0
Author: WPTuts
Author URI: http://wp.tutsplus.org
Tags: buddypress
Template: bp-default
*/

Tags: buddypress will notify BuddyPress that we are using a BP enabled theme.

Template: bp-default will instruct BuddyPress that when this theme is active to inherit its functionality from the bp-default theme unless a theme file has been modified.

Within sidebar.php we need to load the widget.php.

locate_template(array('members/single/bookmarks/widget.php'), true);

Step 2 functions.php – Register Script

Let’s go ahead and register the bookmarks.js file, it will be required on every page from here on out. In functions.php add the following.

function px_bookmark_scripts() {
	if(!is_admin()) {
		wp_enqueue_script(
			'px-scripts-functions',
			get_stylesheet_directory_uri() . '/_inc/js/bookmarks.js',
			array('jquery'),
			'1.0',
			true
		);
	}
}
add_action('wp_enqueue_scripts','px_bookmark_scripts');

wp_enqueue_script accepts 5 parameters.

1. Handle – Give your script a name.
2. Source – Path to your script.
3. Dependencies – Which scripts will your script need to function.
4. Version – Version number of your script.
5. In footer – If false your script will be loaded with wp_head. If set to true it will load with wp_footer.

Browsers of our site will be able to add or remove a WordPress post to their bookmarks by clicking an anchor which reads “Add to bookmarks” or “Remove from bookmarks” located to the bottom of each post.

When either anchor is clicked we will use AJAX and make a request to a PHP script. Once executed we will update the sidebar widget.

Should the browser be logged in as a member of the site they can then save any “Lists of bookmarks” which are currently stored within the session and displayed in the widget.

functions.php…

function px_bookmark_link() {
	global $post;
	if(@in_array($post->ID, $_SESSION['bookmarks'])) :
		$content .= '<a href="'.get_permalink().'" class="delete-bookmark" data-post-id="'.$post->ID.'" data-post-name="'.get_the_title().'">Remove from bookmarks</a>';
	else :
		$content .= '<a href="'.get_permalink().'" class="add-bookmark" data-post-id="'.$post->ID.'" data-post-name="'.get_the_title().'">Add to bookmarks</a>';
	endif;
	return $content;
}
add_filter('the_tags', 'px_bookmark_link');

This function is called at each iteration of “the loop” by utilising add_filter and the_tags as our hook.

We let WordPress know that within this function we want access to items within $wp_query and consequently $post. This will allow us to retrieve the_id, the_title and the_permalink.

Some logic is applied when this code executes to determine which link to show. If the user already has the item within their current session we will show a “Remove from bookmarks” anchor and vice versa. in_array() allows us to check this.

in_array() will flag notices if error_reporting has that directive, we use the @ symbol to suppress these notices (hacky).

Using the data returned in $post we form two anchors for adding and removing bookmarks (all data attributes important here) to be later used with our AJAX calls in bookmarks.js.

For a full reference of available filters visit the codex.

Step 3 Widget – Proof of Concept

Now we have our link in place let’s create the widget which will appear in the sidebar at all times and will be populated or emptied on demand.

The image above reflects the final states of the widget in 3 scenarios.

1. No bookmarks whilst being logged in or logged out.
2. Bookmarks currently saved in session whilst not logged in.
3. Bookmarks currently saved in session whilst being logged in.

The next block of code is placed within widget.php and nested within HTML markup.

if($_SESSION['bookmarks']) :
	foreach($_SESSION['bookmarks'] as $key => $value) :
		$keys[] = $key;
		$start_count = min($keys);
	endforeach;
endif;
for($i = $start_count; $i < $start_count + count($_SESSION['bookmarks']); $i++) :
	if($_SESSION['bookmarks'][$i]) :
		$bookmark = get_post($_SESSION['bookmarks'][$i]);
		echo '<li id="bookmark-'.$bookmark->ID.'">';
		echo '<a href="'.$bookmark->post_name.'">'.$bookmark->post_title.'</a>';
		echo '</li>';
	endif;
endfor;

When building this project there was a problem with session data that kept cropping up upon output. Some values were being removed but the key was persisting. Setting a $start_count later to be used when printing the session data solved this problem.

The important thing to note here is how to retrieve items from $_SESSION['bookmarks'] which will be created in the next stage.

At each iteration we use get_post() to query the WordPress database with the stored integer values in $_SESSION['bookmarks']. Which will return all the human readable data we need.

if(is_user_logged_in()) :
	// Show SAVE button
else :
	// Show "LOGIN TO SAVE" message.
endif;
if($_SESSION['bookmarks']) :
	// Show CLEAR button
endif;

This final piece of logic within widget.php determines which buttons and text to show alongside the widget depending on the state of the current session and
also if the user is logged in or out.

Step 4 Adding Bookmarks via AJAX

jQuery is awesome, here we’ll use the delegate method and listen for clicks on our important anchors. We’ll check for the following items being clicked.

• Anchors with a class of add-bookmark
• Anchors with a class of delete-bookmark
• Anchors with a class of clear-bookmarks

Using hasClass we can test which item has been clicked within the delegate method and serve the desired AJAX call.

Should you be building this into a larger project please consider using a pubsub pattern.

var $bookmark_widget = $('#px-bookmarks'),
	$bookmark_form = $('#px-bookmarks form'),
	$bookmark_widget_list = $('#px-bookmarks .current-bookmarks'),
	$empty_widget = $('#px-bookmarks p'),
	$widget_buttons = $('#px-bookmarks .widget-buttons'),
	$login_notify = $('#px-bookmarks .login-notify'),
	// This should be changed to reflect your domain.
	$ajax_path = 'http://yoursite.com/wp-content/themes/bookmark-theme/members/single/bookmarks/ajax.php';

First log some variables so we are not “splashing around in the DOM” too much. All DOM selectors above are located within widget.php.

$(".add-bookmark, .delete-bookmark, .clear-bookmarks").delegate(this, 'click', function(e) {
	e.preventDefault();
});

We tell jQuery to listen for click on all of the listed classes and via the callback function we will then tell it what to do. The next portions of code to be added will be placed directly after e.preventDefault().

Using preventDefault() is a smarter way of nullifying the default action when JavaScript is present. Here is some discussion surrounding preventDefault() on Stack Overflow.

The next portions of code to be added will be placed directly after e.preventDefault().

var $post_id   = $(this).data('post-id'),
	$post_name = $(this).data('post-name'),
	$post_href = $(this).attr('href'),
	$that 	   = $(this);

Once a user has clicked any of the “important anchors” we need to store the data attribute values which were attached to anchors in Step 2. This will allow us to send and retrieve the data we want.

The next code can become a little verbose as we will be showing and hiding elements based on which item has been clicked, with that pre-cursor the code below is the
bare minimum which will function without aesthetics in mind. However please do download the source and look to these lines.

if($that.hasClass('add-bookmark')) {
	$.ajax({
		url: $ajax_path + '?method=add',
		type: 'GET',
		data: 'post_id=' + $post_id,
		success: function(returndata) {
			if($bookmark_widget_list.children().length === 0) {
				// Show / hide
			}
			$bookmark_widget_list.prepend('<li id="bookmark-'+ $post_id +'">
				<a href="'+ $post_href +'">' + $post_name + '</a></li>');
		}
	});
}

Here we use hasClass to distinguish which item was clicked by using jQuery to search against our clicked item.

Based on the outcome we setup our AJAX call a little bit differently each time. With the url and data being requested and sent each time changing slightly.

Notice ?method=add appended to $ajax_path. This is the equivalent of http://site.com/path/to/ajax.php?method=add.

When adding a bookmark to the current session the only item we need to pass to our PHP code is the id of that post which was stored into the $post_id variable.

When jQuery receives a successful response we then append that item to the current bookmark list within the widget area as a list item. Using $post_id, $post_name and $post_href here.

When the page is refreshed the code added to widget.php in step 3 will kick in.

On line 7 of the last snippet there is a small subroutine within the success method which determines if there are any list items present within the widget area. This is the previously-mentioned-slightly-verbose code which does nothing more than show and hide some DOM elements. It has been removed for readability here on Wptuts+. Moving on…

if($that.hasClass('delete-bookmark')) {
	$.ajax({
		url: $ajax_path + '?method=delete',
		type: 'GET',
		data: 'post_id=' + $post_id,
		success: function(returndata) {
			if($bookmark_widget_list.children().length <= 1) {
				// Show / hide
			}
			$('#bookmark-'+ $post_id).remove();
		}
	});
}

Much like if($that.hasClass('add-bookmark')) here we check for items clicked that have the class of delete-bookmark.

Once this subroutine has been entered the url in the AJAX call is altered slightly by sending over a different query string. Namely ?method=delete.

When a successful response is returned we remove that list item from the current bookmarks stored within the widget.

Applying some logic in the same fashion as the add-bookmark subroutine to determine if the item removed is going to be the final item. Based on this outcome here DOM elements are again shown or hidden.

if($that.hasClass('clear-bookmarks')) {
	$.ajax({
		url: $ajax_path + '?method=clear',
		success: function(returndata) {
			// Show / hide

			$('.postmetadata .delete-bookmark').each(function(index) {
				// Bookmark list cleared, set anchors attached to posts to default.
				$(this).removeClass().addClass('add-bookmark').html('Add to bookmarks');
			});
		}
	});
}

The final code snippet here is used to clear all bookmarks within the widget by setting the url query string to a different method and resetting any anchors on the page to the default "Add to bookmarks" to reflect an empty $_SESSION. This is done by utilising jQuery's each method to find all occurrences of the class delete-bookmark (anchor attached to posts using add_filter) and switching it back to the default
add-bookmark.

Step 5 PHP Requested via AJAX

Now we will create the PHP code referenced in the AJAX calls above which will be used to add, delete and clear all bookmarks from the session.

Within ajax.php we will create the following 3 functions.

• add_bookmark()
• delete_bookmark()
• clear_bookmarks()

Let's first create add_bookmark()

function add_bookmark() {
	$post_id = $_GET['post_id'];
	if(@!in_array($post_id, $_SESSION['bookmarks'])) :
		$_SESSION['bookmarks'][] = $post_id;
	endif;
}

First we store the $post_id previously passed over in bookmarks.js via data: 'post_id=' + $post_id.

Next we use the in_array function again to determine if this item should be added to the bookmarks session.

function delete_bookmark() {
	$post_id = $_GET['post_id'];

	foreach($_SESSION['bookmarks'] as $key => $value) :
		$keys[] = $key;
	endforeach;
	$start_count = min($keys);

	if(@in_array($post_id, $_SESSION['bookmarks'])) :
		for($i = $start_count; $i < $start_count + count($_SESSION['bookmarks']); $i++) :
			if($_SESSION['bookmarks'][$i] === $post_id) :
				unset($_SESSION['bookmarks'][$i]);
			endif;
		endfor;
	endif;
}

Within the delete_bookmark() function we again store the $post_id.

Using the same technique to output our bookmarks in widget.php a $start_count is established.

Next we determine if the item passed ($post_id) exists within the bookmarks session via in_array, and unset any values that are matched.

function clear_bookmark() {
	session_start();
	session_unset();
	session_destroy();
}

Finally the clear_bookmark() function destroys all session data.

We will need one more piece of code for this file to be complete. Head to the top of the file and add the following.

session_start();

$method = $_GET['method'];

switch($method) {
	case "add" :
		add_bookmark();
	break;
	case "delete" :
		delete_bookmark();
	break;
	case "clear" :
		clear_bookmark();
	break;
}

We use session_start() to resume the current session. This is crucial here.

Next we store the method which is sent over with url in our $.ajax calls.

Based on the current value of $method we call the appropriate function.

Step 6 Bookmarks on Members Profiles

The files we will be dealing with for the remainder of this tutorial are listed below.

• members/single/home.php – This file is a modified version of bp-default/members/single/home.php.
• members/single/bookmarks/loop.php – Used to retrieve any previously saved member bookmark lists.
• members/single/bookmarks/remove.php – Used to delete any saved bookmark lists.
• members/single/bookmarks/save.php – Used to save any bookmark lists stored within the current session.
• members/single/bookmarks/view.php – Used as a makeshift template loader.

Inside home.php we will add a list item to the unordered list within the div with an id of item-nav.

Using the $bp global we can quickly form the URL required.

global $bp;
echo '<li><a href="'.$bp->displayed_user->domain.'?component=bookmarks">Bookmarks</a></li>';

This is one of smaller sins we make along the road to demonstrate proof of concept. However to re-iterate proof-of-concept and speedy development is the important factor here.

Should we decide to expand this feature more we would look to using BuddyPress hooks.

if($_GET['component'] == 'bookmarks') :
	locate_template(array('members/single/bookmarks/view.php'), true);

Still within home.php we check against the query string which will allow us to serve custom templates.

if(!$_GET['action']) :
	locate_template(array( 'members/single/bookmarks/loop.php'), true);
elseif($_GET['action'] == 'save' && is_user_logged_in() && bp_is_home()) :
	locate_template(array( 'members/single/bookmarks/save.php'), true);
elseif($_GET['action'] == 'remove' && is_user_logged_in() && bp_is_home()) :
	locate_template(array( 'members/single/bookmarks/remove.php'  ), true);
endif;

Within view.php (our make-shift template loader) we check for 2 actions and if none has been defined we show the list of saved bookmarks.

Back in step 3 some logic was added to determine which anchors to show within the widget based on the current state of $_SESSION['bookmarks'] and whether or not the user was logged in.

Let's create a small table in the database which will be used to store a list of bookmarks which correspond to each member.

DROP TABLE IF EXISTS `bookmarks`;
CREATE TABLE `bookmarks` (
	`id` int(11) NOT NULL AUTO_INCREMENT,
	`user_id` int(11) NOT NULL,
	`created` date NOT NULL,
	`post_ids` text NOT NULL,
	`list_name` text NOT NULL,
	PRIMARY KEY (`id`)
)

The MySQL above will create a new table with 5 fields for us to store bookmark data.

Once created it's time to move into save.php.

Whilst the user is accessing save.php we will present a form with a text input, here the user will be required to give a label to the list of bookmarks he or she would like to save.

Once a label has been provided we will store each bookmark list as a row within the database (for later retrieval) and clear the current session.

if(!$_POST['px-bookmark-list-name']) :
	// Present form asking to give list a name
	// Stage 1
elseif($_POST['px-bookmark-list-name']) :
	// Label supplied store to database.
	// Stage 2
endif;

Now within stage 1 of save.php...

// If form submitted but no label supplied present error.
if($_POST['submit'] && !isset($_POST['px-bookmark-list-name'])) :
	echo '<p class="error">A label is required.</p>';
endif;

// Establish the start counter
if($_SESSION['bookmarks']) :
	foreach($_SESSION['bookmarks'] as $key => $value) :
		$keys[] = $key;
	endforeach;
	$start_count = min($keys);
endif;

// Loop over items and store in hidden form fields.
for($i = $start_count; $i < $start_count + count($_SESSION['bookmarks']); $i++) :
	if($_SESSION['bookmarks'][$i] !== NULL) :
		$bookmark = get_post($_SESSION['bookmarks'][$i]);
		echo '<input type="hidden" name="px-post-url[]" value="'.$bookmark->post_name.'" />';
		echo '<input type="hidden" name="px-post-name[]" value="'.$bookmark->post_title.'" />';
		echo '<input type="hidden" name="px-post-id[]" value="'.$bookmark->ID.'" />';
		echo '<input type="submit" name="submit" value="Save List">';
	endif;
endfor;

First we display an error if no label has been supplied.

Next we use the same technique from widget.php and ajax.php to establish a start counter and iterate over the session data.

Finally we output some form fields with the help of get_post.

global $bp;

foreach($_POST['px-post-id'] as $value) :
	$posts_to_save[] = $value;
endforeach;

$posts = serialize($posts_to_save);

During stage 2 of save.php we gain access to the $bp global.

We loop over the $_POST data and store posts to be saved as an array. This is then serialized and stored into the $posts variable.

$list_name = $_POST['px-bookmark-list-name'];

$query = $wpdb->insert(
	'bookmarks',
	array(
		'user_id'		=> $bp->loggedin_user->id,
		'created'		=> current_time('mysql'),
		'post_ids'		=> $posts,
		'list_name'		=> $list_name
	),
	array(
		'%d',			// user_id
		'%s',			// created
		'%s',			// post_ids
		'%s'			// list_name
	)
);

Next we store the label supplied by the user for this bookmark list into a variable and utilise WPDB to insert the row to the database.

if($query) :
	echo '<div id="message" class="updated">';
	echo '<p>List saved.</p>';
	echo '</div>';

	session_start();
	session_unset();
	session_destroy();
else :
	echo '<div id="message" class="error">';
	echo '<p>There was an error.</p>';
	echo '</div>';
endif;

Finally we check if the query was successful and unset session data, otherwise display an error.

Step 7 Retrieving and Deleting Bookmarks

Remember, in view.php when no particular action is set we will load loop.php. In this file $wpdb will be used to retrieve and output any bookmarks lists.

global $bp;
$displayed_user = $bp->displayed_user->id;
$bookmark_lists = $wpdb->get_results( "SELECT * FROM bookmarks WHERE user_id = $displayed_user ORDER BY id DESC");

Using the $bp global the id of the profile being displayed is stored into the $displayed_user variable.

Next we perform a query against the bookmarks table with the stored $displayed_user as a where condition.

if($bookmark_lists) :
	foreach($bookmark_lists as $bookmark_list) :
		echo $bookmark_list->list_name;
		$post_ids = unserialize($bookmark_list->post_ids);
		foreach($post_ids as $post_id) :
			$bookmark = get_post($post_id);
			echo '<a href="http://yoursite.com/'.$bookmark->post_name.'" title="View bookmark">'.$bookmark->post_title.'</a>';
		endforeach;
	endforeach;
endif;

When results are returned they are displayed by looping over the data and outputting accordingly. Here we make use of unserialize to reverse the effects of
serialize which was used to store bookmarks previously.

We can make one more addition to the previous block of code.

if(is_user_logged_in() && bp_is_home()) :
	echo '<a href="'.$bp->displayed_user->domain.'?component=bookmarks&action=remove&id='.$bookmark_list->id.'" class="delete-list">Delete list</a>';
endif;

This will add an anchor to the title of each list which when clicked will pass a new action of remove along with the bookmark list id.

Which leads us to our final stage... Deleting a bookmark list. Open up remove.php and let's finish this off.

if(isset($_GET['action']) == 'remove' && isset($_GET['id'])) :
	$list_id = $_GET['id'];
	global $bp;
	$user_id = $bp->loggedin_user->id;
	$query = $wpdb->query("DELETE FROM bookmarks WHERE id = $list_id AND user_id = $user_id");

	if($query) :
		echo '<div id="message" class="updated">';
		echo '<p>List deleted.</p>';
		echo '</div>';
	else :
		echo '<div id="message" class="error">';
		echo '<p>There was an error.</p>';
		echo '</div>';
	endif;
endif;

First we make sure the action is set to remove and there is an id to build a small query with.

Next we store some user data and run the query. Users should only be able to delete lists that belong to them, using $bp->loggedin_user->id helps us achieve this.

Finally we serve a message depending on the outcome.

Conclusion

Over the course of this tutorial a number of techniques have been applied. Using jQuery, raw PHP, WordPress conventions and BuddyPress we have been able to illustrate a nice feature to be added to your social network site powered by WordPress and BuddyPress.

Out of the box BuddyPress does not come with a bookmarks manager attached to member profiles and there isn't a plugin out there that functions exactly like this.

A bookmarks manager is one example but this could be anything.

The main goal of this tutorial was to illustrate how quickly and effectively you can hi-jack BuddyPress to demonstrate proof of concept.

With some know-how this could be put together in an evening with little trouble at all. The time commitment is tangible and could be factored into a monthly maintenance contract.

However if a client desired more features from the bookmarks manager such as a dashboard widget and more in-depth features you would be stepping into the realms of a plugin.

Data has not been sanitised in this tutorial so please make sure if you are to place this into a "real world" environment, go through a little bit of validation before-hand.

I hope you have enjoyed this tutorial and any discrepancies you may find please do leave a comment and will do my best to help you through it.

Since there seem to be various interpretations of what the terms ‘validation’, ‘escaping’ and ‘sanitization’ mean, I’ll first clarify what I mean by them in this article:

• Validation – These are the checks that are run to ensure the data you have is what it should be. For instance, that an e-mail looks like an e-mail address, that a date is a date and that a number is (or is cast as) an integer
• Sanitization / Escaping – These are the filters that are applied to data to make it ‘safe’ in a specific context. For instance, to display HTML code in a text area it would be necessary to replace all the HTML tags by their entity equivalents

Why Is Sanitization Important?

When data is included in some context (say in a HTML document) – that data could be misinterpreted as a code for that environment (for example HTML code). If that data contains malicious code, then using that data without sanitizing it, means that code will be executed. The code doesn’t even necessarily have to be malicious for it to cause undesired effects. The job of sanitization is to make sure that any code in the data isn’t interpreted as code – otherwise you may end up like Bobby Tables’ school…

‘Exploits of a Mom’ – xkcd

A seemingly innocuous example might be pre-filling a search field with the currently queried term, using the unescaped $_GET['s']:

<form method="get" id="searchform" action="<?php echo esc_url( home_url( '/' ) ); ?>">
	<input type="text" class="field" name="s" id="s" value="<?php echo $_GET['s']; ?>"/>
	<input type="submit" class="submit" name="submit" id="searchsubmit" value="Search" />
</form>

This opens up a vulnerability that could allow javascript to be injected by, for instance, tricking someone into visiting http://yoursite.com?s="/><script>alert('Injected javascript')</script>. The search term ‘jumps’ out of the value attribute, and the following part of the data is interpreted as code and executed. To prevent this, WordPress provides get_search_query which returns the sanitized search query. Although this is a ‘harmless’ example the injected script could be far more malicious and at best it would just ‘break’ the form if search terms contain double quotes.

How this malicious (or otherwise) code may have found its way onto your site is not the concern here – but rather it is to prevent it from executing. Nor do we make assumptions about the nature of this unwanted code, or its intent – it could have simply been an error on the user’s part. This brings me to rule No.1…

Rule No. 1: Trust Nobody

It’s a common maxim that is used with regards to data sanitization, and it’s a good one. The idea is that you should not assume that any data entered by the user is safe. Nor should you assume that the data you’ve retrieved from the database is safe – even if you had made it ‘safe’ prior to inserting it there. In fact, whether data can be considered ‘safe’ makes no sense without context. Sometimes the same data may be used in multiple contexts on the same page. Titles for instance, can safely contain quotes or double quotes when inside header tags – but will cause problems if used (unescaped) inside a title attribute of a link tag. So it is rather pointless to make data ‘safe’ when adding it to the database, since it is often impossible to make data safe for all contexts simultaneously. (Of course it needs to be made safe to add to the database – but we’ll come to that later).

Even if you only intend to use that data in one specific context, say a form, it is still pointless to sanitize the data when writing to the database because, as per Rule No. 1, you cannot trust that it is still safe when you take it out again.

Rule No. 2: Validate on Input, Escape on Output

This is the procedural maxim that sets out when you should validate data, and when you sanitize it. Simply put – validate your data (check it’s what it should be – and that it’s ‘valid’) as soon as you receive it from the user. When you come to use this data, for example when you output it, you need to escape (or sanitize) it. What form this sanitization takes, depends entirely on the context you are using it in.

The best advice is to perform this ‘late’: escape your data immediately before you use or display it. This way you can be confident that your data has been properly sanitized and you don’t need to remember if the data has been previously checked.

Rule No. 3: Trust WordPress

You might be thinking “Ok, validate before writing to database and sanitize when using it. But don’t I need to make sure the data is safe to write to the database?”. In general, yes. When adding data to a database, or simply using an input to interact with a database, you would need to escape the data incase it contained any SQL commands. But this brings me to Rule No. 3, one which flies in the face of Rule No. 1: Trust WordPress.

In a previous article, I took user input (sent from a search form via AJAX) and used it directly with get_posts() to return posts that matched that search query:

	$posts = get_posts( array(
		's'=>$_REQUEST['term']
	) );

An observant reader noticed that I hadn’t performed any sanitization – and they were right. But I didn’t need to. When you use high-level functions such as get_posts(), you don’t need to worry about sanitizing the data – because the database queries are all properly escaped by WordPress’ internals. It’s a different matter entirely if you are using a direct SQL query – but we’ll look at this in a later section. Similarly, functions like the_title(), the_permalink(), the_content() etc. perform their own sanitization (for the appropriate context).

Data Validation

When you receive data entered by a user it’s important to validate it. (The settings API, covered in this series, allows you to specify a callback function to do exactly this). Invalid data is either auto-corrected, or the process is aborted and the user is returned to the form to try again (hopefully with an appropriate error message). The concern here is not safety but rather validity – if you’re doing it right, WordPress will take care of safely adding the data to the database. What ‘valid’ means is up to you – it could mean a valid email address, a positive integer, text of a limited length, or one of an array of specified options. However you aim to determine validity, WordPress offers a lot of functions that can help.

Numbers

When expecting numeric data, it’s possible to check if the data ‘is some form of number’, for instance is_int or is_float. Usually, it’s sufficient to simply cast the data as numeric with: intval or floatval.

If you need to ensure the number is padded with leading zeros, WordPress provides the function zeroise(). Which takes the following parameters:

• Number – the number to pad
• Threshold – the number of digits the number will be padded to

For example:

echo zeroise(70,4); // Prints 0070

E-mails

To check the validity of e-mails, WordPress has the is_email() function. This function uses simple checks to validate the address. For instance, it checks that it contains the ‘@’ symbol, that it’s longer than 3 characters, the domain contains only alpha-numerics and hyphens, and so forth. Obviously, it doesn’t check that the e-mail address actually exists. Assuming the e-mail address passed the checks, it is returned, otherwise ‘false’ is returned.

	$email = is_email('someone@e^ample.com');
	// $email is set to false.

	$email = is_email('someone@example.com');
	// $email is set to 'someone@example.com'.

HTML

Often you may wish to allow only some HTML tags in your data – for instance in comments posted on your site. WordPress provides a family of functions of the form wp_kses_* (KSES Strips Evil Scripts). These functions remove (some subset of) HTML tags, and can be used to ensure that links in the data are of specified protocols. For example the wp_kses() function accepts three arguments:

• content – (string) Content to filter through kses
• allowed_html – An array where each key is an allowed HTML element and the value is an array of allowed attributes for that element
• allowed_protocols – Optional. Allowed protocol in links (for example http, mailto, feed etc.)

wp_kses() is a very flexible function, allowing you to remove unwanted tags, or just unwanted attributes from tags. For example, to only allow <strong> or <a> tags (but only allow the href attribute):

$content = "<em>Click</em> <a title='click for wp.tuts+' href='http://wp.tutsplus.com'>here</a> to visit <strong> wptuts+ </strong>";

echo wp_kses( $content, array(
	'strong' => array(),
	'a' => array('href')
) );

// Prints the HTML "Click <a href='http://wp.tutsplus.com'>here</a> to visit <strong> wptuts+ </strong>":
Click here to visit  wptuts+ 

Of course, specifying every allowed tag and every allowed attribute can be a laborious task. So WordPress provides other functions that allow you to use wp_kses with pre-set allowed tags and protocols – namely the ones used for validating posts and comments:

• wp_kses_post()
• wp_kses_data()

The above functions are helpful in ensuring that HTML received from the user only contains whitelisted elements. Once we’ve done that we would also like to ensure that each tag is balanced, that is every opening tag has its corresponding closing tag. For this we can use balanceTags(). This function accepts two arguments:

• content – Content to filter and balance tags of
• force balance – True or false, whether to force the balancing of tags

// Content with missing closing </strong> tag
$content = "<em>Click</em> <a href='http://wp.tutsplus.com'>here</a> to visit <strong> wptuts+";

echo balanceTags($content,true),

// Prints the HTML "Click <a href='http://wp.tutsplus.com'>here</a> to visit <strong> wptuts+ </strong>"

Filenames

If you want to create a file in one of your website’s directories, you will want to ensure the filename is both valid and legal. You would also want to ensure that the filename is unique for that directory. For this WordPress provides:

• sanitize_file_name( $filename ) – sanitizes (or validates) the file-name by removing characters that are illegal in filenames on certain operating systems or that would require escaping at the command line. Replaces spaces with dashes and consecutive dashes with a single dash and removes periods, dashes and underscores from the beginning and end of the filename.
• wp_unique_filename( $dir, $filename ) – returns a unique (for directory $dir), sanitized filename (it uses sanitize_file_name).

Data From Text Fields

When receiving data inputted into a text field, you’ll probably want to strip out extra white spaces, tabs and line breaks, as well as stripping out any tags. For this WordPress provides sanitize_text_field().

Keys

WordPress also provides sanitize_key. This is a very generic (and occasionally useful) function. It simply ensures the returned variable contains only lower-case alpha-numerics, dashes, and underscores.

Data Sanitization

Whereas validation is concerned with making sure data is valid – data sanitization is about making it safe. While some of the validation functions referred to above might be useful in making sure data is safe – in general, it is not sufficient. Even ‘valid’ data might be unsafe in certain contexts.

Rule No. 4: Making Data Safe Is About Context

Simply put you cannot ask “How do I make this data safe?”. Instead you should ask, “How do I make this data safe for using it in X”.

To illustrate this point, suppose you have a widget with a textarea where you intend to allow the user to enter some HTML. Suppose they then enter:

<textarea name="my-textarea"></textarea> Hello World

This is perfectly valid, and safe, HTML – however when you click save, we find that the text has jumped out of the textarea. The HTML code is not safe as a value for the textarea:

What is safe to use in one context, is not necessarily safe in another. Whenever you use or display data you must keep in mind what forms of sanitization need to be done in order to make using that data safe. This is why WordPress often provides several functions for the same content, for instance:

• the_title – for using the title in standard HTML (inside header tags, for example)
• the_title_attribute – for using the title as an attribute value (usually the title attribute in <a> tags)
• the_title_rss – for using the title in RSS feeds

These all perform the necessary sanitization for a particular context – and if you’re using them you should be sure to use the correct one. Sometimes though, we’ll need to perform our own sanitization – often because we have custom input beyond the standard post title, permalink, content etc. that WordPress handles for us.

Escaping HTML

When printing variables to the page we need to be mindful of how the browser will interpret them. Let’s consider the following example:

<h1> <?php echo $title; ?> </h1>

Suppose $title = <script>alert('Injected javascript')</script>. Rather than displaying the HTML <script> tags, they will be interpreted as HTML and the enclosed javascript would be injected into the page.

This form of injection (as also demonstrated in the search form example) is called Cross-site scripting and this benign example belies its severity. Injected script can essentially control the browser and ‘act on behalf’ of the user or steal the user’s cookies. This becomes an even more serious issue if the user is logged in. To prevent variables printed inside HTML being interpreted as HTML, WordPress provides the well known esc_html function. In this example:

<h1> <?php echo esc_html($title); ?> </h1>

Escaping Attributes

Now consider the following example:

<?php $value = 'my-value" onfocus="alert(\"Injected javascript\")"'; ?>
<input type="text" name="myInput" value="<?php echo $value;?>"/>

Because $value contains double quotes, unescaped it can jump out of the value attribute and inject script, for example, by using the onfocus attribute. To escape unsafe characters (such as quotes, and double-quotes in this case), WordPress provides the function esc_attr. Like esc_html it replaces ‘unsafe’ characters by their entity equivalents. In fact, at the time of writing, these functions are identical – but you should still use the one that is appropriate for the context.

For this example we should have:

<?php $value = 'my-value" onfocus="alert(\"Injected javascript\")"'; ?>
<input type="text" name="myInput" value="<?php echo esc_attr($value);?>"/>

Both esc_html and esc_attr also come with __, _e, and _x variants.

• esc_html__('Text to translate', 'plugin-domain') / esc_attr__ – returns the escaped translated text,
• esc_html_e('Text to translate', 'plugin-domain') / esc_attr_e – displays the escaped translated text and finally the
• esc_html_x('Text to translate', $context, 'plugin-domain') / esc_attr_x – translates the text according to the passed context, and then returns the escaped translation

HTML Class Names

For class names, WordPress provides sanitize_html_class – this escapes variables for use in class names, simply by restricting the returned value to alpha-numerics, hyphens and underscores. Note: It does not ensure the class name is valid (reference: http://www.w3.org/TR/CSS21/syndata.html#value-def-identifier).

In CSS, identifiers can contain only the characters [a-zA-Z0-9] and ISO 10646 characters U+00A0 and higher, plus the hyphen (-) and the underscore (_); they cannot start with a digit, two hyphens, or a hyphen followed by a digit. Identifiers can also contain escaped characters and any ISO 10646 character as a numeric code.

Escaping URLs

Let’s now look at another common practise, printing variables into the href attribute:

<a href="<?php echo $url;?>" title="Link Title"> Link Text </a>

Clearly it is vulnerable to the same form of attack as illustrated in escaping HTML and attributes. But what if the $url was set as follows:

$url = 'javascript:alert(\'Injected javascript\')'

On clicking the link, the alert function would be fired. This contains no HTML, or any quotes that allow it to jump out of the href attribute – so esc_attr is not sufficient here. This is why context matters: esc_attr($url) would be safe in the title attribute, but not for the href attribute – and this is because of the javascript protocol – which while perfectly valid – is not to be considered safe in this context. Instead you should use:

• esc_url – for escaping URLs that will be printed to the page.
• esc_url_raw – for escaping URLs to save to the database or use in URL redirecting.

esc_url strips out various offending characters, and replaces quotes and ampersands with their entity equivalents. It then checks that the protocol being used is allowed (javascript, by default, isn’t).

What esc_url_raw does is almost identical to esc_url, but it does not replace ampersands and single quotes (which you don’t want to, when using the URL as an URL, rather than displaying it).

In this example, we are displaying the URL, so we use esc_url:

<a href="<?php echo esc_url($url);?>" title="Link Title"> Link Text </a>

Although not necessary in most cases, both functions accept an optional array to specify which protocols (such as http, https, ftp, ftps, mailto, etc) you wish to allow.

Escaping JavaScript

Sometimes you’ll want to print javascript variables to a page (usually in the head):

<script>
var myVar = '<?php echo $variable; ?>';
</script>

In fact, if you are doing this, you should almost certainly be using wp_localize_script() – which handles sanitization for you. (If anyone can think of a reason why you might need to use the above method instead, I would like to hear it).

However, to make the above example safe, you can use the esc_js function:

<script>
var myVar = '<?php echo esc_js($variable); ?>';
</script>

Escaping Textarea

When displaying content in a textarea, esc_html is not sufficient because it does not double encode entities. For example:

<?php $var = '<strong>text</strong> &lt;b&gt;bold&lt;/b&gt;' ?>
<textarea><?php echo esc_html($var); ?> </textarea>

$var printed in the textarea will appear as:

<strong>text</strong> <b>bold</b>

Rather than also encoding the & as & in the <b> tags.

For this WordPress provides esc_textarea, which is almost identical to esc_html, but does double encode entities. Essentially it is little more than a wrapper for htmlspecialchars. In this example:

<?php $var = '<strong>text</strong> &lt;b&gt;bold&lt;/b&gt;' ?>
<textarea><?php echo esc_textarea($var); ?> </textarea>

Antispambot

Displaying e-mail addresses on your website leaves them prone to e-mail harvesters. One simple method is to disguise the e-mail address. WordPress provides antispambot, which encodes random parts of the e-mail address into their HTML entities (and hexadecimal equivalents if $mailto = 1). On each page load the encoding should be different and while the returned address renders correctly in the browser, it should appear as gobbledygook to the spambots. The function accepts two arguments:

• e-mail – the address to obfuscate
• mailto – 1 or 0 (1 if using the mailto protocol in a link tag)

$email = "joebloggs@example.com";
$email = sanitize_email($email);
echo '<a href="mailto:'.antispambot($email,1).'" title="Click to e-mail me" >'.antispambot($email).' </a>';

Query Strings

If you wish to add (or remove) variables from a query string (this is very useful if you wish to allow users to select an order for your posts), the safest and easiest way is to use add_query_arg and remove_query_arg. These functions handle all the necessary escaping for for the arguments and their values for use in the URL.

add_query_arg accepts two arguments:

• query parameters – an associative array of parameters -> values
• url – the URL to add the parameters and their values to. If omitted, the URL of the current page is used

remove_query_arg also accepts two arguments, the first is an array of parameters to remove, the second is as above.

// If we are at www.example.com/wp-admin/edit.php?post_type=book
$query_params = array ('page' => 'my-bage');
$url = add_query_arg( $query_params );

// Would set $url to be:
// www.example.com/wp-admin/edit.php?post_type=book&page=my-page

Validation & Sanitization

As previously mentioned, sanitization doesn’t make much sense without a context – so it’s pretty pointless to sanitize data when writing to the database. Often, you need to store data in its raw format anyway, and in any case – Rule No. 1 dictates that we should always sanitize on output.

Validation of data, on the other hand, should be done as soon as it’s received and before it’s written to the database. The idea is that ‘invalid’ data should either be auto-corrected, or be flagged to the data, and only valid data should be given to the database.

That said – you may want to also perform validation when data is displayed too. In fact sometimes, ‘validation’ will also ensure the data is safe. But the priority here is on safety and you should avoid excessive validation that would run on every page load (the wp_kses_* functions, for instance, are very expensive to perform).

Database Escaping

When using functions such as get_posts or classes such as WP_Query and WP_User_Query, WordPress takes care of the necessary sanitization in querying the database. However, when retrieving data from a custom table, or otherwise performing a direct SQL query on the database – proper sanitization is then up to you. WordPress, however, provides a helpful class, the $wpdb class, that helps with escaping SQL queries.

Let’s consider this basic ‘SELECT‘ command, where $age and $firstname are variables storing an age and name that we are querying:

SELECT * WHERE age='$age' AND firstname = '$firstname'

We have not escaped these variables, so potentially further commands could be injected in. Borrowing xkcd’s example from above:

$age = 14;
$firstname = "Robert'; DROP TABLE Students;";
$sql = "SELECT * WHERE age='$age' AND firstname = '$firstname';";
$results = $wpdb->query

Will run as the command(s):

SELECT * WHERE age='14' AND firstname = 'Robert'; DROP TABLE Students;';

And delete our entire Students table.

To prevent this, we can use the $wpdb->prepare method. This accepts two parameters:

• The SQL command as a string, where string variables are replaced by the placeholder %s and decimal numbers are replaced by the placeholder %d and floats by %f
• An array of values for the above placeholders, in the order they appear in the query

In this example:

$age = 14;
$firstname = "Robert'; DROP TABLE Students;";
$sql = $wpdb->prepare('SELECT * WHERE age=%d AND firstname = %s;',array($age,$firstname));
$results = $wpdb->get_results($sql);

The escaped SQL query ($sql in this example) can then be used with one of the methods:

• $wpdb->get_row($sql)
• $wpdb->get_var($sql)
• $wpdb->get_results($sql)
• $wpdb->get_col($sql)
• $wpdb->query($sql)

Inserting and Updating Data

For inserting or updating data, WordPress makes life even easier by providing the $wpdb->insert() and $wpdb->update() methods.

The $wpdb->insert() method accepts three arguments:

• Table name – the name of the table
• Data – array of data to insert as column->value pairs
• Formats – array of formats for the corresponding values (‘%s‘,’%d‘ or’%f‘)

$age = 14;
$firstname = "Robert'; DROP TABLE Students;";
$wpdb->insert(
	'Students',
	array( 'firstname' => $firstname, 'age' => $age ),
	array( '%s', '%d' )
);

The $wpdb->update() method accepts five arguments:

• Table name – the name of the table
• Data – array of data to update as column->value pairs
• Where – array of data to match as column->value pairs
• Data Format – array of formats for the corresponding data values
• Where Format – array of formats for the corresponding ‘where’ values

// Update Robert'; DROP TABLE Students; to Bobby

$oldname = "Robert'; DROP TABLE Students;";
$newname = "Bobby";
$wpdb->update(
	'Students',
	array( 'firstname' => $newname ),
	array( 'firstname' => $oldname ),
	array( '%s' ),
	array( '%s' )
);

Both the $wpdb->insert() and the $wpdb->update() methods perform all the necessary sanitization for writing to the database.

Like Statements

Because the $wpdb->prepare method uses % to distinguish the place-holders, care needs to be taken when using the % wildcard in SQL LIKE-statements. The Codex suggests escaping them with a second %. Alternatively you can escape the term to be searched for with like_escape and then add the wildcard % where appropriate, before including this in the query using the prepare method. For instance:

$age=14;
$firstname = "Robert'; DROP TABLE Students;";
SELECT * WHERE age=$age (firstname LIKE '%$firstname%');

Would be made safe with:

$age=14;
$firstname = "Robert'; DROP TABLE Students;";
SELECT * WHERE age=$age AND (firstname LIKE '%$firstname%');
$query = $wpdb->prepare('SELECT * WHERE age=%d AND (firstname LIKE %s);', array($age, '%'.like_escape($firstname).'%') );

Summary

This isn’t an exhaustive list of the functions available for validation and sanitization, but it should cover the vast majority of use cases. A lot of these (and other) functions can be found in /wp-includes/formatting.php and I’d strongly recommend digging into the core code and having a look into how WordPress core does validation and sanitization of data.

Did you find this article useful? Do you have any further suggestions on best practices for data validation and sanitization in WordPress? Let us know in the comments below.

The Parameters

The function has several parameters to work with. Here are the defaults as listed in the WordPress.org Codex:

<?php $defaults = array(
	'theme_location'  => ,
	'menu'            => ,
	'container'       => 'div',
	'container_class' => 'menu-{menu slug}-container',
	'container_id'    => ,
	'menu_class'      => 'menu',
	'menu_id'         => ,
	'echo'            => true,
	'fallback_cb'     => 'wp_page_menu',
	'before'          => ,
	'after'           => ,
	'link_before'     => ,
	'link_after'      => ,
	'items_wrap'      => '<ul id=\"%1$s\" class=\"%2$s\">%3$s</ul>',
	'depth'           => 0,
	'walker'          =>
);
?>

<?php wp_nav_menu( $defaults ); ?>

Theme Location

Using this parameter, we can set a theme location which is then used on the Menus page to set a menu to work in that part of your theme, without having to manually define which menu should appear there. This is very helpful for theme distributors because you’re able to use conditionals to display a menu only if the user has defined a menu for that location. The only other requirement is that you use the function register_nav_menu() to register those locations. This is usually done from your function files when you’re setting up support for menus.

Let’s start building our custom menu function parameters assuming that we’ve registered a theme location called "primary".

$params = array(
	'theme_location' => 'primary'
);

Menu

This parameter is used to manually define which menu should be used. In our example, we are only setting a generic menu location and not defining an exact one to use, but if we were wanting to tell the function to use a menu called "Primary Navigation", our parameters would look like this:

$params = array(
	'theme_location' => 'primary',
	'menu' => 'Primary Navigation'
);

Container

By default, our menu will be wrapped in a div, but if you’re like me, you usually don’t need this and probably want to cut back on the amount of divs and other tags being used to keep your code as tidy as possible. You could also use this parameter to define a different tag such as an html5 <section> or <nav>. For our example, we don’t want a container to change the default container values since the Twenty Eleven theme styles rely on it being there.

Container Class and Container ID

As you can pretty much guess, these parameters are used to set a class and an ID to the container. Since we’re omitting this altogether, we have no need to define values.

Menu Class and Menu ID

These work just like the previous parameters except this time we definitely want to set an ID of "nav" because that is the ID we’ll use in our stylesheet to style the navigation bar.

$params = array(
	'theme_location' => 'primary',
	'container' => false,
	'menu_id' => 'nav'
);

Echo

You can use this parameter to tell whether you want to display (echo) the results, or return it for use in PHP. This item is boolean so to return it simply set this parameter to 0.

Fallback CB

This is a callback function that you can fallback to if no menu is found. By default it uses the old stand by wp_page_menu() and passes all of the same parameters to this function as well.

Before and After

These items are used to define what can be placed before and after the anchor tags (<a></a>). You could use these to precede each item with a vertical bar, or wrap the nav items in a span tag.

Link Before and Link After

These work the same as the previous items we covered except that whatever you define will be inside of the anchor tags. Our example doesn’t require that we use these so we’ll ignore them and let the default empty item be.

Items Wrap

By default, the items are wrapped in an unordered list with the menu id and menu class. This parameter lets you change that if you so desire.

Depth

This parameter is really nice for when you want to use the same menu twice but don’t want any child items to display in the location you’re setting up with the wp_nav_menu() function. For instance, if you want the primary navigation to include a second level dropdown, you could leave this at the default setting. Then if you wanted to use the same parent items in a footer navigation and omit the child items, you could set this parameter to a depth of 1. The default "0" means all levels will be output. To keep our example concise, we’re assuming that the primary navigation doesn’t include any child items.

Walker

The parameter is used to define a walker object which can be used to manipulate how the entire function works and outputs its information. We’ll go over a good example in the next section.

Adding a Description to the Nav Menu Items

For our example, we want to add a sub description to each main menu item. The functionality to add the description itself is already in place in the WordPress Menu system. To turn this on, go to Menus and then press the screen options tab in the top right corner. The option you need to make sure is clicked should say, "Description". With this checked, a menu item should now look like this:

Once we have our descriptions filled out, we’ll need to create the walker class and add it to the wp_nav_menu() parameters. We’ll call the class description_navigation so our complete parameters code should look like this:

$params = array(
	'theme_location' => 'primary',
	'menu_id' => 'nav',
	'walker' => new description_walker()
);
wp_nav_menu($params);

The Walker Class

Now we’re ready to add those descriptions in using our Walker class:

class description_walker extends Walker_Nav_Menu {
	function start_el(&$output, $item, $depth, $args) {
		global $wp_query;
		$indent = ( $depth ) ? str_repeat( "\t", $depth ) : '';

		$class_names = $value = '';

		$classes = empty( $item->classes ) ? array() : (array) $item->classes;

		$class_names = join( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item ) );
		$class_names = ' class="'. esc_attr( $class_names ) . '"';

		$output .= $indent . '<li id="menu-item-'. $item->ID . '"' . $value . $class_names .'>';

		$attributes  = ! empty( $item->attr_title ) ? ' title="'  . esc_attr( $item->attr_title ) .'"' : '';
		$attributes .= ! empty( $item->target )     ? ' target="' . esc_attr( $item->target     ) .'"' : '';
		$attributes .= ! empty( $item->xfn )        ? ' rel="'    . esc_attr( $item->xfn        ) .'"' : '';
		$attributes .= ! empty( $item->url )        ? ' href="'   . esc_attr( $item->url        ) .'"' : '';
		$description  = ! empty( $item->description ) ? '<span>'.esc_attr( $item->description ).'</span>' : '';

		if($depth != 0) {
			$description = $append = $prepend = "";
		}

		$item_output = $args->before;
		$item_output .= '<a'. $attributes .'>';
		$item_output .= $args->link_before .apply_filters( 'the_title', $item->title, $item->ID );
		$item_output .= $description.$args->link_after;
		$item_output .= '</a>';
		$item_output .= $args->after;

		$output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args );
	}
}

There is a lot going on here. For more information on Walker classes in general, let me refer you to another tutorial: Understanding the Walker Class. The most important part you should understand here is that we’re rebuilding the output of each link item and adding in the description. On line 19 of the snippet above you can see where we get the item description if it exists and make it the value of $description wrapped in a span tag so that we can style the descriptions separately. Then in lines 24-29 where we piece the link item back together, we add in the description right before the close of the anchor tag so that it becomes part of the link itself.

Using the Twenty Eleven theme, you should now have something that looks like this:

Style It Up

Let’s add a bit of styling to make it more legible:

#nav a {
	line-height: 20px;
	padding: 10px 15px;
}

#nav a span {
	display: block;
	font-size: 11px;
	color: #ccc;
}

#nav a:hover span {
	color: #999;
}

This will change the height and padding of each link, cause the description within the span tag to drop to its own line, and adjust the font sizes and colors a bit for a final result that looks like this:

Relation Functions

Not only can you use wp_nav_menu() to output your menu with all customizations, you can go a little further with some of its related functions.

has_nav_menu()

This function is great for only displaying a particular menu if that menu has been assigned to your theme location. For instance, you may want to create a top navigation on your theme for lesser navigation items that a user may not want in their main navigation. This could be things like a home link, "Advertise With Us", or other lower calls to action. But as a theme distributor, if you don’t know if that’s going to be something the user wants to use, simply use a condition like so:

if (has_nav_menu('top-menu')) {
	wp_nav_menu('theme_location='top-menu');
}

wp_get_nav_menu_items()

This function will return an array of items from a particular menu. This may be particular useful if you want to build a custom menu list without using a Walker Class. You lose a lot of functionality such as the menu item’s current class, but it’s a great way to loop through an array of menu items for a simple solution.

Conclusion

There are a lot of things you can do to customize your navigation menus when you know more about the flexibility that is offered with built in parameters and being able to have greater control with the Walker Class. Need to add another span tag with the class of "icon" for custom icons to each item? No problem.

Being able to have full control over the placement and output of menus extends your capabilities as a theme developer an unmeasurable amount of possibilities. What are some of the things you can use that Walker class to do?

Why Should I Use a Video Shortcode?

• Because video embedding plugins are just another little burden for your blog. They take some space on your disk (granted, not more than 1MB), they always query your database for their options and you need to learn how to use the plugins.
• Because embedding the codes of the video sites can be corrupted – especially when you switch between the WYSIWYG editor and the HTML editor.
• And most importantly: Because shortcodes are awesome! They’re easy to use, they can have the functionality of many plugins and their code doesn’t break in your posts!

Exploring the Video Sites

We’re going to work with 7 video hosting sites:

1. YouTube (obviously!)
2. Vimeo
3. Dailymotion
4. Yahoo! Screen
5. Blip.tv
6. Veoh
7. Viddler

Let’s see what their embed codes look like:

YouTube

The default embed code looks like this:

/* Original video: youtube.com/watch?v=dQw4w9WgXcQ */
<iframe width="420" height="315" src="http://www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allowfullscreen></iframe>

But there’s one option, the “privacy-enhanced mode” which adds “-nocookie” to the domain and we’re going to use it in our shortcode.

Vimeo

/* Original video: vimeo.com/36804448 */
<iframe src="http://player.vimeo.com/video/36804448" width="500" height="281" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>

Simple and elegant. That’s why people love Vimeo.

Dailymotion

/* Original video: dailymotion.com/video/xhwpbg_bridgestone-15-sec-spot_auto */
<iframe frameborder="0" width="480" height="360" src="http://www.dailymotion.com/embed/video/xhwpbg"></iframe><br /><a href="http://www.dailymotion.com/video/xhwpbg_bridgestone-15-sec-spot_auto" target="_blank">BridgeStone 15 Sec spot</a> <i>by <a href="http://www.dailymotion.com/DailymotionUSA" target="_blank">DailymotionUSA</a></i>

I think adding a link below the embed code is just not cool, so we’re not adding that to our shortcode.

Yahoo! Screen

/* Original video: screen.yahoo.com/mysterious-death-of-500-fish-in-german-lake-blamed-on-urinating-swimmers-29322943.html */
<div><iframe frameborder="0" width="576" height="324" src="http://d.yimg.com/nl/vyc/site/player.html#shareUrl=http%3A%2F%2Fscreen.yahoo.com%2Fmysterious-death-of-500-fish-in-german-lake-blamed-on-urinating-swimmers-29322943.html&vid=29322943&browseCarouselUI=hide&repeat=0&startScreenCarouselUI=hide"></iframe></div>

The embed code is a little weird on Yahoo! Screen but I found a way to shorten it which will be easier to use in our shortcode.

Blip.tv

/* Original video: blip.tv/mister-glasses/episode-7-5600357 */
<iframe src="http://blip.tv/play/AYLV6UkC.html?p=1" width="780" height="438" frameborder="0" allowfullscreen></iframe><embed type="application/x-shockwave-flash" src="http://a.blip.tv/api.swf#AYLV6UkC" style="display:none"></embed>

This is a hard one – this doesn’t have the video ID (from the video’s URL) in the embed code. But thanks to some research, I figured out how to use the ID! :)

Veoh

/* Original video: veoh.com/watch/v27458670er62wkCt */
<object width="410" height="341" id="veohFlashPlayer" name="veohFlashPlayer"><param name="movie" value="http://www.veoh.com/swf/webplayer/WebPlayer.swf?version=AFrontend.5.7.0.1355&permalinkId=v27458670er62wkCt&player=videodetailsembedded&videoAutoPlay=0&id=anonymous"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.veoh.com/swf/webplayer/WebPlayer.swf?version=AFrontend.5.7.0.1355&permalinkId=v27458670er62wkCt&player=videodetailsembedded&videoAutoPlay=0&id=anonymous" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="410" height="341" id="veohFlashPlayerEmbed" name="veohFlashPlayerEmbed"></embed></object><br /><font size="1">Watch <a href="http://www.veoh.com/watch/v27458670er62wkCt">Intense Cat</a> in <a href="http://www.veoh.com/browse/videos/category/animals">Animals</a>&nbsp;&nbsp;|&nbsp;&nbsp;View More <a href="http://www.veoh.com">Free Videos Online at Veoh.com</a></font>

Ah, the <object> tag… Don’t worry, we’re not going to use it!

Viddler

/* Original video: viddler.com/v/978c9ba2 */
<iframe id="viddler-978c9ba2" src="//www.viddler.com/embed/978c9ba2/?f=1&autoplay=0&player=full&loop=false&nologo=false&hd=false" width="437" height="315" frameborder="0" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>

That’s all. Now, let’s get to the fun part!

The Shortcode: [vid]

We’ll create 4 attributes for this shortcode – the name of the site, the ID of the video and the width and the height of the video. You can set some default values for the attributes:

function vid_sc($atts, $content=null) {
	extract(
		shortcode_atts(array(
			'site' => 'youtube',
			'id' => '',
			'w' => '400',
			'h' => '250'
		), $atts)
	);
}
add_shortcode('vid','vid_sc');

Then comes the part where the function generates the $src variable which generates the src attribute for the iframe:

// YouTube with "privacy-enhanced mode":
if ( $site == "youtube" ) {
	$src = 'http://www.youtube-nocookie.com/embed/'.$id;
}
// Vimeo:
else if ( $site == "vimeo" ) {
	$src = 'http://player.vimeo.com/video/'.$id;
}
// Dailymotion:
else if ( $site == "dailymotion" ) {
	$src = 'http://www.dailymotion.com/embed/video/'.$id;
}
// Yahoo! Screen with some cuts in the URI:
else if ( $site == "yahoo" ) {
	$src = 'http://d.yimg.com/nl/vyc/site/player.html#vid='.$id;
}
// Blip.tv with some "hacks" in the URI:
else if ( $site == "bliptv" ) {
	$src = 'http://a.blip.tv/scripts/shoggplayer.html#file=http://blip.tv/rss/flash/'.$id;
}
// The Veoh URI has some hacks, too:
else if ( $site == "veoh" ) {
	$src = 'http://www.veoh.com/static/swf/veoh/SPL.swf?videoAutoPlay=0&permalinkId='.$id;
}
// Viddler:
else if ( $site == "viddler" ) {
	$src = 'http://www.viddler.com/simple/'.$id;
}

And of course, we return the output. Here’s the full code of our brand new video shortcode:

function vid_sc($atts, $content=null) {
	extract(
		shortcode_atts(array(
			'site' => 'youtube',
			'id' => '',
			'w' => '600',
			'h' => '370'
		), $atts)
	);
	if ( $site == "youtube" ) { $src = 'http://www.youtube-nocookie.com/embed/'.$id; }
	else if ( $site == "vimeo" ) { $src = 'http://player.vimeo.com/video/'.$id; }
	else if ( $site == "dailymotion" ) { $src = 'http://www.dailymotion.com/embed/video/'.$id; }
	else if ( $site == "yahoo" ) { $src = 'http://d.yimg.com/nl/vyc/site/player.html#vid='.$id; }
	else if ( $site == "bliptv" ) { $src = 'http://a.blip.tv/scripts/shoggplayer.html#file=http://blip.tv/rss/flash/'.$id; }
	else if ( $site == "veoh" ) { $src = 'http://www.veoh.com/static/swf/veoh/SPL.swf?videoAutoPlay=0&permalinkId='.$id; }
	else if ( $site == "viddler" ) { $src = 'http://www.viddler.com/simple/'.$id; }
	if ( $id != '' ) {
		return '<iframe width="'.$w.'" height="'.$h.'" src="'.$src.'" class="vid iframe-'.$site.'"></iframe>';
	}
}
add_shortcode('vid','vid_sc');

Tip within the quick tip: Take note that the iframe has two CSS classes: vid and iframe-$site (e.g. iframe-youtube). You should add vid {border:0;} to your CSS file since we didn’t define the frameborder attribute in our iframe tag.

Usage Examples

The default usage is simple enough:

[vid site="youtube" id="dQw4w9WgXcQ" w="600" h="340"]

But to make it even simpler, we set default values for site, w and h. So, if you want to embed a YouTube video, you can just use it like this:

[vid id="dQw4w9WgXcQ"]

You should change the width and the height to match your blog. Also, if you use Vimeo more than YouTube, you can change the default site value to “vimeo”.

That’s it! Add this to your functions.php file and you can start using the shortcode. Enjoy!

Update: We’ve added a usage example section to the article now to make things clearer.

Why Use Custom Queries?

The basic functionalities in WordPress are fine for most simple needs, but what would you do if you want to implement some specific needs? Are you writing a plugin maybe? Then you should learn how you can use SQL queries in WordPress right now! The official references can be found in the WordPress Codex (Custom Queries and the WPDB class).

The wpdb Class

This global WordPress class is key for using queries. In fact, every function uses this class.

Using query

The query function needs a string containing the custom query. The returning value is an integer corresponding to the number of rows affected/selected, and false when there is an error.

$query = "SELECT COUNT(apple) FROM fruits";
$wpdb->query($query);

get_results

This function gets multiple rows when executing a query. By default the result of the function is an array.

$query = "
	SELECT *
	FROM wp_terms wt
	INNER JOIN wp_term_taxonomy wtt ON wt.term_id = wtt.term_id
	WHERE wtt.taxonomy = 'post_tag' AND wtt.count = 0";

$wpdb->get_results($query);

get_var

This will return one variable from the database, but the complete result of the query is cached for later use. Returns NULL if no result is found.

$query = "SELECT COUNT(*) FROM users";
$wpdb->get_var($query);

get_row

A complete row will be returned as a result of the function, which can be an object, an associative array, or a numerically indexed array. NULL is the result when no matching data is found. result_type can be OBJECT, ARRAY_A or ARRAY_N (object, associative array or numbered array). Offset is an integer with a default of 0.

$query = "
SELECT * FROM wp_posts
WHERE post_type = 'post'";

$wpdb->get_row($query, ARRAY_A, 3);

get_col

For getting a column, use this function. Output will be a dimensional array. An empty array will be returned if no result is found. The second parameter is the column offset.

$query = "
SELECT * FROM wp_posts
WHERE post_type = 'post'";

$wpdb->get_col($query, 3);

Prepared Queries

According to the php.net manual:

“They [prepared queries] can be thought of as a kind of compiled template for the SQL that an application wants to run, that can be customized using variable parameters.”

You can protect SQL queries against SQL injection attacks. In short data in queries must be SQL-escaped before the query is executed to prevent injection attacks. This can be easily done with the prepare method. In the following example, the values ’10′, ‘monkey’ and ‘apple’ will be escaped when used in this method.

// Usage: $wpdb->prepare( 'query' [, value_parameter, value_parameter ... ] );

$wpdb->query( $wpdb->prepare(
	"INSERT INTO test_table (post_id, animal, food) VALUES ( %d, %s, %s )",
	array(
		10,
		'monkey',
		'apple'
	)
));

Setting Error Messages

You can turn error messages on and off with the show_errors and hide_errors functions, but you can also print:

$wpdb->show_errors();
$wpdb->hide_errors();

Cache Control

Deleting the cache can be made with the flush function.

$wpdb->flush();

Inserting Data

$wpdb->insert($table, $data, $format);

$wpdb->insert(
	'foods',
	array(
		'fruit' => 'apple',
		'year' => 2012
	),
	array(
		'%s',
		'%d'
	)
);

The used parameters in order are:

• the name of the table to insert data into
• the data to insert (column => value pairs) without escaping
• an array of formats to be mapped to each of the values in $data. If not present, all values will be treated as strings

Updating Data

$wpdb->update(
	'foods',
	array(
		'fruit' => 'apple',	// string
		'year' =>  'value2'	// integer (number)
	),
	array( 'ID' => 1 ),
	array(
		'%s',	// value1
		'%d'	// value2
	),
	array( '%d' )
);

The used parameters in order are:

• table name
• data
• where conditions
• format
• where_format

Column Information

You can get information about the columns of the most recent result with this function. When a function has returned an OBJECT and there are properties you don’t know much about, this can be useful.

$wpdb->get_col_info('type', offset);

• Type: the information you want to retrieve, some examples are here
  • name – column name (this is the default)
  • table – name of the table the column belongs to
  • max_length – maximum length of the column
  • not_null – 1 if the column cannot be NULL
  • more can be found in the WordPress Codex WPDB reference
• Offset: specify the column from which to retrieve information (0 is the first column)

Referencing WordPress Tables

WordPress database tables can be referenced in the wpdb class. This is very convenient as table names can be different than the default ones. Here’s a list of WordPress database table references:

• $wpdb->posts;
• $wpdb->postmeta;
• $wpdb->comments;
• $wpdb->commentmeta;
• $wpdb->terms;
• $wpdb->term_taxonomy;
• $wpdb->term_relationships;
• $wpdb->users;
• $wpdb->usermeta;
• $wpdb->links;
• $wpdb->options;

Note that we don’t need to include the prefix, that’s the benefit here where the wpdb class takes care of that for us.

There we have it! A reference for custom queries in WordPress, all in one place for you.

In this tutorial we are going to create a WordPress widget which displays your Facebook like box. With this WordPress widget you will have the option to display the box header, show your latest fans and show your latest Facebook stream.

Facebook Pages

Facebook Pages have been around for a while now and they have recently been converted to use the new timeline feature to bring even more exposure to your previous posts on your profile.

A Facebook Page is the same as a personal page but you can not friend other people, this is because Facebook Pages are for businesses to connect with their customers.

Facebook Pages give you a more dynamic relationship with the public figures and organizations you are interested in.

If you have your own business you too can create your own Facebook Page.

Facebook Like Box

A Facebook like box is a social plugin which enables Facebook Page owners to display a like button and a status stream on their own website.

The like box means visitors to your site can:

• See how many people like the page and which of their friends already like this page.
• View your recent status updates.
• Like your Facebook Page without leaving your site.

Here is an example of Wptuts+’s Facebook like box.

To create a Facebook Like Box for your Facebook page you need to register a Facebook app to be able to use the Facebook open graph API.

Now you see what the Facebook like box is we can understand how to turn this into a WordPress widget.

WordPress Widgets

Before we start coding the widget we need to understand what a WordPress widget is and how we can use the WordPress Widget API to easily create WordPress widgets.

A WordPress widget is a piece of PHP code which will run inside a WordPress sidebar.

A WordPress sidebar is a registered area in your theme where you can add WordPress widgets.

WordPress widgets can easily be added to sidebars by going to the Widget page in the Dashboard and navigate to Appearance -> Widgets. From this Widgets page you are able to drag and drop widgets into a sidebar of your choice. The widget should have some sort of Admin form so you can edit the data shown by the widget.

WordPress WP_Widget

To create a WordPress widget all you need to do is inherit from the standard WP_Widget class and use some of its functions.

There are three main functions that need to be used for the widget to work these functions are form(), widget() and update().

The WP_Widget class is located in wp-includes/widgets.php.

WordPress Starter Widget

Below is the boilerplate of a WordPress widget, when you create a new widget just copy and paste the below code as a starting point for your widget.

/**
 * Adds Foo_Widget widget.
 */
class Foo_Widget extends WP_Widget {

	/**
	 * Register widget with WordPress.
	 */
	public function __construct() {
		parent::__construct(
			'foo_widget', // Base ID
			'Foo_Widget', // Name
			array( 'description' => __( 'A Foo Widget', 'text_domain' ), ) // Args
		);
	}

	/**
	 * Front-end display of widget.
	 *
	 * @see WP_Widget::widget()
	 *
	 * @param array $args     Widget arguments.
	 * @param array $instance Saved values from database.
	 */
	public function widget( $args, $instance ) {
		extract( $args );
		$title = apply_filters( 'widget_title', $instance['title'] );

		echo $before_widget;
		if ( ! empty( $title ) )
			echo $before_title . $title . $after_title;
		?>Hello, World!<?php
		echo $after_widget;
	}

	/**
	 * Sanitize widget form values as they are saved.
	 *
	 * @see WP_Widget::update()
	 *
	 * @param array $new_instance Values just sent to be saved.
	 * @param array $old_instance Previously saved values from database.
	 *
	 * @return array Updated safe values to be saved.
	 */
	public function update( $new_instance, $old_instance ) {
		$instance = array();
		$instance['title'] = strip_tags( $new_instance['title'] );

		return $instance;
	}

	/**
	 * Back-end widget form.
	 *
	 * @see WP_Widget::form()
	 *
	 * @param array $instance Previously saved values from database.
	 */
	public function form( $instance ) {
		if ( isset( $instance[ 'title' ] ) ) {
			$title = $instance[ 'title' ];
		}
		else {
			$title = __( 'New title', 'text_domain' );
		}
		?>
		<p>
		<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
		<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />
		</p>
		<?php
	}

} // class Foo_Widget

Creating Facebook Like Box Widget

We are going to create a WordPress widget to allow you to easily add and change a Facebook like box on your WordPress blog.

The benefit of using a widget is for the flexibility it will give you. The choice that you have on your Facebook like box allows you to completely change the functionality just by placing different attributes on the like box.

The Facebook like box takes the following attributes:

• data-href – The URL to your Facebook page.
• data-width – The width of the like box.
• data-show-faces – A true or false value which decides if you will show people who like your page.
• data-stream – A true or false value which decides if you will show your latest status updates.
• data-header – A true or false value which decides if you will show the find us on Facebook bar.

These are the options which we need to make sure the user can change in the widget admin screen, so they can change the look of the like box directly in the WordPress dashboard.

Now we know what to expect from the Facebook like box we can start coding.

Facebook Widget Constructor

First we are going to register the widget on the widget_init action.

/*
 * Plugin Name: Paulund Facebook Like Box
 * Plugin URI: http://www.paulund.co.uk
 * Description: A widget that a facebook like box for your website
 * Version: 1.0
 * Author: Paul Underwood
 * Author URI: http://www.paulund.co.uk
 * License: GPL2

    Copyright 2012  Paul Underwood

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License,
    version 2, as published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
*/

/**
 * Register the Widget
 */
add_action( 'widgets_init', create_function( '', 'register_widget("pu_facebook_widget");' ) );

The register_widget function will call the pu_facebook_widget class. In the constructor we can create the widget by passing through arguments to the WP_Widget constructor.

/**
 * Create the widget class and extend from the WP_Widget
 */
class pu_facebook_widget extends WP_Widget {

	/**
	 * Register widget with WordPress.
	 */
	public function __construct() {

		parent::__construct(
			'pu_facebook_widget',		// Base ID
			'Facebook Like Box',		// Name
			array(
				'classname'		=>	'pu_facebook_widget',
				'description'	=>	__('A widget that displays a facebook like box from your facebook page.', 'framework')
			)
		);

	} // end constructor
}

Widget Function

The widget function is called to output the widget in the sidebar. This is where we need to collect the data input from the user on the dashboard and display the widget on the website.

Use the following function to display your Facebook like box.

	/**
	 * Front-end display of widget.
	 *
	 * @see WP_Widget::widget()
	 *
	 * @param array $args     Widget arguments.
	 * @param array $instance Saved values from database.
	 */
	public function widget( $args, $instance ) {
		extract( $args );

		/* Our variables from the widget settings. */
		$this->widget_title = apply_filters('widget_title', $instance['title'] );

		$this->facebook_id = $instance['app_id'];
		$this->facebook_username = $instance['page_name'];
		$this->facebook_width = $instance['width'];
		$this->facebook_show_faces = ($instance['show_faces'] == "1" ? "true" : "false");
		$this->facebook_stream = ($instance['show_stream'] == "1" ? "true" : "false");
		$this->facebook_header = ($instance['show_header'] == "1" ? "true" : "false");

		add_action('wp_footer', array(&$this,'add_js'));

		/* Display the widget title if one was input (before and after defined by themes). */
		if ( $this->widget_title )
			echo $this->widget_title;

		/* Like Box */
		?>
			<div class="fb-like-box"
				data-href="http://www.facebook.com/<?php echo $this->facebook_username; ?>"
				data-width="<?php echo $this->facebook_width; ?>"
				data-show-faces="<?php echo $this->facebook_show_faces; ?>"
				data-stream="<?php echo $this->facebook_stream; ?>"
				data-header="<?php echo $this->facebook_header; ?>"></div>
		<?php
	}

You may have noticed we add an action to the wp_footer to run the function add_js. This is where you will need to add the Facebook JavaScript to get the like box to work correctly.

/**
 * Add Facebook javascripts
 */
public function add_js() {
	echo '<div id="fb-root"></div>
		<script>(function(d, s, id) {
			var js, fjs = d.getElementsByTagName(s)[0];
			if (d.getElementById(id)) return;
			js = d.createElement(s); js.id = id;
			js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1&appId='.$this->facebook_id.'";
			fjs.parentNode.insertBefore(js, fjs);
		}(document, \'script\', \'facebook-jssdk\'));</script>';
}

Update Function

The update function is used to update the WordPress database when the widget admin form is submitted.

This is where you will need to place any validation needed on the values from the form. This takes 2 parameters, an array of values sent to be saved and an array of values which are currently stored. The return of this function will be the new values stored in the database.

/**
 * Sanitize widget form values as they are saved.
 *
 * @see WP_Widget::update()
 *
 * @param array $new_instance Values just sent to be saved.
 * @param array $old_instance Previously saved values from database.
 *
 * @return array Updated safe values to be saved.
 */
function update( $new_instance, $old_instance ) {
	$instance = $old_instance;

	/* Strip tags for title and name to remove HTML (important for text inputs). */
	$instance['title'] = strip_tags( $new_instance['title'] );
	$instance['app_id'] = strip_tags( $new_instance['app_id'] );
	$instance['page_name'] = strip_tags( $new_instance['page_name'] );
	$instance['width'] = strip_tags( $new_instance['width'] );

	$instance['show_faces'] = (bool)$new_instance['show_faces'];
	$instance['show_stream'] = (bool)$new_instance['show_stream'];
	$instance['show_header'] = (bool)$new_instance['show_header'];

	return $instance;
}

Form Function

The form function is used to create the form on the widget dashboard. This will need to be pre-populated with the current values in the database and make it easy for the user to change the values to change the widget behaviour.

/**
 * Create the form for the Widget admin
 *
 * @see WP_Widget::form()
 *
 * @param array $instance Previously saved values from database.
 */
function form( $instance ) {

	/* Set up some default widget settings. */
	$defaults = array(
		'title' => $this->widget_title,
		'app_id' => $this->facebook_id,
		'page_name' => $this->facebook_username,
		'width' => $this->facebook_width,
		'show_faces' => $this->facebook_show_faces,
		'show_stream' => $this->facebook_stream,
		'show_header' => $this->facebook_header
	);

	$instance = wp_parse_args( (array) $instance, $defaults ); ?>

	<!-- Widget Title: Text Input -->
	<p><label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e('Title:', 'framework') ?></label>
	<input type="text" class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" value="<?php echo $instance['title']; ?>" /></p>

	<!-- App id: Text Input -->
	<p><label for="<?php echo $this->get_field_id( 'app_id' ); ?>"><?php _e('App Id', 'framework') ?></label>
	<input type="text" class="widefat" id="<?php echo $this->get_field_id( 'app_id' ); ?>" name="<?php echo $this->get_field_name( 'app_id' ); ?>" value="<?php echo $instance['app_id']; ?>" /></p>

	<!-- Page name: Text Input -->
	<p><label for="<?php echo $this->get_field_id( 'page_name' ); ?>"><?php _e('Page name (http://www.facebook.com/[page_name])', 'framework') ?></label>
	<input type="text" class="widefat" id="<?php echo $this->get_field_id( 'page_name' ); ?>" name="<?php echo $this->get_field_name( 'page_name' ); ?>" value="<?php echo $instance['page_name']; ?>" /></p>

	<!-- Width: Text Input -->
	<p><label for="<?php echo $this->get_field_id( 'width' ); ?>"><?php _e('Width', 'framework') ?></label>
	<input type="text" class="widefat" id="<?php echo $this->get_field_id( 'width' ); ?>" name="<?php echo $this->get_field_name( 'width' ); ?>" value="<?php echo $instance['width']; ?>" /></p>

	<!-- Show Faces: Checkbox -->
	<p><label for="<?php echo $this->get_field_id( 'show_faces' ); ?>"><?php _e('Show Faces', 'framework') ?></label>
	<input type="checkbox" class="widefat" id="<?php echo $this->get_field_id( 'show_faces' ); ?>" name="<?php echo $this->get_field_name( 'show_faces' ); ?>" value="1" <?php echo ($instance['show_faces'] == "true" ? "checked='checked'" : ""); ?> /></p>

	<!-- Show Stream: Checkbox -->
	<p><label for="<?php echo $this->get_field_id( 'show_stream' ); ?>"><?php _e('Show Stream', 'framework') ?></label><input type="checkbox" class="widefat" id="<?php echo $this->get_field_id( 'show_stream' ); ?>" name="<?php echo $this->get_field_name( 'show_stream' ); ?>" value="1" <?php echo ($instance['show_stream'] == "true" ? "checked='checked'" : ""); ?> /></p>

	<!-- Show Header: Checkbox -->
	<p><label for="<?php echo $this->get_field_id( 'show_header' ); ?>"><?php _e('Show Header', 'framework') ?></label>
	<input type="checkbox" class="widefat" id="<?php echo $this->get_field_id( 'show_header' ); ?>" name="<?php echo $this->get_field_name( 'show_header' ); ?>" value="1" <?php echo ($instance['show_header'] == "true" ? "checked='checked'" : ""); ?> /></p>

	<?php
}

You do not need to add a submit button as WordPress will automatically add it for you.

Download

That's all you need to create a WordPress plugin which creates a widget to display your Facebook like page. All you have to do now is install the plugin, activate it, add the widget to a sidebar and fill out the form with your page details.

You can download this plugin from WordPress.org: Download Facebook Like Box Plugin

This is part two of a series looking at WordPress’ Rewrite API. In part one we took a whistle stop tour of the basics of WordPress’ Rewrite API. In this tutorial we will look at the rewrite settings available to us when registering a post type or taxonomy. While custom post types and taxonomies (unlike the default posts, categories and tags) don’t benefit from any Settings -> Permalink interface, setting up rewrites for custom types is still fairly straightforward. We’ll also be using the methods introduced in part one, so if you haven’t already I recommend you read WordPress’ Rewrite API Part One: The Basics.

Flushing the Rewrite Rules

When you register a custom type, WordPress also registers rewrite rules (actually, not quite, and I’ll explain why in the ‘Permastructures’ section). As mentioned in part one, these rules will only be included once the rewrite rules are ‘flushed’. Themes and plug-ins can force this ‘flushing’ by calling flush_rewrite_rules(). This needs to, and should only, be done once on activation and then again on deactivation (to clean up after yourself).

Obviously, prior to flushing the rewrite rules, you need to have added them. However the init hook on which post types should be registered, has already been fired and when it was, your plug-in or theme wasn’t yet active and so your post types and taxonomies are not yet registered. In order to register the rewrite rules that come with your post types and taxonomies, this means you need to ‘manually’ register them on activation, prior to flushing the rewrite rules. So, this should be your set up:

function wptuts_register_types() {
	//function which registers your custom post type and taxonomies
}
add_action('init','wptuts_register_types');

function wptuts_plugin_activation() {

	// Register types to register the rewrite rules
	wptuts_register_types();

	// Then flush them
	flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'wptuts_plugin_activation');

function wptuts_plugin_deactivation() {

	flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'wptuts_plugin_activation');

Themes can use the hooks after_switch_theme for activation and switch_theme for de-activation.

Custom Post Types

When you register a post type with register_post_type one of the arguments available to you is the rewrite argument. This should be an array with the following keys:

• slug – a slug used to identify the post type in URLs. The post’s slug is appended to this for the post’s permalink e.g. www.example.com/books/the-wizard-of-oz
• with_front – true or false. If your post’s permalink structure begins with a constant base, such as ‘/blog’ – this can also be added to your custom post type’s permalink structure by setting it to true e.g. true will give www.example.com/blog/books/ and false www.example.com/books/
• feeds – true or false. Whether to generate feed rewrite rules e.g. www.example.com/books/feed/rss and www.example.com/book/rss. The default value is the value of has_archive.
• pages – true or false. Whether to generate rule for ‘pretty’ pagination for the post type archive e.g. www.example.com/books/page/2 instead of www.example.com/books?page=2. Defaults to true.
• ep_mask – This used to be a separate argument: permalink_epmask. As of 3.4 it will move to the rewrite array. The default is EP_PERMALINK.

The ‘feeds’ and ‘pages’ keys concern only the post-type archive page (for which you need to have set the has_archive argument to true). From this rewrite array WordPress handles the generation of the rewrite rules for your post types automatically. As an example:

$labels = array(
	'name' => __('Books', 'your-plugins-translation-domain'),
	//array of labels
);

$args = array(
	'labels' => $labels,
	'has_archive'=>true,
	'rewrite' => array(
		'slug'=>'books',
		'with_front'=> false,
		'feed'=> true,
		'pages'=> true
	)
);
register_post_type('book',$args);

Would give the following rewrite rules:

• The permalink of the book ‘the-wizard-of-oz‘: www.example.com/books/the-wizard-of-oz
• Archive of all books www.example.com/books (and www.example.com/books/page/2)
• The feed of the above archive: www.example.com/books/feed/rss (and www.example.com/books/rss)

Taxonomies

The register_taxonomy() function offers fewer options:

• slug – a slug to identify the taxonomy e.g. www.example.com/genre/history
• with_front – As above.
• hierarchical – true or false. If set to true and the taxonomy is hierarchical, the term permalink reflects the hierarchy. Defaults to false.
• ep_mask – Added in 3.4. See EP Mask section below.

The first two options are similar to the above. The hierarchical option gives the term permalinks the same structure as pages. For example, let ‘History’ be a genre and ‘Military History’ a sub-genre. With hierarchical set to false, ‘Military History’ will have a the permalink:

www.example.com/genre/military-history

Whereas, set to true, it will have:

www.example.com/genre/military/military-history

Registering a taxonomy automatically registers your taxonomy-terms’ feeds:

www.example.com/genre/military-history/feed

You can get the feed-link permalink to any taxonomy term with $feed_link = get_term_feed_link($term_id, $taxonomy, $feed)

Post Type Archives

By default, WordPress doesn’t produce ‘pretty’ permalinks for your custom post type’s year, month or day archives (nor the author archive – but we’ll leave that one for now). While:

www.example.com/?post_type=book&year=2012&monthnum=05

Correctly gives an archive of all books published in May 2012:

www.example.com/books/2012/05

Will give a 404 error. However, we can simply add extra rewrite rules using the available rewrite API methods we covered in part one. One method is to add the following list of rewrite rules when you register your post type:

// Add day archive (and pagination)
add_rewrite_rule("books/([0-9]{4})/([0-9]{2})/([0-9]{2})/page/?([0-9]{1,})/?",'index.php?post_type=book&year=$matches[1]&monthnum=$matches[2]&day=$matches[3]&paged=$matches[4]','top');
add_rewrite_rule("books/([0-9]{4})/([0-9]{2})/([0-9]{2})/?",'index.php?post_type=book&year=$matches[1]&monthnum=$matches[2]&day=$matches[3]','top');

// Add month archive (and pagination)
add_rewrite_rule("books/([0-9]{4})/([0-9]{2})/page/?([0-9]{1,})/?",'index.php?post_type=book&year=$matches[1]&monthnum=$matches[2]&paged=$matches[3]','top');
add_rewrite_rule("books/([0-9]{4})/([0-9]{2})/?",'index.php?post_type=book&year=$matches[1]&monthnum=$matches[2]','top');

// Add year archive (and pagination)
add_rewrite_rule("books/([0-9]{4})/page/?([0-9]{1,})/?",'index.php?post_type=book&year=$matches[1]&paged=$matches[2]','top');
add_rewrite_rule("books/([0-9]{4})/?",'index.php?post_type=book&year=$matches[1]','top');

This can easily get a bit messy – especially when you consider that you would need to add extra rules if you wanted your archives to support pretty URLs for their feeds. However, the above illustrates an important fact about adding custom rules: The order in which the rules are added is important.

Recall that these rules are added to the rewrite array in the order in which you call add_rewrite_rule. When parsing a request, WordPress uses the first matching rule. Try switching the order in which the year and month archive rules are added. You’ll find that www.example.com/books/2012/04/ takes you to the 2012 archive. This is because that URL matches the patterns for both the year and month archives, but the former was added first. Remember to always add the more specific rule first.

On the other hand, if you add a rewrite rule, whose regex already exists as a rule, that rule shall be overridden by the new one.

Permastructures

There is an easy way to achieve the above: add_permastruct. This function is used by WordPress to create ‘permastructures’, from which it generates rewrite rules (like the above), which handle pagination and feeds. When you register a custom post type, WordPress doesn’t automatically create all the rewrite rules. Instead it registers a permastructure – and only when the rules are being generated (i.e. when they are being flushed) does WordPress use those permastructures to generate the actual rewrite rules.

An example of a permastructure is the one you use in Settings -> Permalinks. These accept any ‘hard-coded’ slugs or any tags that exist by default or have been added with add_rewrite_tag, which we covered in part one. For example, the permastructure %year%/%category%/%author% would generate the following rewrite rules:

• www.example.com/2012/url-rewriting/stephen
• www.example.com/2012/url-rewriting/stephen/page/2
• www.example.com/2012/url-rewriting/stephen/feed/rss

• www.example.com/2012/url-rewriting/
• www.example.com/2012/url-rewriting/page/2
• www.example.com/2012/url-rewriting/feed/rss

• www.example.com/2012/
• www.example.com/2012/page/2
• www.example.com/2012/feed/rss

The add_permastruct Function

The add_permastruct function accepts four arguments:

• name – A unique slug to identify your permastructure
• struct – The permastructure itself e.g. ‘%year%/%category%/%author%‘
• with_front – true or false. This is the same argument as when registering the post type
• ep_mask – See EP Mask section below

A couple of warnings on using add_permastruct need to be made here. First: you’ll want to make sure that a custom permastructure doesn’t clash with WordPress’ rewrite rules for posts and pages. This can be done by prepending your custom permastructure with something hard-coded. For example:

'something-hard-coded/%year%/%monthnum%/%day%'

Secondly – the rules are added in that order – so if your tags are ‘too generic’, the latter rules may never be applied. For example, the above structure (which you can try on your Settings -> Permalinks page), generally works well, except that:

www.example.com/2012/page/2

Is interpreted as the page of posts by author ’2′, in category ‘page’ in 2012. If you want to use add_permastruct and have your pagination and feeds rules cascade nicely then you’ll need to use tags which are not ‘generic’ (by which I mean that the regex expressions are not generic). %author% and %category% are good examples of a generic tag as these will typically match any character.

Custom Permastructure Example: Post Type Date Archives

The year, month, and day tags on the other hand are very specific – matching only positive integers of lengths four and two, so we can use add_permastruct for our post type’s date archive. Because of the specific nature of the date tags, we need these rules to be added before the post type permalink rule – so add the following immediately before registering your post type:

// Please note that this will only work on WordPress 3.4+ http://core.trac.wordpress.org/ticket/19871
add_rewrite_tag('%book_cpt%','(book)s','post_type=');
add_permastruct('book_archive', '%book_cpt%/%year%/%monthnum%/%day%');

In the above, the custom tag %book_cpt% acts as a hard-coded slug to differentiate this permastructure from other rules (as per the first warning). The generated rules will only apply if %book_cpt% matches ‘books’ and, in which case the ‘book’ part is captured and interpreted as the value for post_type. Please note that add_rewrite_tag only accepts the third argument since WordPress 3.4. However, you could use the following work-around:

global $wp_rewrite;
$wp_rewrite->add_rewrite_tag('%book_cpt%','(book)s','post_type=');

Having set up the book archives, you might also expect that

www.example.com/books?year=2012

Would take us to the 2012 book archive as well. Testing it, however, reveals that instead it takes us to the post year archive page:

www.example.com/2012/

WordPress has redirected us to a different page due to something known as canonicalization.

Canonical Redirect

Typically there are many URLs that could point to the same content on your website. For example:

www.example.com/year/2012

www.example.com/year/2012/page/1

www.example.com/2012/////////page/1

www.example.com/index.php/2012/

www.example.com/index.php////2012///page/1

Will all take you to the first page of your 2012 archive. From a SEO perspective this isn’t great – we can’t assume that search engines will recognise these URLs as the same resource, and these URLs may end up competing against each other. Google may also actively penalise you for duplicate content, and while it is good at determining when this duplication isn’t ‘malicious’, it still recommends to redirect these superfluous URLs to one preferred ‘canonical’ (or standard) URL. This is called canonicalization.

Doing so not only helps consolidate ratings such as link popularity, but also helps your users. If they use an ugly or ‘incorrect’ URL – they are taken to the ‘correct’ URL – and what’s in their address bar, is what they’re more likely to return to.

Since 2.1.0 WordPress has handled canonical redirection, even taking an educated guess at the sought after content if the original query returned a 404. Unfortunately, in this instance, WordPress is redirecting to the wrong URL. This is because the URL we actually want is not natively understood by WordPress, and it has ignored the ‘post type’ part of the URL. Fortunately, however we can use the redirect_canonical filter to fix this.

add_filter('redirect_canonical', 'wptuts_redirect_canonical', 10, 2);
function wptuts_redirect_canonical($redirect_url, $requested_url) {

	global $wp_rewrite;

	// Abort if not using pretty permalinks, is a feed, or not an archive for the post type 'book'
	if( ! $wp_rewrite->using_permalinks() || is_feed() || ! is_post_type_archive('book') )
		return $redirect_url;

	// Get the original query parts
	$redirect = @parse_url($requested_url);
	$original = $redirect_url;
	if( !isset($redirect['query'] ) )
		$redirect['query'] ='';

	// If is year/month/day - append year
	if ( is_year() || is_month() || is_day() ) {
		$year = get_query_var('year');
		$redirect['query'] = remove_query_arg( 'year', $redirect['query'] );
		$redirect_url = user_trailingslashit(get_post_type_archive_link('book')).$year;
	}

	// If is month/day - append month
	if ( is_month() || is_day() ) {
		$month = zeroise( intval(get_query_var('monthnum')), 2 );
		$redirect['query'] = remove_query_arg( 'monthnum', $redirect['query'] );
		$redirect_url .= '/'.$month;
	}

	// If is day - append day
	if ( is_day() ) {
		$day = zeroise( intval(get_query_var('day')), 2 );
		$redirect['query'] = remove_query_arg( 'day', $redirect['query'] );
		$redirect_url .= '/'.$day;
	}

	// If paged, apppend pagination
	if ( get_query_var('paged') > 0 ) {
		$paged = (int) get_query_var('paged');
		$redirect['query'] = remove_query_arg( 'paged', $redirect['query'] );

		if ( $paged > 1 )
			$redirect_url .= user_trailingslashit("/page/$paged", 'paged');
	}

	if( $redirect_url == $original )
		return $original;

	// tack on any additional query vars
	$redirect['query'] = preg_replace( '#^\??&*?#', '', $redirect['query'] );
	if ( $redirect_url && !empty($redirect['query']) ) {
		parse_str( $redirect['query'], $_parsed_query );
		$_parsed_query = array_map( 'rawurlencode', $_parsed_query );
		$redirect_url = add_query_arg( $_parsed_query, $redirect_url );
	}

	return $redirect_url;
}

The above function is lengthy, but not very complicated. It could be improved upon, and is only intended as an example of what you can do with the redirect_canonical filter. It first checks that pretty permalinks are turned on, that we are after our ‘book’ archive and it’s not a feed. It then checks in turn:

1. Is it a year, month or day archive? If so, remove the ‘year’ variable from the query string and set the redirect URL to www.example.com/books/[year]
2. Is it a month or day archive? If so, remove the ‘monthnum’ variable from the query string and append the value to the redirect URL: www.example.com/books/[year]/[monthnum]
3. Is it a day archive? If so, remove the ‘day’ variable from the query string and append the value to the redirect URL: www.example.com/books/[year]/[monthnum]/[day]
4. Finally, if there is a paged variable, append this to the redirect URL

Tags in the Post Type Permalinks

Another feature that isn't supported for post types or taxonomies 'out of the box' is to use tags in the permalink structure. While tags used in the 'slug' of a post type's (or taxonomy's) rewrite array are correctly interpreted, WordPress doesn't replace these tags with their appropriate values when generating the permalinks – we need to replace it ourselves. However, using tags like this also breaks the post type's archive page – so we'll use a different method. As an example, let's suppose that we want our custom post type 'book' to have the structure:

www.example.com/books/[some-genre]/[a-book]

I'm using the example of a custom taxonomy, but the same methods can be used for any permastructure (for instance including the date, author, or even a custom field). First of all, we add the rewrite rule:

function wptuts_custom_tags() {
	add_rewrite_rule("^books/([^/]+)/([^/]+)/?",'index.php?post_type=book&genre=$matches[1]&book=$matches[2]','top');
}
add_action('init','wptuts_custom_tags');

Now, www.example.com/book/fiction/the-wizard-of-oz, for instance, points to the book 'the-wizard-of-oz'. However the permalink generated by WordPress still produces www.example.com/book/the-wizard-of-oz. The next step is to alter the produced permalink.

We did something similar in part one when we wanted to use a custom tag in the post permalink structure. Then we used the post_link filter; this time we use the equivalent for custom post types, the post_type_link filter. Using this hook we can inject our structure into the books' permalinks.

function wptuts_book_link( $post_link, $id = 0 ) {

	$post = get_post($id);

	if ( is_wp_error($post) || 'book' != $post->post_type || empty($post->post_name) )
		return $post_link;

	// Get the genre:
	$terms = get_the_terms($post->ID, 'genre');

	if( is_wp_error($terms) || !$terms ) {
		$genre = 'uncategorised';
	}
	else {
		$genre_obj = array_pop($terms);
		$genre = $genre_obj->slug;
	}

	return home_url(user_trailingslashit( "books/$genre/$post->post_name" ));
}
add_filter( 'post_type_link', 'wptuts_book_link' , 10, 2 );

Manipulating WordPress Rewrites

Let's extend the above permalink structure to achieve the following:

• A specific book: www.example.com/books/[some-genre]/[a-book]
• All books in a genre: www.example.com/books/[some-genre]
• All books: www.example.com/books/

Recall that the order in which rewrite rules are added matter. Specifically, rules added first take priority.

So, first we register our custom taxonomy 'genre' with:

$args = array(
	...
	'rewrite' => array(
		'slug'=>'books'
	),
	...
)
register_taxonomy('genre',$args);

This adds the following permastructure:

• Books in a genre: www.example.com/books/[some-genre]

After registering the taxonomy, we then register our custom post type as follows:

$args = array(
	...
	'rewrite' => array(
		'slug'=>'books'
	),
	...
)
register_post_type('book',$args);

This would register the following rules:

• All books: www.example.com/books/ (which we want)
• A specific book: www.example.com/books/[a-book] (which we don't)

However the second conflicts with (and is 'beaten' by) the competing rule added when we registered our taxonomy. The resulting structure is:

• Book called 'slug' : www.example.com/books/fiction/slug
• Books in genre 'slug': www.example.com/books/slug
• All Books: www.example.com/books/

EP_Masks

Earlier when we looked at registering post types, taxonomies (or otherwise, permstructures), WordPress let us specify our own 'ep_mask'. So what are they?

In part one we looked at how we can add endpoints with add_rewrite_endpoint. The second argument in that function is a constant (or combination of constants using bitwise operators), which determine where the endpoint is added. For instance:

add_rewrite_endpoint( 'form', EP_PAGES );

Adds the rewrite form(/(.*))?/?$ to every page permalink and:

add_rewrite_endpoint( 'json', EP_PAGES | EP_PERMALINKS);

Adds the rewrite json(/(.*))?/?$ to every post and page permalink. So these constants specify a 'location' (i.e. 'at the end of a post permalink') and they are called endpoint masks (or ep masks).

When you register a post type, WordPress registers a permastructure – and associated with it an endpoint mask. Then when the rewrite rules are generated, it also adds any endpoint rewrite rules that have been added to that endpoint mask.

For instance, when WordPress registers the default 'Page' post type – it associates the endpoint mask EP_PAGES with the page permastructure. Then, any endpoint rewrite rules added to the EP_PAGES are actually added to that page permastructure. When you register a post type, you can specify your own endpoint mask, or use an existing one. By default it is EP_PERMALINKS – which means any endpoint rewrite rules that are added to EP_PERMALINKS are added to your custom post type's rewrite rules.

Of course you may not want endpoint rules added for your post type (in which case you can use the endpoint mask EP_NONE), or you may wish to add some endpoint rewrite rules only to your custom post type. To do this, you first need to create an endpoint mask, which is nothing more than a constant which satisfies:

1. The value of the constant is a positive number and a power of 2: 2^x (e.g. 2097152 = 2²¹)
2. This value is unique

The power of 2 requirement is necessary because WordPress uses binary logic to determine where endpoint rules should be added. Unfortunately, this is nearly impossible to check   so the best advice is to add endpoint masks only when necessary and give it a very high value (e.g. 2²¹). At the time of writing 2⁰ up to 2¹³ are used by Core.

Define your endpoint mask just before registering your post type or taxonomy:

	define('EP_BOOK', 8388608); // 8388608 = 2^23

	$args = array(
		'labels' => $labels,
		'has_archive'=>true,
		'rewrite' => array(
			'slug'=>'books'
			'with_front'=> false
			'feed'=> true
			'pages'=> true
			'ep_mask'=> EP_BOOK
		)
	);

	register_post_type('book',$args);

	// Then you can endpoint rewrite rules to this endpoint mask
	add_rewrite_endpoint('loan', EP_BOOK);

(Note: The above uses WordPress 3.4 arguments. If you are using an older version of WordPress, you will have to use the now deprecated permalink_epmask.). As of WordPress 3.4 you can specify an endpoint mask when registering a taxonomy too.

Summary

In this tutorial I've covered the basics of the rewrite API for post types and taxonomies, but also some more advanced topics. WordPress' handling of rewrites is (necessarily) complex and the best way to understand it is to delve into the source code and test it out using what've you learnt and a rewrite analyzer plug-in.

There are a couple of tickets working their way through the WordPress development Trac at the moment, relating to the Rewrite API. In the future we see a much easier and conflict-free way of handing endpoint masks.

• Improve documentation and usability of WP_Rewrite Endpoint
• Better support for custom post types in WP_Rewrite
]]> http://wp.tutsplus.com/tutorials/creative-coding/the-rewrite-api-post-types-taxonomies/feed/ 2 http://wp.tutsplus.com/tutorials/creative-coding/the-rewrite-api-the-basics/ http://wp.tutsplus.com/tutorials/creative-coding/the-rewrite-api-the-basics/#comments Wed, 23 May 2012 10:28:21 +0000 Stephen Harris http://wp.tutsplus.com/?p=25474 This entry is part 1 of 2 in the series The Rewrite API

This is part one of a two part series looking at WordPress’ Rewrite API. In this tutorial we look at how rewrites work and the basic methods available to create custom rewrite rules.

---

What Is Rewriting?

WordPress, like all content management systems, decides what content to display based on the variables (usually called query variables) passed to it. For instance: http://example.com/index.php?category=3 tells WordPress we are after posts in a category with an ID of 3 and http://example.com/index.php?feed=rss tells WordPress we want the site’s feed in RSS format.

Unfortunately this can leave us with rather ugly URLs:

http://example.com/index.php?post_type=portfolio&taxonomy=wordpress&portfolio=my-fancy-plugin

This is where WordPress’ rewriting steps in. It allows us to replace the above with:

http://example.com/portoflio/wordpress/my-fancy-plugin

Which is now not only much more readable (and memorable) but also more SEO friendly. This is, in a nutshell, what rewrites do.

---

How Does It Work?

Now http://example.com/portoflio/wordpress/my-fancy-plugin doesn’t exist as a directory or a file. So how does WordPress serve up the correct content? When WordPress receives a ‘pretty permalink’ like the above it needs to convert that into something it understands, namely a query object. More simply it has to take the pretty URL, and map the appropriate parts to the correct query variable. So for our example:

http://example.com/portoflio/wordpress/my-fancy-plugin

• post_type is set to ‘portfolio’
• portfolio-taxonomy is set to ‘wordpress’
• portfolio is set to ‘my-fancy-plugin’ (the post name)

Then WordPress knows we are after posts of type ‘portfolio‘, in the ‘wordpress‘ ‘portfolio-taxonomy‘ taxonomy term with name ‘my-fancy-plugin‘. (As you may have guessed the first two are actually redundant). WordPress then performs that query, chooses the appropriate template with which to display the results and then serves that to the viewer. But clearly WordPress doesn’t just guess how to interpret the URLs, it needs to be told…

It Starts With .htaccess

Assuming you can and have enabled pretty permalinks on your Settings -> Permalinks page (see the Codex for minimum requirements – for WordPress on Nginx servers there is this plug-in) – then things start with the .htaccess file. It plays a simple and yet significant role. WordPress includes something similar to the the following in this file:

	# BEGIN WordPress
	<IfModule mod_rewrite.c>
		RewriteEngine On
		RewriteBase /
		RewriteRule ^index\.php$ - [L]
		RewriteCond %{REQUEST_FILENAME} !-f
		RewriteCond %{REQUEST_FILENAME} !-d
		RewriteRule . /index.php [L]
	</IfModule>
	# END WordPress

This simply checks if the file or directory actually exists – and if it does, you are simply taken there. For instance:

http://example.com/blog/wp-content/uploads/2012/04/my-picture.png

Would simply take you the PNG attachment ‘my-picture.png‘. But, as in the case of:

http://example.com/blog/portoflio/wordpress/my-fancy-plugin

Where the directory does not exist – you are taken to your WordPress’ index.php file. It’s this file which boots WordPress.

Interpreting the URL

At this point, WordPress doesn’t yet know what you’re after. After some initial loading of WordPress and its settings, it fires the parse_request method of the WP class (located in the class-wp.php file). It’s this method which takes the /portoflio/wordpress/my-fancy-plugin and converts it into a WordPress-understandable query object (almost, it actually sets the query_vars array and afterwards $wp->query_posts turns this into a query).

In short this function compares the received URL (/portoflio/wordpress/my-fancy-plugin) with an array of ‘regular expressions’. This is the rewrite array – and it will look something like this:

	category/(.+?)/page/?([0-9]{1,})/?$ => index.php?category_name=$matches[1]&paged=$matches[2]
	category/(.+?)/?$ => index.php?category_name=$matches[1]
	tag/([^/]+)/page/?([0-9]{1,})/?$=> index.php?tag=$matches[1]&paged=$matches[2]
	tag/([^/]+)/?$ => index.php?tag=$matches[1]
	([0-9]{4})/([0-9]{1,2})/([0-9]{1,2})/?$ => index.php?year=$matches[1]&monthnum=$matches[2]&day=$matches[3]
	(.+?)(/[0-9]+)?/?$ => index.php?pagename=$matches[1]&page=$matches[2]

The keys of this array are regular expressions, and the received URL is compared against each in turn until there is a match with the pattern of the URL received. The corresponding value, is how the URL is then interpreted. The $matches array contains the captured values (indexed from 1) from the matching.

For example, visiting www.example.com/blog/tag/my-tag, WordPress will look for the first pattern that matches ‘tag/my-tag‘. With the above array, it matches the third pattern: tag/([^/]+)/?$. This tells WordPress to interpret the URL as www.example.com/blog/index.php?tag=my-tag and correspondingly the ‘my-tag‘ archive is served.

Of course, WordPress lets you customise this array, and the rest of this tutorial is dedicated to showing you how.

---

Customising the Rewrite Rules

Settings -> Permalinks

Your first port of call should be the ‘Permalink’ settings page. This page allows you to alter the rules for the default ‘post‘ post type, and ‘category‘ and ‘tags‘ taxonomies. The ‘default’ option has pretty permalinks disabled, but you can select from a list of preset structures or create a custom structure. Please note that custom structures should not contain your site URL. WordPress allows you to alter your permalink structure by adding in provided tags such as %postname% (the post’s name), %year% (the year the post was published) and %author% (the author of the post). A permalink structure such as:

/%year%/%author%/%postname%/

Would produce a post link such as:

www.example.com/2012/stephen/my-post

The documentation for these options can be found in the WordPress Codex. (Later on I’ll be showing you how to create your own custom tags).

However, the provided options are quite limited. In this tutorial I shall focus on the functions provided by WordPress that offer greater control over permalink structures and how they are interpreted. I won’t be covering the rewrite options available for custom post types or taxonomies, as this will be covered in part 2.

Why Flush the Rewrite Rules?

After any alteration to the rewrite rules (for example, by either using one of the following methods, or registering a custom post type or taxonomy) you may find that the new rules do not take effect. This is because you you need to flush the rewrite rules. This can be done either one of two ways:

• Simply visit the Settings -> Permalink page
• Call flush_rewrite_rules() (covered in part 2)

What does this do? Recall that the parse_request method compares the request against a rewrite array. This array lives in the database. Flushing the rewrite rules updates the database to reflect your changes – and until you do so, they won’t be recognised. But parse_request also writes to the .htaccess file. This makes it an expensive operation. So, although I won’t cover the use of flush_rewrite_rules() until part 2, I will give you this warning: Do not call flush_rewrite_rules on every page load. Plug-ins should only call this when the plug-in is activated and deactivated.

Add Rewrite Rule

The add_rewrite_rule allows you to add additional rules to the rewrite array. This function accepts three arguments:

• rule – a regular expression with which to compare the request URL against
• rewrite – the query string used to interpret the rule. The $matches array contains the captured matches and starts from index ’1′.
• position – ‘top‘ or ‘bottom‘. Where to place the rule: at the top of the rewrite array or the bottom. WordPress scans from the top of the array to the bottom and stops as soon as it finds a match. In order for your rules to take precedence over existing rules you’ll want to set this to ‘top‘. Default is ‘bottom‘.

Note: if you use add_rewrite_rule several times, each with position ‘top‘ – the first call takes precedence over subsequent calls.

Let’s suppose our posts have an event date associated with them and we want to have this structure: www.example.com/blog/the-olympics-begin/2012-07-27 interpreted as www.example.com/blog/index.php?postname=the-olympics-begin&eventdate=2012-07-27 then we can add this rule as follows:

	function wptuts_add_rewrite_rules() {
		add_rewrite_rule(
			'^([^/]*)/([0-9]{4}-[0-9]{2}-[0-9]{2})/?$' // String followed by a slash, followed by a date in the form '2012-04-21', followed by another slash
			'index.php?pagename=$matches[1]&eventdate=$matches[2]',
			'top'
		);
	}
	add_action( 'init', 'wptuts_add_rewrite_rules' );

The following would interpret www.example.com/olympics/2012/rowing as www.example.com/index.php?p=17&olymyear=2012&game=rowing

	add_rewrite_rule(
		'^olympics/([0-9]{4})/([^/]*)',
		'index.php?p=17&olymyear=$matches[1]&game=$matches[2]',
		'top'
	);

If you’re unsure of your regular expressions, you may find this introduction and this tool useful.

Add Rewrite Tag

You may think that the value of eventdate (2012-07-27 in the above example), olymyear and game may be accessible from WordPress’ internals via the get_query_var (in the same way that get_query_var('paged') gets the page number you are on). However, WordPress does not automatically recognise the variable eventdate even though it’s interpreted as a GET variable. There are a couple of ways to make WordPress recognise custom variables. One is to use the query_vars filter as demonstrated in the ‘Add Custom Endpoint’ section below. Alternatively, we can go a step further and use add_rewrite_tag to register a custom tag like the default %postname% and %year%

This function accepts three arguments:

• tag name – (with leading and trailing %) e.g: %eventdate%
• regex – Regular expression to validate the value, e.g. ‘([0-9]{4}-[0-9]{2}-[0-9]{2})‘
• query – (optional) How the tag is interpreted, e.g. ‘eventdate=‘. If provided, must end with a ‘=’.

	function wptuts_register_rewrite_tag() {
		add_rewrite_tag( '%eventdate%', '([0-9]{4}-[0-9]{2}-[0-9]{2})');
	}
	add_action( 'init', 'wptuts_register_rewrite_tag');

Not only will get_query_var('eventdate') return the value of the date in the URL, but you can use the tag %eventdate% in the Settings -> Permalink (along with the default %year%, %postname% etc.) and WordPress will correctly interpret it. Unfortunately when generating a post’s permalink, WordPress doesn’t know how to replace %eventdate% with the appropriate value: so our post permalinks end up like:

www.example.com/the-olympics-begin/%eventdate%

We need to replace %eventdate% with an appropriate value, and we can do so using using the post_link filter. (In this example, I shall assume that the value is stored in a custom field ‘eventdate‘).

	function wp_tuts_filter_post_link( $permalink, $post ) {

		// Check if the %eventdate% tag is present in the url:
		if ( false === strpos( $permalink, '%eventdate%' ) )
			return $permalink;

		// Get the event date stored in post meta
		$event_date = get_post_meta($post->ID, 'eventdate', true);

		// Unfortunately, if no date is found, we need to provide a 'default value'.
		$event_date = ( ! empty($event_date) ? $event_date : '2012-01-01' );

		$event_date =urlencode($event_date);

		// Replace '%eventdate%'
		$permalink = str_replace( '%eventdate%', $event_date , $permalink );

		return $permalink;
	}
	add_filter( 'post_link', 'wp_tuts_filter_post_link' , 10, 2 );

In part 2 of this series I will cover custom tags for custom post types.

Add Custom Endpoint

Endpoints are tags which are appended to the URL (/trackback/[value] is the most common). It has several other potential uses: displaying different templates depending on the value set, custom notifications, and displaying posts in different ‘formats’ (printable, XML, JSON etc).

You can create endpoints with add_rewrite_endpoint. This function accepts two arguments:

• name – The name of the endpoint e.g. ‘json‘, ‘form‘, etc.
• where – Endpoint mask specifying where the endpoint should be added. This should be one of the EP_* constants listed below (or a combination using bitwise operators). When you register custom post types you can create a mask for that post type:

The default endpoint masks are:

• EP_PERMALINK – for post permalinks
• EP_ATTACHMENT – for attachments
• EP_DATE – for date archives
• EP_YEAR – for year archives
• EP_MONTH – for month archives
• EP_DAY – for ‘day’ archives
• EP_ROOT – for the root of the site
• EP_COMMENTS – for comments
• EP_SEARCH – for searches
• EP_CATEGORIES – for categories
• EP_TAGS – for tags
• EP_AUTHORS – for archive of author’s posts
• EP_PAGES – for pages
• EP_ALL – for everything

End points are extremely flexible, you can use them with bitwise operators so, for example, you can add an endpoint to post and page permalinks with EP_PERMALINK | EP_PAGES.

	function wptuts_add_endpoints() {
		add_rewrite_endpoint('myendpoint', EP_PERMALINK); // Adds endpoint to permalinks
		add_rewrite_endpoint( 'anotherendpoint', EP_AUTHORS | EP_SEARCH); // Adds endpoint to urls for authors or search results
	}
	add_action( 'init', 'wptuts_add_endpoints');

As a brief example, endpoints can be useful for form submissions. Suppose we have a contact form page with name contact-form and with permalink: www.example.com/contact and want the the URLs:

• www.example.com/contact/submission/success – to reflect a successful form submission
• www.example.com/contact/submission/error – to reflect an unsuccessful form submission

This can be done with endpoints. The following is a very simple example of how to use endpoints, and so the form is incredibly basic in its checks (and in fact doesn’t do anything with the data). Normally a form like this would work best in a plug-in, using shortcodes – but for the purposes of this example, create a page with the following template and the rest of the code you can put in your functions.php

<?php
	/**
	* Template Name: Contact Form
	*/
	include('header.php');?>

	<h1> My Simple Contact Form </h1>
	<?php if ( 'success' == get_query_var( 'form' ) ): ?>
		<div class="message">
			Your message has been sent!
		</div>

	<?php elseif( 'error' == get_query_var( 'form' )): ?>
		<div class="message">
			Oops! There seems to have been an error...
		</div>
	<?php endif ?>

	<! -- Display form here -->
	<form method='post' action=''>

		<label> Your name: </label> <input type="text" name="wptuts_contact[name]" value=""/>
		<label> Your message: </label> <textarea name="wptuts_contact[message]" rows="20" cols="30"></textarea>

		<! -- Nonce field -->
		<?php wp_nonce_field('wptuts_send_message','wptuts_contact_nonce'); ?>

		<input type="hidden" name="action" value="wptuts_send_message"/>

		<! -- mmm... honey  -->
		<style scoped>.wptuts-e-mail-conformation{display:none}</style>
		<span class="wptuts-e-mail-conformation"><label for="email-confirmation">Email confirmation:</label><input type="text" name="wptuts_contact[confirmation]" value="" /></span>

		<input type='submit' name='wptuts_contact[send]' value='Send' />
	</form>

	<?php include('footer.php');?>

(In case you are wondering, the honey is referring to this very basic method of catching spam outlined here. It’s certainly not fool proof, but proper form processing and spam protection is off topic here). Now we create our endpoint:

	function wptuts_add_endpoint() {
		add_rewrite_endpoint( 'form', EP_PAGES );
	}
	add_action( 'init', 'wptuts_add_endpoint');

Next we add our ‘form‘ variable to the array of recognised variables:

	function wptuts_add_queryvars( $query_vars ) {
		$query_vars[] = 'form';
		return $query_vars;
	}
	add_filter( 'query_vars', 'wptuts_add_queryvars' );

Finally we provide a form handler, which will process the data, submit the form, and then redirect back to the contact page with the relevant endpoint value appended.

	function wptuts_form_handler() {

		// Are we wanting to process the form
		if( ! isset( $_POST['action'] ) || 'wptuts_send_message' != $_POST['action'] )
			return;

		// ID of the contact form page
		$form_id = 2163;
		$redirect= get_permalink($form_id);

		// Check nonces
		$data = $_POST['wptuts_contact'];

		if( !isset($_POST['wptuts_contact_nonce'] ) || !wp_verify_nonce($_POST['wptuts_contact_nonce'],'wptuts_send_message') ) {
			// Failed nonce check
			$redirect .= 'form/error';
			wp_redirect($redirect);
			exit();
		}

		if( !empty( $data['confirmation'] ) ) {
			// Bees in the honey...
			$redirect .= 'form/error';
			wp_redirect($redirect);
			exit();
		}

		// Santize and validate data etc.

		// Then actually do something with the sanitized data

		// Successful!
		$redirect .= 'form/success';
		wp_redirect($redirect);
		exit();
	}
	add_action( 'init', 'wptuts_form_handler');

Of course even this example could be greatly improved by providing more detailed error messages that convey the reason for failure.

Adding a Custom Feed

With pretty permalinks enabled WordPress automatically produces pretty URLs for your site’s feed: www.example.com/feed/rss. The add_feed function allows you to create a custom feed, which if pretty permalinks are enabled, will also have a ‘pretty’ URL. This function accepts two arguments:

• feed name – The name of the feed as it will be appear in feed/[feed-name]
• feed callback – The function responsible for displaying the feed contents.

The following is intended as an example of add_feed, and provides a very basic custom feed.

	function wptuts_events_feed_callback() {
		$custom_feed = new WP_Query(array('meta_key' => 'eventdate'));

		header('Content-Type: ' . feed_content_type('rss-http') . '; charset=' . get_option('blog_charset'), true);
		echo '<?xml version="1.0" encoding="'.get_option('blog_charset').'"?'.'>'; ?>

		<rss version="2.0">
		<channel>
			<title>My custom feed</title>
			<link><?php bloginfo_rss('url') ?></link>
			<description><?php bloginfo_rss("description") ?></description>
			<lastBuildDate><?php echo mysql2date('D, d M Y H:i:s +0000', get_lastpostmodified('GMT'), false); ?></lastBuildDate>
			<language><?php echo get_option('rss_language'); ?></language>
			<?php if($custom_feed->have_posts()): ?>
				<?php while( $custom_feed->have_posts()): $custom_feed->the_post(); ?>
					<item>
						<title><?php the_title_rss() ?></title>
						<link><?php the_permalink_rss() ?></link>
						<pubDate><?php echo mysql2date('D, d M Y H:i:s +0000', get_post_time('Y-m-d H:i:s', true), false); ?></pubDate>
						<guid isPermaLink="false"><?php the_guid(); ?></guid>
						<description><![CDATA[<?php the_excerpt_rss() ?>]]></description>
					</item>
				<?php endwhile; ?>
			<?php endif; ?>
		</channel>
		</rss>
	<?php
	}

	function wptuts_add_feed() {
		add_feed('events', 'wptuts_events_feed_callback');
	}
	add_action( 'init', 'wptuts_add_feed );

After flushing the permalinks, the feed will be available at www.example.com/feed/events.

---

Checking the Rewrite Rules

Once you’ve added some of your own rewrite rules (and flushed them), you will probably want to check if they are working properly – and if they’re not, find out what’s going wrong. For this, I strongly recommended the Monkeyman Rewrite Analyzer plug-in, a free plug-in available in the WordPress repository. Once activated, this plug-in adds a page to your ‘Tools’ section, which lists all your rewrite rules.



You can also test the rules by giving it an example URL, and the plug-in will filter the rules to show only matching patterns and indicating how WordPress would interpret the URL.



Have fun, and keep an eye out for Part 2, coming soon!

Please note: There is a currently a bug in our syntax highlighter that displays “empty()” as “emptyempty()“. Don’t forget to adjust your code accordingly.

]]> http://wp.tutsplus.com/tutorials/creative-coding/the-rewrite-api-the-basics/feed/ 5