Image from Creative Commons

If your theme currently works, it should be fine after this release too. But I would love for any developers who use it to test it out and make sure.

Below is a little rundown of the new features. All these updates were instigated via pull requests on GitHub. The full discussions can be found on Issue #78 by @inxilpro, and Issue #75 by @mattwiebe. Many thanks to all the contributors and testers.

Option ID Not Required

In the past theme authors were required to have the “optionsframework_option_name” function in their theme to declare the option ID. In this new version it’s not required. If the option ID is not set, it will the simply use theme name with the the “optionsframework” as a prefix.

I’d recommend leaving it in if it’s already part of your theme, but on future projects it’s your choice.

Location of Options.php Filterable

Not everyone likes to store all their files in the base theme directory. With this filter you can rename options.php to whatever you like, or move it to whichever directory you like. Here’s an example:

add_filter('options_framework_location','options_framework_location_override');
function options_framework_location_override() {
	return array('/extensions/options-renamed.php');
}

Options Array Filterable

The entire options array is also now filterable. This might be useful if you want to make a minor alteration to the options of a parent theme from a child theme, or if you just want to avoid using optionsframework_options in your theme.

Here’s an example that appends an additional option using the filter:

add_filter('of_options', function($options) {
	$options[] = array(
	'name' => 'New Option Added Via Filter',
	'id' => 'example_filtered_option',
	'std' => 'Default',
	'type' => 'text'
	);
  return $options;
});

A Fix for User Roles

The option panel has always displayed for users who had the edit_theme_options capability, but because of a quirk in the Settings API users actually need the manage_options capability in order to save them. Now the options should save for anyone with the edit_theme_options capability.

Info Option

You can now put html into the info option by default- which should make it easier to drop in images or other customizations.

Alex King has created a plugin and submitted a couple patches, but until the WordPress UI catches up we as theme developers need to be a little creative.

In the most recent version of Portfolio Press, I ended up styling the image format to look like this:

(You can also view it on the demo site)

Post Format Styling

Instead of putting a title above the post like the standard format, I decided to hide it. In my opinion the focus should be on the image.

Instead of displaying the the_excerpt like I do for other posts in the archive view, I display the_content so that full images are able to be displayed.

Then, using jQuery, I built a rollover effect that displays the post title when someone hovers over the image. If you click on the image, it will take you to the full post.

jQuery With Post Formats

Using jQuery makes it much easier to work with the post formats because you don’t need to guess what’s in the content. It also fails gracefully if it doesn’t find the markup it’s looking for.

For instance, the rollover effect in Portfolio Press is applied only on the first image detected in the post format- even if the author dropped 12 in there. If there’s no image, no additional markup is added.

The script checks to make sure the image is at least 200px wide. The rollover title still might not fit in a larger image, but at least it has a chance.

Authors sometimes link their images to the fullsize version. However, in the archive view I want the image to only link to the full post. The script I wrote will unwrap any link around the original image, and replace it with a link to the post in the archive view. This might not be what some users in intend, but I think the majority will.

Enough Talk

Here’s the script I used to create the rollover effect on post format images:

    // Image Post Format
    $('#content .format-image').each( function() {
    	var image = $(this).find('img:first');
    	if (image.width() > 200 ) {
	    	var link = $(this).find('.entry-title').children();
	    	var title = link.text();
	    	image.unwrap('a');
	    	image.wrap('<div class="image-wrap" />');
	    	image.wrap(link.text(''));
	    	image.parent().append('<h3/>');
	    	$(this).find('h3').text(title).width(image.width() - 20);
    	}
    });
    $('.format-image .image-wrap a').hover( function() {
    	$(this).children('h3').slideDown(100);
    }, function(){
    	$(this).children('h3').slideUp(200);
    });

View It

You can view the post formats here. Portfolio Press 0.9 can be downloaded from GitHub (the latest isn’t in the .org repository yet).

I just finished a small project for Bluefin Software redeveloping their blog. They wanted to stay with WordPress.com hosting because of its ability to scale and low maintenance. And incredibly, by using just the custom design upgrade and widget areas in the Coraline Theme, it was possible to build exactly what their designer had envisioned.

Bluefin Blog After Custom Design

Bluefin Blog Original

Benefits of Using WordPress.com

Using WordPress.com has a few benefits:

• It’s completely free to have a basic blog. The custom design option is only $30/yr, and custom domains are only $12. Together, it’s still about half as much as using a shared host like HostGator or BlueHost.
• It scales up incredibly well. WordPress.com serves up 2.5 billion pageviews a month. Your site will run fast, content is served off a global CDN, and you never have to worry about upgrading a plugin.
• It handles everything most users need. Contact forms, polls, stats, twitter widgets, code highlighters, and flickr widgets are all available.

Disadvantages of Using WordPress.com

If you use WordPress.com you won’t be able to add any plugins. You’re stuck with what they got. No bbPress or Gravity Forms for you, sorry.

You can’t alter the theme markup. Although it’s possible to do a lot with CSS, you won’t be able to do everything- especially in the javascript department. You’re also limited to the selection of themes on WordPress.com.

Tips for Custom Design on WordPress.com

If that doesn’t deter you, here’s some tips for working with the custom design option:

Pick the Right Theme

Before you get heavily involved in the design, try to pick out the theme you want to use and work within it’s limitations.

I originally chose Toolbox to build the site off of since it’s a blank canvas with good markup, but to make the custom footer work I needed widget areas at the bottom. That’s why I switched to Coraline, which has an incredibly flexible layout.

Use the Widget Areas

Widget areas are the one part (besides the actual post content) where you can control the markup. Just paste in the HTML you need (no scripts or iframes though).

Build the Site Locally

I built out the Bluefin design locally using MAMP. All the free themes on WordPress.com are available on WordPress extend or directly through SVN from Automattic.

Make a Child Theme

Once you have the theme you plan to customization, make a child theme, import the WordPress.com content (if you have it), and start styling. The other advantage of building a child theme is that it will be very easy to switch to self-hosted if you need to in the future.

Upload All Your Assets to WordPress.com

When you’re ready to move the design over, simply paste in the contents of your child theme’s CSS in the custom design editor. If you’re using any images, those should be uploaded into your media assets on WordPress.com and replaced in the stylesheet so they can be served from WordPress.com’s CDN.

In Conclusion

WordPress.com won’t be for everyone- but it’s definitely a great option for some. It’s low (or free) price and quality support make it a great option for folks who aren’t ready to make the plunge on self-hosted, and also for companies and organizations that just need a basic website and fairly unique look.

Also, as a developer it’s quite nice. On a .org site you can do anything with enough time and work, but on .com the scope is inherently limited. In this case, to 400 lines of CSS.

The method suggested by Google involves manually applying code to each link. This is fine if you want to just track a few specific links, but jQuery is more useful if you want to track every external link on the page.

Custom Tracking Events

The meat of the custom event is this line (which should be fired when an external link is clicked) is:

_gat._getTrackerByName()._trackEvent("Outbound Links", e.currentTarget.host, url, 0);

• “Outbound Links” is the category of events to track
• “e.currentTarget.host” is the “action”, in this case, the domain the user is clicking to.
• “url” is the “label”, which I use to send the full url of the external link.

If you’re unfamiliar with custom events, here’s the docs page at Google.

Code for Detecting and Tracking Outbound Link Clicks

This code snippet is highly commented and peppered with console.logs so that you can verify it’s working correctly and see how it works. It should only be used in development environments- there’s a compressed version in the next section for use on live sites.

// Outbound Link Tracking with Google Analytics
// Requires jQuery 1.7 or higher (use .live if using a lower version)
// For more info see: http://support.google.com/googleanalytics/bin/answer.py?hl=en&answer=55527
$("a").on('click',function(e){
		var url = $(this).attr("href");
		// Console logs shows the domain name of the link being clicked and the current window
		console.log('e.currentTarget.host: ' + e.currentTarget.host);
		console.log('window.location.host: ' + window.location.host);
		// If the domains names are different, it assumes it is an external link
		// Be careful with this if you use subdomains
		if (e.currentTarget.host != window.location.host) {
			console.log('external link click');
			// Outbound link!  Fires the Google tracker code.
			_gat._getTrackerByName()._trackEvent("Outbound Links", e.currentTarget.host, url, 0);
  		// Checks to see if the ctrl or command key is held down
		// which could indicate the link is being opened in a new tab
		if (e.metaKey || e.ctrlKey) {
			console.log('ctrl or meta key pressed');
			var newtab = true;
		}
		// If it is not a new tab, we need to delay the loading
		// of the new link for a just a second in order to give the
		// Google track event time to fully fire
		if (!newtab) {
			console.log('default prevented');
			e.preventDefault();
                        console.log('loading link after brief timeout');
			//setTimeout('document.location = "' + url + '"', 100);
		}
	}
	else {
		console.log('internal link click');
	}
});

Compressed Version

This is the same code as above, but with comments and console.logs stripped out:

// Outbound Link Tracking with Google Analytics
// Requires jQuery 1.7 or higher (use .live if using a lower version)
$("a").on('click',function(e){
	var url = $(this).attr("href");
	if (e.currentTarget.host != window.location.host) {
		_gat._getTrackerByName('demand')._trackEvent("Outbound Links", e.currentTarget.host, url, 0);
		if (e.metaKey || e.ctrlKey) {
		     var newtab = true;
		}
		if (!newtab) {
		     e.preventDefault();
		     setTimeout('document.location = "' + url + '"', 100);
		}
	}
});

Viewing the Results

To see if your custom tracking events are firing correctly, check your Google Analytics dashboard under “Content > Events > Overview”. It may take a couple hours before you start to see the results. In this screenshot you can clearly see when the tracking began:

In WordPress

If you are using a plugin for Google Analytics, like Google Analyticator, there is a settings fields where you can add javascript to be included with the tracker. You can also just include it with your other scripts.

Another option to track links easily in WordPress is to use the stats from Jetpack, which give you outbound click data by default.

Instead, set up the tracking variables and just call the Google script once. Here’s what I’ve used:

<script>
var _gaq=[
	['_setAccount', 'UA-1111111-1'],['_trackPageview'],['_trackPageLoadTime'],
	['secondTracker._setAccount', 'UA-2222222-1'],['secondTracker._trackPageview'],['secondTracker._trackPageLoadTime']
];
(function(d, t) {
     var g = d.createElement(t),
         s = d.getElementsByTagName(t)[0];
    g.src = '//www.google-analytics.com/ga.js';
    s.parentNode.insertBefore(g, s);
}(document, 'script'));
</script>

Notes:

• This is an optimized version of the GA script from Mathias Bynens.
• You can include more than two. Just copy the secondTracker code and repeat.
• The “secondTracker” label can be changed to anything you like.
• _trackPageLoadTime isn’t required, but _trackPageview is.
• The code should be placed right before the close of the body tag.

Ajax can also be used to load more significant amounts of content, but it gets more complicated. URLs don’t update by default, which is important if someone wants to bookmark that particular post or share it. Browser navigation buttons for “Back” and “Forward” can also be an issue.

Thankfully there are HTML5 methods for dealing with browser history and states, and an awesome jquery plugin that provides some fallback for older browsers. This tutorial will walk you through the code required for a theme that makes extensive use of ajax and also point you to some live demos.

When to Use Ajax

Sites that use ajax well generally have a good reason for it. One of my favorite ajax sites is Designers MX, which hosts music mixes. By using ajax the site is able to keep the music playing uninterrupted while users navigate through the site.

When animations could be interrupted by a fresh page load, ajax is also extremely helpful. I developed a site for Byron Reece that features a large slider at the top for selecting posts. If the user had to load a new page after clicking on an item on the slider the site interaction would not have worked.

Sites that have heavy initial page weight but then just need to load in small snippets can benefit enormously from ajax. An example might be a gallery site that displays a huge amount of thumbnails initially, but then just needs a single request for a larger image when the user selects it.

How URL Pushstates Work

You’ll notice on the Byron Reece site that when you click on an a different item in the slider the URL updates even though a fresh page load is not happening. In modern browsers that support HTML5 push states, this url looks like any other you would normally use on the web. In legacy browsers, like IE8, it reverts to the hash url structure (#!).

Most of this URL magic is handled by history.js. All you do is send a title and url for the new browser state when the ajax event happens.

A Simple Example

I coded out a much simpler example of an AJAX driven site using the TwentyEleven theme as a base for an example. Any links clicked in the top navigation menu will load the new content from that link into the #primary and #secondary divs.

I wouldn’t suggest building a site like this, as you don’t get a whole lot of upside for using ajax here, but it works well for demonstration purposes.

Enqueue the Required Javascript

For the pushstates to work as I used them, you’ll need to load history.js. There is a compressed version for use with jquery that can be downloaded here. I also load another javascript file that contains the custom code, which I saved in ajax_demo_init.js.

/*
 * Loads the scripts that are required for push_states to work.
 *
 * https://github.com/balupton/History.js
 *
 */
function ajax_demo_init() {
	if ( !is_admin() ) {
		wp_deregister_script('historyjs');
		wp_register_script( 'historyjs', get_bloginfo( 'stylesheet_directory' ) . '/js/jquery.history.js', array( 'jquery' ), '1.7.1' );
		wp_enqueue_script( 'historyjs' );
		wp_register_script( 'ajax_demo_init', get_bloginfo( 'stylesheet_directory' ) . '/js/ajax_demo_init.js', array( 'historyjs' ), false, true );
		wp_enqueue_script( 'ajax_demo_init' );
	}
}
add_action( 'wp_enqueue_scripts','ajax_demo_init' );

ajax_demo_init

This is the custom javascript that enables history.js, tells the site which link targets to load via ajax, and pushes the new browser states. I’ll post it as a block here, and then explain in more detail below:

jQuery(document).ready(function($) {
	// Establish Variables
	var
		History = window.History, // Note: Using a capital H instead of a lower h
		State = History.getState(),
		$log = $('#log');
	// If the link goes to somewhere else within the same domain, trigger the pushstate
	$('#access a').on('click', function(e) {
		e.preventDefault();
		var path = $(this).attr('href');
		var title = $(this).text();
		History.pushState('ajax',title,path);
	});
	// Bind to state change
	// When the statechange happens, load the appropriate url via ajax
	History.Adapter.bind(window,'statechange',function() { // Note: Using statechange instead of popstate
		load_site_ajax();
	});
	// Load Ajax
	function load_site_ajax() {
		State = History.getState(); // Note: Using History.getState() instead of event.state
		// History.log('statechange:', State.data, State.title, State.url);
		//console.log(event);
		$("#primary").prepend('<div id="ajax-loader"><h4>Loading...</h4></div>');
		$("#ajax-loader").fadeIn();
		$('#site-description').fadeTo(200,0);
		$('#content').fadeTo(200,.3);
		$("#main").load(State.url + ' #primary, #secondary', function(data) {
			/* After the content loads you can make additional callbacks*/
			$('#site-description').text('Ajax loaded: ' + State.url);
			$('#site-description').fadeTo(200,1);
			$('#content').fadeTo(200,1);
			// Updates the menu
			var request = $(data);
			$('#access').replaceWith($('#access', request));
		});
	}
});

Pushing the Title and URL

This snippet tells the site which links should be loaded by ajax (‘#access a’). To fully ajaxify a site you’d probably want it to detect external vs internal links, and load all the internal ones with ajax.

$('#access a').live('click', function(e) {
	e.preventDefault();
	var path = $(this).attr('href');
	var title = $(this).text();
	History.pushState('ajax',title,path);
});

The path variable is what sets the new url. The title is what will be at the top of the browser window and show up when bookmarked.

You might need to be a little careful with the title. You’ll notice in my Ajax Demo the full title is there on a fresh page load, but on an ajax load it drops site name from the title. To get it to match perfectly you’d have to tweak the title variable slightly.

Binding the Listener on Statechange

This idea took a little while for me to understand. When someone clicks on a link that you want to load via ajax, you don’t actually trigger any of the ajax on that click function. Instead, you have the click trigger a statechange event and pass it the needed variables for url and title.

The real work is done in the statechange listener. Here’s a real simple example with all the console log events uncommented so you can see what’s going on:

// Bind to state change
// When the statechange happens, load the appropriate url via ajax
History.Adapter.bind(window,'statechange',function() { // Note: Using statechange instead of popstate
     State = History.getState(); // Note: Using History.getState() instead of event.state
     History.log('statechange:', State.data, State.title, State.url);
     console.log(event);
});

(The above doesn’t actually load content, it just posts to the browser console.)

In the Ajax Demo, a click on “Example One” will display the following in the browser console:

statechange: [
Object
, "Example One", "http://themes.wptheming.com/ajax-demo/example-one/"]
MouseEvent

You can see the event was triggered by a mouseclick, and that “Example One” is the new title, “http://themes.wptheming.com/ajax-demo/example-one” is the URL that will be loaded.

Any functions in the statechange listener will also be fired when someone clicks the “back” or “forward” buttons in their browser.

Loading in the New Content via Ajax

The final piece is to actually load in the new content using ajax. If you’re unfamiliar with how this works, I’d also read the jQuery documentation the load function. For the TwentyEleven ajax example, we replace the #primary and #secondary divs with content from the new URL. This all happens inside the load_site_ajax function:

$("#main").load(State.url + ' #primary, #secondary', function(data) {
     /* After the content loads you can make additional callbacks*/
});

If you look at the original code, you’ll also notice that a couple other things I do to let the user know that new content is being loaded.

As soon as the ajax link is clicked, a loader gif is shown:

$("#primary").prepend('<div id="ajax-loader"><h4>Loading...</h4></div>');
$("#ajax-loader").fadeIn();

I also dim the content, so that the user is aware that it will change shortly:

$('#content').fadeTo(200,.3);

Once the content has loaded, the ajax loader disappears because the new content doesn’t have the ajax loader in #primary (remember, it was prepended using javascript). So, all that’s left to do is undim the new content:

$('#content').fadeTo(200,1);

One final issue I had, is that the menu items weren’t highlighting correctly because WordPress applies certain classes to them depending on which page it has loaded. When you load new content into #primary or #secondary and change the URL, the menu will keep the same classes it had on the initial page load. One way around that is to also reload the menu:

// Updates the menu
var request = $(data);
$('#access').replaceWith($('#access', request));

A Note on Browser Compatibility

Benjamin (the creator of history.js) wrote a great post about supporting url states in legacy browsers. By legacy, I really mean Internet Explorer 9 and below (IE10 is slated to support it).

There’s a couple issues with older browsers, but I think the main one is bookmarking. If a user visits the home page in IE8, then loads a secondary page via ajax, the URL will look something like this:

http://themes.wptheming.com/ajax-demo/#example-one/?&_suid=132434056033304790466820008113

However, if you visit that URL directly- it will only load the home page, not the page you thought you bookmarked (http://themes.wptheming.com/ajax-demo/example-one).

I worked out a method for detecting a hash and loading the correct content after the initial load, but it doesn’t work in modern browsers- and sort of defeats the point of using ajax since it is now loading the initial page content and then new page content:

// For legacy browser support
// Only checks for hashes, so more robust support might be needed if you use anchors
if (window.location.hash) {
	load_site_ajax();
}

I’m sure someone has worked out a better way to do this! Please share it in the comments.

Additional Thing to Watch Out For

If you use social buttons like Google+ or Twitter, don’t expect them to automatically update with the new URL. I’ll write a follow-up post about how to get those working.

A lot of WordPress themes use body classes for styling. These won’t update on an ajax load.

Did I Miss Something?

If you see anywhere I can improve the code, please share it in the comments- especially about legacy browser support.

Download the AJAX Demo Code

If you’d like to get the Ajax Demo theme code, it’s available as a $5 download. The javascript code is the same as posted in this tutorial- just conveniently bundled into a theme version.

Purchase the “Ajax Demo” Theme for $5
(And thanks for supporting the site!)

If you need an out-of-the-box solution and aren’t interested in customizing the code, one of these plugins might be a quicker solution:

• The Events Calender
• Calendar Press
• GigPress (For Musicans)

The Basics

Building an events post combines three concepts:

• Custom Post Types
• Custom Metaboxes
• Advanced Meta Queries

Download the Code

I built a working plugin with everything I describe here up on GitHub. You can install the “Events Posts” plugin, and move the file “archive-events.php” into your theme in order to follow along.

Download the Code on GitHub

The Post Type

I create a new post type for events. You could also use a regular post if you don’t want a separation between your regular posts and event posts, but for the purposes of this tutorial it makes it easier to explain.

If you’re not familiar with custom post types, read Justin Tadlock’s excellent write up.

Here’s how you would create a custom post type for events (view on GitHub):

function ep_eventposts() {
	/**
	 * Enable the event custom post type
	 * http://codex.wordpress.org/Function_Reference/register_post_type
	 */
	$labels = array(
		'name' => __( 'Events', 'eventposttype' ),
		'singular_name' => __( 'Event', 'eventposttype' ),
		'add_new' => __( 'Add New Event', 'eventposttype' ),
		'add_new_item' => __( 'Add New Event', 'eventposttype' ),
		'edit_item' => __( 'Edit Event', 'eventposttype' ),
		'new_item' => __( 'Add New Event', 'eventposttype' ),
		'view_item' => __( 'View Event', 'eventposttype' ),
		'search_items' => __( 'Search Events', 'eventposttype' ),
		'not_found' => __( 'No events found', 'eventposttype' ),
		'not_found_in_trash' => __( 'No events found in trash', 'eventposttype' )
	);
	$args = array(
    	'labels' => $labels,
    	'public' => true,
		'supports' => array( 'title', 'editor', 'thumbnail', 'comments' ),
		'capability_type' => 'post',
		'rewrite' => array("slug" => "event"), // Permalinks format
		'menu_position' => 5,
		'menu_icon' => plugin_dir_url( __FILE__ ) . '/images/calendar-icon.gif',  // Icon Path
		'has_archive' => true
	);
	register_post_type( 'event', $args );
}
add_action( 'init', 'ep_eventposts' );

The Metaboxes

For the user to be able to select an event start time or event end time, you’ll need to define a couple meta boxes. My example puts two metaboxes in the right side of the post, and one for location under the main editor.

I’ve written other tutorials about metaboxes if you need a more in-depth overview.

This is a long code snippet, but the basic idea is that we get the current time and populate the metaboxes of a fresh post with that. When someone saves a post, it checks that they have permissions to edit, and then overwrites the metabox data if it has changed.

/**
 * Adds event post metaboxes for start time and end time
 * http://codex.wordpress.org/Function_Reference/add_meta_box
 *
 * We want two time event metaboxes, one for the start time and one for the end time.
 * Two avoid repeating code, we'll just pass the $identifier in a callback.
 * If you wanted to add this to regular posts instead, just swap 'event' for 'post' in add_meta_box.
 */
function ep_eventposts_metaboxes() {
	add_meta_box( 'ept_event_date_start', 'Start Date and Time', 'ept_event_date', 'event', 'side', 'default', array( 'id' => '_start') );
	add_meta_box( 'ept_event_date_end', 'End Date and Time', 'ept_event_date', 'event', 'side', 'default', array('id'=>'_end') );
	add_meta_box( 'ept_event_location', 'Event Location', 'ept_event_location', 'event', 'normal', 'default', array('id'=>'_end') );
}
add_action( 'admin_init', 'ep_eventposts_metaboxes' );
// Metabox HTML
function ept_event_date($post, $args) {
	$metabox_id = $args['args']['id'];
	global $post, $wp_locale;
	// Use nonce for verification
	wp_nonce_field( plugin_basename( __FILE__ ), 'ep_eventposts_nonce' );
	$time_adj = current_time( 'timestamp' );
	$month = get_post_meta( $post->ID, $metabox_id . '_month', true );
	if ( empty( $month ) ) {
		$month = gmdate( 'm', $time_adj );
	}
	$day = get_post_meta( $post->ID, $metabox_id . '_day', true );
	if ( empty( $day ) ) {
		$day = gmdate( 'd', $time_adj );
	}
	$year = get_post_meta( $post->ID, $metabox_id . '_year', true );
	if ( empty( $year ) ) {
		$year = gmdate( 'Y', $time_adj );
	}
	$hour = get_post_meta($post->ID, $metabox_id . '_hour', true);
    if ( empty($hour) ) {
        $hour = gmdate( 'H', $time_adj );
    }
    $min = get_post_meta($post->ID, $metabox_id . '_minute', true);
    if ( empty($min) ) {
        $min = '00';
    }
	$month_s = '<select name="' . $metabox_id . '_month">';
	for ( $i = 1; $i < 13; $i = $i +1 ) {
		$month_s .= "\t\t\t" . '<option value="' . zeroise( $i, 2 ) . '"';
		if ( $i == $month )
			$month_s .= ' selected="selected"';
		$month_s .= '>' . $wp_locale->get_month_abbrev( $wp_locale->get_month( $i ) ) . "</option>\n";
	}
	$month_s .= '</select>';
	echo $month_s;
	echo '<input type="text" name="' . $metabox_id . '_day" value="' . $day  . '" size="2" maxlength="2" />';
    echo '<input type="text" name="' . $metabox_id . '_year" value="' . $year . '" size="4" maxlength="4" /> @ ';
    echo '<input type="text" name="' . $metabox_id . '_hour" value="' . $hour . '" size="2" maxlength="2"/>:';
    echo '<input type="text" name="' . $metabox_id . '_minute" value="' . $min . '" size="2" maxlength="2" />';
}
function ept_event_location() {
	global $post;
	// Use nonce for verification
	wp_nonce_field( plugin_basename( __FILE__ ), 'ep_eventposts_nonce' );
	// The metabox HTML
	$event_location = get_post_meta( $post->ID, '_event_location', true );
	echo '<label for="_event_location">Location:</label>';
	echo '<input type="text" name="_event_location" value="' . $event_location  . '" />';
}
// Save the Metabox Data
function ep_eventposts_save_meta( $post_id, $post ) {
	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE )
		return;
	if ( !isset( $_POST['ep_eventposts_nonce'] ) )
		return;
	if ( !wp_verify_nonce( $_POST['ep_eventposts_nonce'], plugin_basename( __FILE__ ) ) )
		return;
	// Is the user allowed to edit the post or page?
	if ( !current_user_can( 'edit_post', $post->ID ) )
		return;
	// OK, we're authenticated: we need to find and save the data
	// We'll put it into an array to make it easier to loop though
	$metabox_ids = array( '_start', '_end' );
	foreach ($metabox_ids as $key ) {
		$events_meta[$key . '_month'] = $_POST[$key . '_month'];
	    $events_meta[$key . '_day'] = $_POST[$key . '_day'];
	        if($_POST[$key . '_hour']<10){
	             $events_meta[$key . '_hour'] = '0'.$_POST[$key . '_hour'];
	         } else {
	               $events_meta[$key . '_hour'] = $_POST[$key . '_hour'];
	         }
	    $events_meta[$key . '_year'] = $_POST[$key . '_year'];
	    $events_meta[$key . '_hour'] = $_POST[$key . '_hour'];
	    $events_meta[$key . '_minute'] = $_POST[$key . '_minute'];
	    $events_meta[$key . '_eventtimestamp'] = $events_meta[$key . '_year'] . $events_meta[$key . '_month'] . $events_meta[$key . '_day'] . $events_meta[$key . '_hour'] . $events_meta[$key . '_minute'];
    }
	// Add values of $events_meta as custom fields
	foreach ( $events_meta as $key => $value ) { // Cycle through the $events_meta array!
		if ( $post->post_type == 'revision' ) return; // Don't store custom data twice
		$value = implode( ',', (array)$value ); // If $value is an array, make it a CSV (unlikely)
		if ( get_post_meta( $post->ID, $key, FALSE ) ) { // If the custom field already has a value
			update_post_meta( $post->ID, $key, $value );
		} else { // If the custom field doesn't have a value
			add_post_meta( $post->ID, $key, $value );
		}
		if ( !$value ) delete_post_meta( $post->ID, $key ); // Delete if blank
	}
}
add_action( 'save_post', 'ep_eventposts_save_meta', 1, 2 );
/**
 * Helpers to display the date on the front end
 */
// Get the Month Abbreviation
function eventposttype_get_the_month_abbr($month) {
    global $wp_locale;
    for ( $i = 1; $i < 13; $i = $i +1 ) {
                if ( $i == $month )
                    $monthabbr = $wp_locale->get_month_abbrev( $wp_locale->get_month( $i ) );
                }
    return $monthabbr;
}
// Display the date
function eventposttype_get_the_event_date() {
    global $post;
    $eventdate = '';
    $month = get_post_meta($post->ID, '_month', true);
    $eventdate = eventposttype_get_the_month_abbr($month);
    $eventdate .= ' ' . get_post_meta($post->ID, '_day', true) . ',';
    $eventdate .= ' ' . get_post_meta($post->ID, '_year', true);
    $eventdate .= ' at ' . get_post_meta($post->ID, '_hour', true);
    $eventdate .= ':' . get_post_meta($post->ID, '_minute', true);
    echo $eventdate;
}

Displaying Event Posts on Archive Pages

To display event posts on archive pages you should run a pre_get_posts filter (hat tip to Bill Erickson). This example filter will display the event posts five per page, sorted by their _start_eventtimestamp meta key in ascending order, and only display posts that have a start time that is later than the current time.

The following code could be placed in functions.php. For the example plugin, it’s already in event-posts.php.

/**
 * Customize Event Query using Post Meta
 *
 * @link http://www.billerickson.net/customize-the-wordpress-query/
 * @param object $query data
 *
 */
function ep_event_query( $query ) {
	// http://codex.wordpress.org/Function_Reference/current_time
	$current_time = current_time('mysql');
	list( $today_year, $today_month, $today_day, $hour, $minute, $second ) = split( '([^0-9])', $current_time );
	$current_timestamp = $today_year . $today_month . $today_day . $hour . $minute;
	global $wp_the_query;
	if ( $wp_the_query === $query && !is_admin() && is_post_type_archive( 'event' ) ) {
		$meta_query = array(
			array(
				'key' => '_start_eventtimestamp',
				'value' => $current_timestamp,
				'compare' => '>'
			)
		);
		$query->set( 'meta_query', $meta_query );
		$query->set( 'orderby', 'meta_value_num' );
		$query->set( 'meta_key', '_start_eventtimestamp' );
		$query->set( 'order', 'ASC' );
		$query->set( 'posts_per_page', '5' );
	}
}
add_action( 'pre_get_posts', 'ep_event_query' );

Other Queries

If you just wanted to display the event posts in the sidebar or on a different template (and not worry about paging), you could do something like this:

 $args = array( 'post_type' => 'event',
'meta_key' => '_start_eventtimestamp',
'orderby'=> 'meta_value_num',
'order' => 'ASC',
'posts_per_page' => 20,
 );
 $events = new WP_Query( $args );
if ( $events->have_posts() ) :
	echo '<ul>';
	while ( $events->have_posts() ) : $events->the_post();
		echo '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a></li>';
	endwhile;
	echo '</ul>';
endif;

Extending

This tutorial isn’t meant to be a full-fledged plugin- just an example to get you started. Several improvements could be made, such as using a jquery datepicker to select the date (or even just making sure you end time is after your start time and a valid date). If your primary users are in the United States or other countries on a 12-hour clock, you might want to use an AM/PM selector.

If you’re interested in learning more, check out Noel Tock’s excellent events tutorial which covers some of these examples.

Tim Thumb Hacker

Several of my websites were hacked this week using the TimThumb exploit. The issue has been known for a couple weeks now.

Although I had updated the majority of sites and had notified former clients, I still hadn’t gotten to some of the smaller sites yet- like my girlfriend’s food blog.

And word to the wise, your girlfriend’s food blog should always be top priority.

Hackers are using a variety of techniques to hijack WordPress sites right now, but this is how I cleaned up the ones on my server.

Make Backup of Everything

Common sense, but worth mentioning again. You never know when you might accidentally delete a directory you need or wipe part of the database. Most cPanels wills let you easily export a copy of the database. And it’s a lot easier to download a second copy or your files then rebuild them all from scratch.

Get Shell Access to Your Host

If you only have one site, this may not be necessary. But I have over twenty WordPress installs running on my server and I wanted to find all the files that were compromised and fix them quickly. Most hosts offer shell access. With BlueHost, I just had to go into my control panel and enable it.

Here’s BlueHost’s instructions for setting up shell access and for logging in via shell.

Fix TimThumb Vulnerability

You can download the latest version of TimThumb with the security fixes here: http://timthumb.googlecode.com/svn/trunk/timthumb.php (Just save the file out).

Replace any instances of TimThumb.php on your server with the new version. WooThemes used the name “thumb.php” for this file, so you should also look for that.

If you have shell access you can do a quick search to find all instances of timthumb with:

find *  -iname 'timthumb*' -ls

or

find *  -iname 'thumb.php' -ls (for WooTheme versions)

In many cases I found themes that were not being used and just deleted them directly:

rm -rf path/to/theme

Most theme companies have also already released fixes, so you could also get the latest version directly from them and replace your current theme.

Clean Up After the Hack

DISCLAIMER: I don’t consider myself to be a security expert, but these are the steps I took to clean up my site. If anyone else has additional recommendations, please drop them in the comments or post a link.

1. I wiped the entire directory of the hacked site since I didn’t know which files has been added or compromised.
2. I changed my database passwords and uploaded a new clean version of WordPress with a fresh wp-config.php file.

If you’re using shell this is very quick (http://codex.wordpress.org/Installing_WordPress):


wget http://wordpress.org/latest.tar.gz
tar -xzvf latest.tar.gz

3. I manually checked my backed-up “wp-content” to make sure no odd new files had been added. I specifically checked for files that other folks have reported as being exploited, like:
   
   

   /wp-content/uploads/feed-file.php
   /wp-content/uploads/feed-files.php
   /wp-content/themes/******/cache/.htaccess
   

   The file in my case was:

   /wp-content/data.php
   

   There’s an excellent post that goes into the hacking methods in more detail and suggests other files to check at: http://redleg-redleg.blogspot.com/2011/08/malware-hosted-newportalsecom.html

4. I also grepped the backed-up “wp-content” directory for any files with base64_decode. There are legitimate reasons to have base64_decode in a file, but if you don’t know where the file came from, or what it does, find out.

   Here’s how you grep a directory:

   grep -r base64_decode *

   If you want to grep your entire server, try

   grep -r --exclude={wp-app.php,class-simplepie.php,class-IXR.php} base64_decode *

5. When I was reasonably confident my backup wp-content directory was clean, I re-uploaded it.
6. I reset my file permissions as specified by WordPress in the codex
7. I logged back into WordPress and reset the admin passwords.
8. I reset my permalinks to be completely sure the htaccess was overwritten.

Anything I Missed?

If anyone else has other suggestions or recommendations, please post them below.

And please update ALL sites that might have the TimThumb vulnerability. Your girlfriend will thank you.

I’ve held onto to the plugin for a while in GitHub since it’s an easy thing for any developer to build out- but I’ve recently been thinking that a standard plugin in the repository might be beneficial as it could make more themes more portable. (Especially for users of my Portfolio Press theme)

And since I expect people to hack on this a bit as well, I wanted to do a walk through of the code.

Plugin Header

/*
Plugin Name: Portfolio Post Type
Plugin URI: http://www.wptheming.com
Description: Enables a portfolio post type and taxonomies.
Version: 0.1
Author: Devin Price
Author URI: http://wptheming.com/portfolio-post-type/
License: GPLv2
*/

Explanation: All plugins need to have basic header data in order to show up in plugin admin page. If you don’t want to get updates to the plugin (I don’t expect many), change the name to something different. Shoot, feel free to change any of this information- GPL baby!

Enable the Portfolio Post Type

function portfolioposttype() {
	/**
	 * Enable the Portfolio custom post type
	 * http://codex.wordpress.org/Function_Reference/register_post_type
	 */
	$labels = array(
		'name' => __( 'Portfolio', 'portfolioposttype' ),
		'singular_name' => __( 'Portfolio Item', 'portfolioposttype' ),
		'add_new' => __( 'Add New Item', 'portfolioposttype' ),
		'add_new_item' => __( 'Add New Portfolio Item', 'portfolioposttype' ),
		'edit_item' => __( 'Edit Portfolio Item', 'portfolioposttype' ),
		'new_item' => __( 'Add New Portfolio Item', 'portfolioposttype' ),
		'view_item' => __( 'View Item', 'portfolioposttype' ),
		'search_items' => __( 'Search Portfolio', 'portfolioposttype' ),
		'not_found' => __( 'No portfolio items found', 'portfolioposttype' ),
		'not_found_in_trash' => __( 'No portfolio items found in trash', 'portfolioposttype' )
	);
	$args = array(
    	'labels' => $labels,
    	'public' => true,
		'supports' => array( 'title', 'editor', 'thumbnail', 'comments' ),
		'capability_type' => 'post',
		'rewrite' => array("slug" => "portfolio"), // Permalinks format
		'menu_position' => 5,
		'has_archive' => true
	);
	register_post_type( 'portfolio', $args);
}
add_action( 'init', 'portfolioposttype' );

This is the basic code needed to register the portfolio post type. I’ve wrapped it all in one function that fires on init. For a deeper explanation of all the arguments ($args) check out the codex post.

Register Taxonomies

Wrapped in that same function I also register two taxonomies for categories and tags. Since that code is long, and basically just a bunch of labels I’ll point you to the actual code on GitHub. If you don’t want taxonomies, you don’t actually need that code.

Use Post Thumbnails

If you want your post type to be able to use thumbnails, you’ll need to register it:

// Allow thumbnails to be used on portfolio post type
add_theme_support( 'post-thumbnails', array( 'portfolio' ) );

View Thumbnail Images in Column View of Dashboard

For something like portfolio items, it’s nice to see the images when you’re scanning posts in the dashboard. I wrote about how that functionality works in a separate post. That’s handled by the code listed under:

/**
 * Add Columns to Portfolio Edit Screen
 * http://wptheming.com/2010/07/column-edit-pages/
 */
 

Display a Custom Icon for Portfolio Menus

I was lucky enough to get Ben Dunkle (the designer of the WordPress icons), to make some portfolio icons for me. To display theme out in the dasboard, here’s the code:

/**
 * Displays the custom post type icon in the dashboard
 */
function portfolioposttype_portfolio_icons() {
    ?>
    <style type="text/css" media="screen">
        #menu-posts-portfolio .wp-menu-image {
            background: url(<?php echo plugin_dir_url( __FILE__ ); ?>images/portfolio-icon.png) no-repeat 6px 6px !important;
        }
		#menu-posts-portfolio:hover .wp-menu-image, #menu-posts-portfolio.wp-has-current-submenu .wp-menu-image {
            background-position:6px -16px !important;
        }
		#icon-edit.icon32-posts-portfolio {background: url(<?php echo plugin_dir_url( __FILE__ ); ?>images/portfolio-32x32.png) no-repeat;}
    </style>
<?php }
add_action( 'admin_head', 'portfolioposttype_portfolio_icons' );

I also wrote about custom post type icons in more depth on this post.

Custom Meta Boxes

This plugin doesn’t register any custom meta boxes, but those obviously might be useful if you want to include a link a website, or a purchase button, etc. If you’re interested in doing that- see my post on adding custom meta boxes to post types.

Download

• WordPress.org
• GitHub

Example Admin Notices

Display a Standard Notice

function my_admin_notice(){
    echo '<div class="updated">
       <p>I am a little yellow notice.</p>
    </div>';
}
add_action('admin_notices', 'my_admin_notice');

Since this div is classed “updated” the notice will display yellow. If the class is changed to “error” it displays in red.

How To Make a Dismissible Notice

With a little more work it’s also possible to display a notice stays present until the user clicks to ignore it. This could be a good way to ensure the user sees the message but also won’t get annoyed by it.

The following example was adapted from the AddThis plugin. I also use something similar in the Options Framework.

If a user clicks to hide the notice, it will save their preference in the user meta.

/* Display a notice that can be dismissed */
add_action('admin_notices', 'example_admin_notice');
function example_admin_notice() {
	global $current_user ;
        $user_id = $current_user->ID;
        /* Check that the user hasn't already clicked to ignore the message */
	if ( ! get_user_meta($user_id, 'example_ignore_notice') ) {
        echo '<div class="updated"><p>';
        printf(__('This is an annoying nag message.  Why do people make these? | <a href="%1$s">Hide Notice</a>'), '?example_nag_ignore=0');
        echo "</p></div>";
	}
}
add_action('admin_init', 'example_nag_ignore');
function example_nag_ignore() {
	global $current_user;
        $user_id = $current_user->ID;
        /* If user clicks to ignore the notice, add that to their user meta */
        if ( isset($_GET['example_nag_ignore']) && '0' == $_GET['example_nag_ignore'] ) {
             add_user_meta($user_id, 'example_ignore_notice', 'true', true);
	}
}

Display Notices Only On Certain Admin Pages

If possible, target the notice to only appear on certain pages where the user needs to see them. You can do that by using the $pagenow global variable.

For example, this notice will only appear on the plugins page:

function my_admin_notice(){
    global $pagenow;
    if ( $pagenow == 'plugins.php' ) {
         echo '<div class="updated">
             <p>This notice only appears on the plugins page.</p>
         </div>';
    }
}
add_action('admin_notices', 'my_admin_notice');

Check User Role Before Displaying a Notice

Notices should only be displayed to users that can actually do something about them. For instance, if the user cannot edit theme options, there’s no point in displaying a notice about it.

Here’s some common roles checks you might want to do:

if ( current_user_can( 'install_plugins' ) )
if ( current_user_can( 'manage_options' ) )
if ( current_user_can( 'edit_theme_options' ) )

Notice Etiquette

Notices can be annoying, so be careful with how you use them. Keep the text short and try not display more than one. Use sparingly.

Other Resources

• http://theme.it/how-to-display-an-admin-notice-for-required-theme-plugins
• http://codex.wordpress.org/Plugin_API/Action_Reference/admin_notices

Unfortunately, a couple things that worked in previous versions will break with this release unless theme code is updated. I debated these changes quite a bit but decided it was best to do this while the plugin is still relatively young and would affect the least amount of people.

Validation Filters

Validation filters are the most exciting update in the Options Framework. Not only is there better sanitization (read security), it’s also now possible to change the default validation on any input without hacking the plugin directly.

Several users had mentioned that they wanted to enter some html in the textareas. I updated this so $allowedtags can be used. But if you wanted a different sanitization method, the default can now be removed and a new one added in via your themes functions. (Edit: $allowedposttags might be used soon instead)

Since, “embed” is not one of the $allowedtags- here’s how you could remove the default santization from a text area and allow “embed” to be used:

/*
 * This is an example of how to override a default filter
 * for 'textarea' sanitization and use a different one.
 */
add_action('admin_init','optionscheck_change_santiziation', 100);
function optionscheck_change_santiziation() {
	remove_filter( 'of_sanitize_textarea', 'of_sanitize_textarea' );
	add_filter( 'of_sanitize_textarea', 'of_sanitize_textarea_custom' );
}
function of_sanitize_textarea_custom($input) {
	global $allowedtags;
        $of_custom_allowedtags["embed"] = array(
             "src" => array(),
             "type" => array(),
             "allowfullscreen" => array(),
             "allowscriptaccess" => array(),
             "height" => array(),
	     "width" => array()
	);
        $of_custom_allowedtags = array_merge($of_custom_allowedtags, $allowedtags);
        $output = wp_kses( $input, $of_custom_allowedtags);
	return $output;
}

Allow Script and Embed Tags

A lot of folks have been asking how to include all the $allowedpsttags in addition to script and embed tags. Here’s how you would do it (hat tip Jake Caputo):

/*
 * This is an example of how to override a default filter
 * for 'textarea' sanitization and $allowedposttags + embed and script.
 */
add_action('admin_init','optionscheck_change_santiziation', 100);
function optionscheck_change_santiziation() {
    remove_filter( 'of_sanitize_textarea', 'of_sanitize_textarea' );
    add_filter( 'of_sanitize_textarea', 'custom_sanitize_textarea' );
}
function custom_sanitize_textarea($input) {
    global $allowedposttags;
    $custom_allowedtags["embed"] = array(
      "src" => array(),
      "type" => array(),
      "allowfullscreen" => array(),
      "allowscriptaccess" => array(),
      "height" => array(),
          "width" => array()
      );
      $custom_allowedtags["script"] = array();
      $custom_allowedtags = array_merge($custom_allowedtags, $allowedposttags);
      $output = wp_kses( $input, $custom_allowedtags);
    return $output;
}

Checkbox Code Has Changed

The most noticeable change in version 0.6 is how checkbox data is stored. The reason it’s the most noticeable is because it’s the one most likely to break a current implementation. Instead of storing checkbox data as “true” or “false”, I’ve changed it to “1″ or “0″, which is how WordPress itself stores checkbox values and much smarter way to do it. I’ve written about this more in another post called “Checkboxes and Booleans”.

If you currently are using checkboxes in your theme, you should update options.php to use a default value of “0″ or “1″. You should also update how the theme reads checkbox data to something like:

if ( of_get_option('checkbox_option', "0") ) {
	do_action();
}

Helper Function Returns Boolean False by Default

Instead of having the helper function of_get_option return the string “false” by default, I’ve updated it to return the boolean false (thanks so a suggestion from @sawyerh). Again, there’s more about this in my post on booleans. This should just make it easier to check if options are saved in the database. This change isn’t likely to break something if it isn’t updated, but the new code for your theme should look like this:

if ( !function_exists( 'of_get_option' ) ) {
function of_get_option($name, $default = false) {
	$optionsframework_settings = get_option('optionsframework');
	// Gets the unique option id
	$option_name = $optionsframework_settings['id'];
	if ( get_option($option_name) ) {
		$options = get_option($option_name);
	}
	if ( !empty($options[$name]) ) {
		return $options[$name];
	} else {
		return $default;
	}
}
}

Better Handling of Option Arrays

I updated the code for how arrays of options (like multicheckbox, background, and typography) are processed and stored. I don’t think should affect current users- but it’s something to keep an eye on. The new code allows the options to be stored directly into the array rather than having an additional step in the validation to process it.

Better Display of Messages

For anyone who dug into the code of 0.5, you probably saw my very awkward way of displaying the “Options Reset” and “Options Saved” messages. I had an option in the database for saving the message which was set when the form was submitted and then later cleared after the message was displayed.

By digging through WordPress core I found a more elegant way to do it. At the top of the options page I now use settings_errors(), which automatically displays any messages.

The messages are set in optionsframework_validate() as it processes the form. So, the reset message it now set like so:

// If the reset button was clicked
	if (!empty($_POST['reset'])) {
		// If options are deleted sucessfully update the error message
		if (delete_option($option_name) ) {
			add_settings_error('options-framework', 'restore_defaults', __('Default options restored.'), 'updated fade');
		}
	}

Thanks and Credits

I owe a big thanks to Michael Fields for this release. He advised me on how to implement the validation filters and did a thorough code review which caught many of the html escaping errors. If you need a really solid WordPress developer to check your code, I’d highly recommend him.

I was only able to have a code review done thanks to several generous donations. Having cash to spend on a third party code check was extremely helpful, made the plugin much stronger, and was well spent! If you use the plugin and can contribute, a PayPal donation will make my day.

And finally, several people have been helping out with testing and development on GitHub. I really appreciate it! I’m probably leaving someone out, but big thanks to @mantone, @rejithomas, @sawyerh, @samargulies, @mfields, @adampickeringq, @djevrek, @utkarshkukreti, @celtic7, @helgatheviking, @johnraz, @jmilone, @thumbnet, and @pastorjack.

Update: Version 0.6 has been released

The way to get around this, or the way that I did, is to automatically assume all checkboxes in a form are unchecked unless your $_POST data explicitly tells you otherwise. In the Options Framework this required an extra step as I was looping through my options array and validating the data from the $_POST:

function optionsframework_validate($input) {
if (!empty($_POST['update'])) {
     // Get the options array defined for the form
     $options = optionsframework_options();
     foreach ($options as $option) {
          $id = $option['id'];
          //  Set the check box to "0" by default
          if ( 'checkbox' == $option['type'] && ! isset( $input[$id] ) ) {
               $input[$id] = "0";
           }

In the above code I’m setting any checkboxes that weren’t set in the form (and therefore weren’t checked) to “0″, and combining with all the other form data ($input) that was sent in the $_POST request. That way I have a complete set of checkboxes available in my $input rather than just the ones that were checked.

How to Store Checkbox State in the Database

The other main issue I had was how to store the checkbox data in the database. In the early versions of the Options Framework I saved checkbox data as either “true” or “false”. This was fine as long as I always evaluated the option (e.g. if ( get_option(“checkbox”) == “false”) ) { do something }).

However, this caused a problem if I wanted to call the option directly, because if “checkbox” is set to “false”, get_option(“checkbox”) returns true. Confused?

“False” (notice the quotes) is a string not a boolean, and most strings return true. If the option “checkbox” was set to “pancake”, that would also return true.

This little script checks 11 values and gives their boolean result:

$booleancheck = array(1,0,-1,"1","0",false,true,'false','true',"randomstring","");
echo '<ul>';
foreach ($booleancheck as $key) {
     echo '<li>'. $key.': ';
     if ($key) {
          echo "True";
      }
      else {
           echo "False";
      }
      echo '</li>';
      }
echo '</ul>';

You’ll see that “0″,”1″ will return false and true respectively regardless of whether they are sent as a string or an integer- and that’s the way I eventually decided to save checkbox data.

I also should have studied the WordPress core options a little earlier because that’s how it does it. If you pull up /wp-admin/options.php of your WordPress site you’ll see all check boxes either saved as “0″ or “1″.