Now available through Jetpack, Content Options let users make small visual changes, like showing or hiding the author, date, featured images, and more.
If you’re making themes, Jetpack allows you to easily add additional functionality to your themes in a consistent way without a lot of overhead — and without accidentally wandering into “plugin territory.” Here at Automattic, more and more of our themes take advantage of Jetpack to implement site logos, featured content sliders, testimonials, portfolios, food menus, and other special functionality.
The trouble is that users don’t always realize they need to activate Jetpack in order to turn on this functionality. With so many installing themes directly from their WordPress dashboards, most users don’t even know where to find a readme file. As a result, we saw tons of confused users posting in the WordPress.org forums, asking how to make their sites look like our demos.
What we needed was a way to easily inform our users that their theme relied on certain Jetpack modules, and help them install or activate them as needed. This would save on support time as well as make our users happy. We also needed a solution that would be easy to add to lots of different themes, without requiring a lot of manual labor.
Enter the Jetpack Dependency Script
We’ve been working on a solution to this problem over the past few months, and we’ve come up with a simple script that helps our users figure out what’s going on. Since starting to use it in our themes, we’ve seen the number of support requests drop substantially.
Since we love open source, we’ve made the code freely available on Github — so you can use it, too!
Give It a Spin
Want to start using it in your themes? Download it from our Github repo, put it somewhere in your theme — I recommend the
inc folder — and include it from your theme’s
functions.php, like so:
/** * Load plugin enhancement file to display admin notices. */ require get_template_directory() . '/inc/plugin-enhancements.php';
You’ll want to replace all instances of
textdomain in the script with your theme’s text domain, since it adds a few new strings. You’ll also want to regenerate your theme’s POT file once that’s done.
How It Works
The notifications appear on the user’s dashboard and on the Themes and Plugin pages. The notifications can be dismissed so they don’t annoy users who don’t want to use Jetpack.
What’s Under the Hood?
Since the script is looking for theme support using
current_theme_supports(), themes need to explicitly register support for the Jetpack features they support. Some Jetpack features — like testimonials and portfolios — are available across all themes, and don’t require the theme to explicitly declare support for the feature. Be sure to add theme support for all Jetpack features you intend your theme to make use of. You can declare support like so:
add_theme_support( 'jetpack-portfolio' );
The script checks for theme support first, then checks to see if the required plugins (Jetpack) and modules are activated. It then builds out notifications tailored to the user’s individual situation, so that users are effectively guided through the process of installing and activating the plugin.
Presto! In only 366 lines of code, we have happier support people and happier users. Feel free to use this script in your own themes, or remix it for your own purposes.
Good user experience in WordPress themes can make the difference between frustrated or happy users. Yet, it’s often overlooked. A solid user experience can feel just right, creating sound expectations and delight. If you’re looking to boost your theming skills and learn more about themes and user experience, we recommend these three recent talks by members of the Automattic Theme Team:
Kirk Wight, A Call for Simplicity: As WordPress blazes into its second decade, theming, plugin development, and WordPress core itself are reaching troublesome levels of complexity and confusion, challenging the very essence of what has gotten WordPress to where it is in the first place. Pulling from diverse areas of culture and tech, we’ll tie together our need for simplicity, and issue a call to arms for the next ten years of WordPress.
Tammie Lister, Theme, Don’t Be My Everything: It’s time to stop putting everything including the kitchen sink into themes. A theme shouldn’t be a bloated monster with an options panel that stretches out the horizon. This talk is a call to action to stop making themes that do everything and start making themes that focus.
David Kennedy, Themes are for Users: In this talk, we’ll explore user research, theme setup, theme options and more. By the end, you’ll know what makes up a theme’s user experience, and how to set your users up for success.
And if you’re still getting started with theming, or even WordPress, wondering how you could ever contribute to WordPress and add value – you’re not alone. Check out Kathryn Presner’s The Techie Continuum, and start contributing to WordPress today!
A minimalist theme crafted by Automattic’s Tammie Lister, Sapor is geared to showcase your passions. Designed with food blogging in mind but well suited to anything from gardening to healthy living, it features a left sidebar for menu and widgets, and offers a Site Logo option with Jetpack active. We’re pleased that Sapor is now available in the WordPress.org directory — visit the demo or take it for a spin.
Watch the video presentation or read the transcript below.
You’ll find accompanying material for this screencast available in a public GitHub repo — each screencast has a corresponding folder with a very simple theme that can be activated.
But if you look closely, you might notice something has changed. Our
changePost function has disappeared, and instead we are requiring the
changePost function. If we go back to the containing directory, you can see that we also have a changepost.js file. This file now contains the
changePost function. Note that at the bottom, we have a line that says
module.exports = changePost. This is the CommonJS convention for defining what the module actually is. So when we require it, this ensures that what we require is the
changePost function itself.
Let’s get concatenating. I’ve mentioned that we’re using Webpack, so let’s get that set up. First, you need to install Node.js. Fortunately, this is a lot easier than it used to be — simply go to nodejs.org and download the automatic installer for your system. Once node.js is installed, we can run a command to install Webpack:
npm install webpack -g
This gives us global command-line access to Webpack. With this done, we can now run the most basic Webpack command, which is to take a source file, and smoosh it into a compiled file. The command for this is:
webpack ./theme.js compiled.js
We can now view the compiled file and see that it contains the contents of both changepost.js and theme.js. An extra little bonus with Webpack is the
-p flag, which simply means that you want to minify the file – remove whitespace and remove all comments etc. You can see that even this simple example our compiled file is almost a third of the size it was unminified.
We can also add the
-w flag which means we want Webpack to watch the files and automatically recompile whenever we change anything.
With the file compiled, we can see everything in action working together.
The Route of All Evil
With everything we’ve looked at so far, you can probably imagine stringing together a theme that allows a user to browse through different chunks of content from their website. However, a major missing piece is routing, something that you may not have heard of. Routing broadly encompasses the way that we deal with URLs changing. Let’s say a user visits our site, clicks to a different post and wants to share the link. With the examples we’ve looked at so far, this isn’t possible. Routing also ties into our user’s history. If we have no routes, the user can’t press the back button. No routing also means we have little chance of anything meaningful being indexed by search engines. I’m sure you can now appreciate that routing is very important.
In PHP, WordPress deals with this for us. There is a rather large class called
Let’s look at something basic we can implement.
If you look closely at changepost.js, you’ll notice that I’ve added a new line since the last tutorial. As well as editing the document on success, I’ve added a line that redefines
window.location.hash. This is the most basic way of changing our user’s route. You’ve probably seen this used on other websites and it amounts to the same thing as using an anchor link to take the user to certain heading on a page.
Let’s look at this in action. Our eventListener has been added to the first link in the menu. If we click it, note that the route now changes.
So with some very basic routing, we now want to change what happens if the user clicks back.
If we go back to theme.js, the eagle-eyed among you may have noticed another line beneath my link listener:
window.onhashchange = changeRoute
We’re hooking a new function,
changeRoute function. Here, we say if the hash equals nothing — as in, we’re on the homepage — show the original post that we fetched in the first place. The code here is almost identical to
changePost, but it just gets the original post.
What About no-js?
Will Somebody Please Think About the Search Engines?!
This ties back into the search engine point, since we know that Google does take page-load times into account when ranking sites in search results. We really don’t want our load times to be three to four times longer than they need to be.
In the next part of this tutorial, we’ll look at how to move from our basic theme to something more advanced, building from an altogether more stable foundation.
Watch the video presentation or read the written transcript below.
You’ll find accompanying material for this screencast available in a public GitHub repo — each screencast has a corresponding folder with very simple theme that can be activated.
Time for a REST
With traditional WordPress themes, we’ve been able to use all manner of loops and custom queries to get data. In shifting our approach to be less PHP-centric, where will our data come from?
The missing piece of our puzzle is a REST API, essentially an HTTP interface for getting data from a source. The REST part stands for REpresentational State Transfer. Think of it as a way of accessing WordPress queries directly through a URL. We can type a URL into our browser and include parameters just like we would with a custom loop, and in the browser we can see pure data from our website.
A REST API also allows you to post data, so the WordPress REST API allows you to add and update content directly without using the admin interface. Certain types of requests do need authentication, the REST API only publicly exposes content which is already revealed by WordPress through other avenues, like RSS feeds.
This all means that you don’t have to worry about connecting to a database, you just use a series of URLs to access different types of content on your site — these are known as endpoints.
The WordPress REST API is due to be fully incorporated in WordPress 4.5, due in the spring of next year. In fact, the infrastructure of the WordPress REST API will be included with WordPress 4.4 and has already been merged into trunk.
Exploring the WordPress REST API
Next, let’s look at some of the basic things we can do with the WordPress REST API.
I have a WordPress environment set up locally where I have installed WP API. Ahead of its inclusion in core, WP API is available as a plugin on the WordPress plugin repository. With the plugin activated, I can navigate to the URL
/wp-json/. At this URL I can see an overview of everything that the REST API makes available to me.
As the URL suggests, WP API uses JSON formatted data. This is not compulsory for REST APIs, but most REST APIs will use either JSON or XML formatted data. More recently JSON is the preferred format as it’s less verbose and generally easier to work with. I’m also using a Chrome extension called JSON View, which adds sane line breaks and some colours to make it easier to read the JSON. Without JSON View, the JSON data is quite hard for a human to read!
The REST API adds namespaces to its endpoints. This is to ensure that extensions and future versions of the API don’t break functionality for sites and software that use it. The primary namespace at the moment is
wp/v2. This means that we can build our website against version 2 of the REST API. If, in the future, it’s decided that the REST API should be structured differently, this restructure would happen under the namespace of
wp/v3. Therefore the REST API could completely change, but what we built for v2 would be safe with the inherent backwards compatibility of the v2 namespace.
So, if we navigate to
/wp-json/wp/v2/ we can see all of the information about this namespace. As newcomers, we don’t have to worry about this at the moment, but it’s worth understanding the path we take to what we’re really trying to get from the REST API.
If we add
posts/ to the end of the above URL, we finally start seeing the data from our website. By default,
posts/ will show us the same content that a generic loop on our homepage would. On a clean install of WordPress, this is usually the 10 most recent posts.
We can further narrow down our request to the REST API by adding a post’s ID to the URL. So in this instance,
/wp-json/wp/v2/posts/1241/ will show us just the one post with ID 1241.
The REST API provides typical things that we might want in relation to a post. We can see the date, modified date, permalink, title, content, excerpt, format, whether or not it’s sticky, and more.
I’ve set up a basic HTML document set up in my text editor, including a
div with the
anchor link with text “Hello world,” and an empty
div element. The
div has an
innerHTML methods to change the data in the HTML on this page. At the moment we aren’t dealing with errors, we would want to deal with these if we were doing this in production.
Let’s see how this works. If I activate the session 2 theme on my test site, we can see what this does. There we go, the data from the REST API is being rendered in my theme demo.
One last thing before we end this tutorial. We still have that link that I added at the top — let’s look at how this is connected.
Well, if we go back to the index of our little theme and scroll down, you can see we also have a function,
There we have it.
You can now see how a very basic WordPress REST API-based theme can work. In the next screencast we will consider more advanced approaches to theming and the challenges we face when taking this approach.
WordPress theming hasn’t changed very much over the past few years. It’s certainly become more refined, and projects such as Underscores (_s) have helped promote best practices and robust standards. That said, we can still go as far back as Kubrick and find plenty of common ground with the most recent WordPress themes.
- Storing and pre-fetching content using the browser’s Web Storage API to allow server-less, seamless transitions — using the browser’s History API — between posts and pages.
- Animations within themes, for more natural and intuitive interactions.
- The ability to create entirely offline experiences using all new Service Workers.
In this five-part tutorial, we’ll expose you to the brave new world that WordPress theme development might inhabit in the coming years. While the best practices for building a theme in this way are still to be established, we’ll do our very best to guide you into the secret garden of the future.
Stay tuned for:
Putting the Jetpack portfolio custom post type to good use, Blask showcases all types of creative work – like photography, graphic design, illustration, or painting – in an elegant, minimalist way. Blask was developed by Automattic’s Ola Laczek, based on a design by Mel Choyce.
Colinear is Thomas Guillot’s revamp of the classic Coraline. With six layout options accessible via the Customizer, Colinear offers tremendous flexibility in displaying large amounts of content, perfect for news or magazine-style sites.
Both Colinear and Blask support a Site Logo with Jetpack active, and are fully responsive, looking spiffy at any screen size. We hope you enjoy this handsome theme duo.
Check out the video presentation or the written transcript below.
Getting Our Hands Dirty
First, we want to select something in the DOM. The two most common methods for doing this are
querySelector. They’re similar, except with
querySelector we can select elements by their class. As its name suggests
getElementById only allows us to select elements by their ID.
With something selected, we could now change pretty much anything about it. This is basically what jQuery does behind the scenes.
A Whole New Node
We’re pleased to launch two new themes on WordPress.org.
Featuring big, bold drop caps and oversized images, Libretto is ideal for showcasing longform writing or stunning imagery. Its classic design and typographic details will give your blog a sophisticated, elegant look. Libretto is a fork of Readly, originally designed by WPShower.
Designed by Automattic’s Caroline Moore, Libre brings a stylish, classic look to your personal blog or longform writing site and is now available for download at WordPress.org. Libre’s main menu stays fixed to the top while visitors read your posts, and three footer widget areas let you tuck extra content away at the bottom of the page. Two custom page templates, including a full-width layout, add visual variety. Make Libre your own by adding a header image or — with Jetpack — a site logo. Libre sports a clean, responsive design that lets your site shine on screens of any size.