Author: Kirk Wight

I am a Code Wrangler at Automattic, helping make WordPress.com the best it can be. Pender Island, British Columbia, Canada is where I call home. Lover, not a fighter.

Working with the Eventbrite API Plugin

Eventbrite and WordPress are the perfect fit, but until now, integrating the two has not been for the faint of heart. In early 2014, Eventbrite announced its new upcoming REST API, and this became the perfect opportunity to give theme developers an easy-to-use set of tools for working with Eventbrite events: the Eventbrite API plugin.

The plugin gives theme developers three ways to interact with the Eventbrite API:

  • Theme support
  • The Eventbrite_Query class
  • Helper functions

Theme Support

While the Eventbrite API plugin can display events in any theme, events look their best if the theme declares support and provides tailored templates. This simple process guarantees that events fit perfectly with the theme design, and adding support should take no more than ten minutes.

  1. Add a support declaration, hooked to after_setup_theme. There are no arguments, and usually this can be added to a theme’s existing setup function. 
    function themeslug_setup() {

	...

	/**
	 * Add theme support for the Eventbrite API plugin.
	 * See: https://wordpress.org/plugins/eventbrite-api/
	 */
	add_theme_support( 'eventbrite' );
}
add_action( 'after_setup_theme', 'themeslug_setup' );
  2. Create an eventbrite folder in your theme, and copy over the plugin’s main template files (tmpl/eventbrite-index.php and tmpl/eventbrite-single.php).
  3. Compare the markup in eventbrite-index.php to your own index.php and adjust as necessary. Also, verify that your markup for archive titles matches the Eventbrite template’s page title. The Eventbrite templates don’t use template parts for the post markup, so you may need to compare with content.php or the like. Of course, there’s no reason you couldn’t add a content-eventbrite.php to your theme, if you prefer.
  4. Repeat step 3 with eventbrite-single.php and your own single template.

That’s it! If support is declared, the plugin will use those templates if they exist, or fall back to the plugin’s templates. To see some custom templates in action, check out any of the Twenty* default themes; their templates are included in the plugin.

Eventbrite integration with Twenty Fifteen.
Eventbrite integration with Twenty Fifteen.

The Eventbrite_Query Class

It was important to us that working with the Eventbrite API plugin should be a simple and familiar process for theme developers, with a low barrier to entry. With that in mind, we developed the Eventbrite_Query class, so fetching and displaying events is as simple as making a secondary loop (in fact, the class extends WP_Query). This allows for easy creation of special-purpose loops, widgets, creative page templates – any combination of events you want to display in a theme.

<?php
	// Get the next three unpublicized events for the Apollo Planetarium.
	$events = new Eventbrite_Query( apply_filters( 'eventbrite_query_args', array(
		'display_private' => true,
		'limit' => 3,
		'venue_id' => 6955925,
	) ) );

	if ( $events->have_posts() ) :
		while ( $events->have_posts() ) : $events->the_post(); ?>

There are a few things to keep in mind while working with Eventbrite_Query loops.

  • You can continue to use familiar template tags in event loops, such as the_post_thumbnail(), the_title(), the_content(), etc. They’ve simply been filtered to provide content from the current event.
  • For technical reasons, a few template tags need their Eventbrite equivalent, such as eventbrite_is_single() and eventbrite_edit_post_link().
  • Being a secondary loop, don’t forget to add wp_reset_postdata() at the end.
  • All of the plugin’s template tags are pluggable, and filters exist at various points for further customization.

Helper Functions

If you’re happy processing your own results, and just want an easy-to-use set of tools to handle the API requests, the included helper functions are for you. Each supported API endpoint has its own helper function, and these functions in turn use the Eventbrite_Manager class for the heavy lifting. Not only does this class make the actual API requests, but also handles validation and transients, so you can concentrate on results rather than mechanics.

The Eventbrite API plugin is developed on GitHub, and issues or questions can be posted there or in the forums. Additional info and documentation can be found here.

Along with the Eventbrite Services plugin, it’s never been easier or more fun to display events in your WordPress website. Let us know what you’re doing with Eventbrite, and tell us if there’s anything the Eventbrite API plugin can do to make your Eventbrite integrations easier for you!

The Eventbrite API plugin requires the Keyring plugin for managing OAuth2 authorization to Eventbrite. If you get stuck, check out our detailed instructions for getting connected to Eventbrite.

The Power of Eventbrite on WordPress

Eventbrite is the world’s premier event-management service, and we’re happy to announce two new ways to add Eventbrite events to your self-hosted WordPress site!

We’ve offered Eventbrite integration on WordPress.com for a while, with two dedicated themes. While this made getting your events on your WordPress site easier than ever, it wasn’t available to self-hosted users, and you were limited to only the two themes. Both of these issues are solved with new additions to the WordPress.org theme and plugin repositories.

The Eventbrite Multi theme by Voce Communications.
The Eventbrite Multi theme by Voce Communications.

Originally developed by Voce Communications, the Eventbrite themes that have been available on WordPress.com are now in the WordPress.org theme repository, and the plugin that powers them is also available for download. Together, the themes and the plugin provide full-featured Eventbrite integration for single and multiple events, including a calendar view and a widget. Huge thanks to Voce for continuing to support their work in the .org space!

Automattic has also developed an Eventbrite plugin, called Eventbrite API. This plugin is designed to work with any theme, with no explicit support required. It also provides a selection of simple tools that allow theme developers to work with events as easily as custom loops, making Eventbrite theme integrations more fun to build than ever. We’ll have a post next Monday demonstrating how to take advantage of this new plugin in your themes.

Eventbrite and WordPress are a perfect match, and we now have two great plugins for bringing them together. See you at the show!

Making Features Available to Themes

I’ve gotten myself into a bit of a problem.

A couple of months ago, we released a new feature called Site Logo on WordPress.com, that allows you to set a logo for your site and have it persist between theme changes. It went over well, and it was decided to roll it into Jetpack for .org users. However, part of that Jetpack integration involved prefixing the template tags used by themes, leaving me with inconsistent function names once we merge Jetpack back to WordPress.com (and for those using the .org Github plugin). It also leaves our premium theme sellers wondering what template tags they should be using moving forward.

I was discussing how to handle the transition with George Stephanis, the Jetpack team lead, and he suggested something I hadn’t considered: have themes just add a hook rather than using template tags when adding features. So rather than theme devs outputting a site logo by adding:

<?php if ( function_exists( 'jetpack_the_site_logo' ) ) jetpack_the_site_logo(); ?>

it could just be:

<?php do_action( 'jetpack_site_logo' ); ?>

I admit it weirds me out: I want to use template tags, the same way I do to output a post title or a featured image, and I imagine people hanging all sorts of strange stuff from it, because, well, it’s a hook. The advantages are clear, though: code behind that hook can be changed and evolve with little concern for theme compatibility, no need for the function_exists() dance, and theme devs have an avenue to alter as much or as little as they choose. In fact, any dev can roll their own original implementation, including a totally different Site Logo plugin.

What do you think? Do you prefer the classic use of template tags, or should we move towards hooks for implementing theme features in Jetpack?

Using Custom Headers for Avatars

Some themes like to use the admin account’s avatar, if available, in the header of the theme to highlight the author. However, it’s nice to be able to change that image if the admin email’s avatar is not appropriate nor changeable.

The free Automattic theme Writr, by our very own Thomas Guillot, takes the approach of using Custom Headers for customizing the avatar image. In short, we’ll be using Custom Headers to output our image, and its default image argument will allow us to insert the avatar when no custom header image has been uploaded. Let’s get started!

In header.php, we output our Custom Header image as usual.

<!--?php 	$header_image = get_header_image(); 	if ( ! empty( $header_image ) ) : ?-->
	<a class="site-logo" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
		<img class="no-grav header-image" alt="" src="<?php header_image(); ?>" width="<?php echo get_custom_header()->width; ?>" height="<?php echo get_custom_header()->height; ?>" />
	</a>
<!--?php endif; ?-->

While declaring support for Custom Headers, we set the default-image argument to be a function (which we’ll use for our avatar logic).

function writr_custom_header_setup() {
	add_theme_support( 'custom-header', apply_filters( 'writr_custom_header_args', array(
		'default-image'          => writr_get_default_header_image(),
		...
	) ) );
}
add_action( 'after_setup_theme', 'writr_custom_header_setup' );

Finally, our writr_get_default_header_image function fetches an image from the Gravatar service. If there’s no account matching the admin email sent, we can request another image to be returned from Gravatar; we’ll try to match it to the “Default Avatar” value in Settings → Discussion (that’s all that $default business). More detail on the arguments being sent can be found in the Gravatar Image Requests documentation.

function writr_get_default_header_image() {

	// Get default from Discussion Settings.
	$default = get_option( 'avatar_default', 'mystery' ); // Mystery man default
	if ( 'mystery' == $default )
		$default = 'mm';
	elseif ( 'gravatar_default' == $default )
		$default = '';

	$protocol = ( is_ssl() ) ? 'https://secure.' : 'http://';
	$url = sprintf( '%1$sgravatar.com/avatar/%2$s/', $protocol, md5( get_option( 'admin_email' ) ) );
	$url = add_query_arg( array(
		's' => 120,
		'd' => urlencode( $default ),
	), $url );

	return esc_url_raw( $url );
} // writr_get_default_header_image

That’s it; we automatically get the avatar of the admin email (or an appropriate substitute) from Gravatar, or we can simply upload a new custom header image to override it. Have fun!

Theme Performance

Website performance is a daunting, complicated subject; everything from servers, networks and the code itself affects the length of time it takes for our carefully-crafted pixels to arrive on the screen of our viewer. However, when it comes to WordPress themes, there are a few simple guidelines we can follow to make sure our themes help, rather than hinder, that process.

There is a single, unifying concept behind all of the following practices: less is more. Performance can be improved every time we:

  • reduce the amount of data we fetch,
  • reduce the time required to fetch that data, and
  • reduce the number of times we have to fetch data at all.

Image Handling

Images require special treatment to not get in the way of performance. These tips will make sure any images you require are as lean as possible.

  • Many images can be further compressed before suffering any visible loss in quality. Make sure any included images in your theme are compressed, either with your favourite image editor, or a tool like PNGCRUSH. Use the image format (JPG, PNG, or GIF) that best suits your situation and results in the smallest file size.
  • The best way to reduce image size? Don’t use them at all. If all you need are icons, use an icon font (like Genericons) instead, or the vector format SVG. Use CSS whenever possible for graphic elements, such as spinners or loaders.
  • If you must use multiple small images, combine them into a single file as CSS sprites, to reduce their download to just one HTTP request.

Scripts and Stylesheets

Scripts and stylesheets add up quickly. Simply adding third-party scripts and libraries that cover all edge cases can result in a lot of un-necessary code, while comprehensive CSS frameworks can also amount to needless data. Keeping in mind our mantra of less is more, two further action points can bring significant improvements to our page loads.

  • Minify, combine and compress your scripts and stylesheets to reduce their size and the number of requests to load them.
  • Enqueue scripts and stylesheets only on the pages that require them. See the Twenty Fourteen default theme for an example of how CSS and JS for the slider are conditionally loaded for just the home page.

Transients

Web servers have a very repetitive job. If ten users request our website in one minute, and nothing has changed on that page in that minute (a new post, categories removed, menus changed), it’s a bit of a waste for the web server to keep querying the database for the same information every time. This is where caching comes in. Caching is the general idea of doing the time-consuming data fetching one time, storing the results, and then delivering those stored results the next time someone asks for that same page. While the details of caching are far beyond this article, suffice it to say that the more our theme code can take advantage of caching, the speedier our sites will be – and the Transients API is a simple tool for theme developers to do just that.

Theme developers can store long-running queries in a transient, meaning each time that information is requested by the theme, it will be delivered quickly from cache rather than from a full query of the database. Secondary loops can be stored in transients, as well as the results of uncached core functions. The Twenty Fourteen default theme uses a transient for handling Featured Content.

For more information on transients and caching in general, Zack Tollman of The Theme Foundry has written an easy-to-understand overview of how WordPress uses caching in core.

Testing

Google’s PageSpeed Insights tool is extremely helpful when measuring performance of your sites in general. While some of it will not apply directly to theme code, it can point out issues with large images, unminified assets and more. There are two versions: a web version and a Chrome extension. The web version is usually more up-to-date (and now includes mobile-specific tests), while the extension can be used for offline, local testing.

Pingdom offers a suite of tools for web developers, one of which is the Website Speed Test. While PageSpeed is an overall review of best practices, Pingdom’s page test is focussed on load time, with the number of requests and load size for context.

Wrap-up

Getting content in front of our users as fast as possible is more important than ever these days, particularly considering the growing use of mobile phones and tablets. If we want content in front of our user within one second, we need to squeeze every millisecond we can get out of our themes and WordPress installs. Performance is an ongoing, incremental process which, with these guidelines and regular education, will keep your themes in top shape for all of your visitors, mobile and up. Remember: less is more!