Jack Lenox

In this project we look at the Picard theme, which uses the REST API and React from course Advisor, Jack Lenox.

In this project we will look at how to setup the Picard theme using React and the REST API and then customize it with your own content and take it further with project ideas.

If you’re looking to see how React and the API can be used to power a theme, check out next section on Setting Up Picard Out of the Box.

Author Credit: Tammy Lee

An Overview of the Picard Theme

Picard is a theme created by Jack Lenox and the theme team over at Automattic to demonstrate theming using the WordPress REST API v1.

I had high hopes for this theme, seeing who was involved in its creation, and I was not disappointed! It is super fast because it utilizes local storage to store content from the REST API.  It also uses WordPress menus so you don’t have to dig into the code in order to change menus.

Picard, like most REST API themes, isn’t meant to be used in a production environment. It is, however, an excellent theme to dissect and study to see how to make your own REST API theme! It’s also a great theme to study to pick up on best practices from Automattic’s own theme team.

Picard Out of the Box

Theme Unit Test Data

We started with a clean installation of WordPress. Rather than populating our installation manually we just downloaded and imported the test data XML from the official theme unit test page.  We figured if the team and Automattic developed this theme it could probably work with the theme unit test data. If you have never imported test data into WordPress before the procedure is quite simple.

  1. Download the theme-unit-test-data.xml file from the Theme Unit Test page
  2. Log into your administration dashboard and go to Tools → Import
  3. On the next page, you’ll see a list of blogging services you can install an importer for. Click on WordPress.
  4. Choose the theme-unit-test-data.xml file you downloaded and click ‘Upload file and import’
  5. We left the default authors in place. Make sure you check the ‘Download and import file attachments’ checkbox before you click ‘Submit’.
  6. Wait a while. Depending on your network speed it could take a few minutes to import everything. When the import has finished you’ll see this message:
  7. Because we are not going to be using the imported users at this time we don’t need to update anything about them. Unless you’re concerned about security; in which case, please do change passwords. Our experimentation is being done on a local computer so security isn’t a huge concern.

Tada! Now that you have imported test data your WordPress installation should have posts, pages, users, and menus all setup! What a time saver, eh? Two things you might want to do? By default, the installation is set up to show blog posts as the front page and there are no menus assigned to menu locations. You might want to adjust those settings but, as this is our ‘out of the box’ installation we’re going to leave everything on default.

WP REST API Plugin

As we said in the introduction, the Picard theme is built on the WordPress REST API so you’ll need to download and install the WP REST API v1 plugin and activate it in your WordPress installation. It is important you install version one. It will not work with version two at the time of the writing of this article. Let us know if that changes and we’ll be happy to update!

The installation of the WP REST API plugin is very straightforward and it works right out of the box; no tweaks to settings are necessary.

  1. Download the WP REST API v1 plugin
  2. Log into your WordPress installation and head on over to Plugins → Add New
  3. Click on the ‘Upload Plugin’ button
  4. Choose the .zip file you just downloaded then press ‘Install Now’
  5. Once the plugin has uploaded click ‘Activate Plugin’
  6. And you’re ready to go! There are no settings to set.

Picard Present Theme

  1. Download the Picard Present theme from Jack’s repository as a zip file.
  2. Log into your WordPress installation and head on over to Appearance → Themes
  3. Click on ‘Add New’
  4. Click ‘Upload Theme’
  5. Click ‘Choose Theme’ and navigate to where you downloaded the theme then click ‘Install Now’
  6. Activate the theme

And, huh. Well, gosh. This isn’t quite what we were expecting to see:

picard present home

If you are using Picard Present you will get a blue screen that will show you the first post in your database, e.g. ID = 1.

picard present id1

But wait! That first post isn’t pulled to your home page, you are actually redirected to the URL of your first post.

picard present url redirect

Hrm. Perplexing.We dug into /picard-present-master/components/router/router.jsx to find where the routing is happening but, honestly, we had another Picard theme to test so we didn’t spend more than a half hour poking around seeing how things worked. If we had a free weekend we might be compelled to dig into the code; there’s a lot to learn here!

We dug into /picard-present-master/components/router/router.jsx to find where the routing is happening but, honestly, we had another Picard theme to test so we didn’t spend more than a half hour poking around seeing how things worked. If we had a free weekend we might be compelled to dig into the code; there’s a lot to learn here!If you feel so inclined, there are two big things to look into doing with the Picard Present theme:

If you feel so inclined, there are two big things to look into doing with the Picard Present theme:Routing – Right now ‘/’ will redirect you to the first post in the database. It would be nice if the theme pulled the WordPress preference to either display blog posts or pull a static front page.

 

  1. Routing – Right now ‘/’ will redirect you to the first post in the database. It would be nice if the theme pulled the WordPress preference to either display blog posts or pull a static front page.
  2. Menu – The theme doesn’t actually output the menu it registers! It wouldn’t be a huge effort to output and style the menu.(Any sort of styling would be an improvement over the default!)

picard present menu

So, seeing as Picard Present is a bit of a make-work project, let’s see what Automattic’s Picard theme is like out of the box!

Picard Master Theme

The Picard Master theme is different than the Picard Present because you can’t just download the .zip and upload it to your WordPress installation. If you try to upload the .zip file without running Gulp you’ll get an error about a missing style.css. Running Gulp creates the style.css file for you.

Automattic did such a great job on their installation instructions we’re going to direct you to their repository and wait for you to get to the point where you’ve activated their theme in your WordPress installation!

Ready? Great!

Menus

Right out of the gate, Picard Master has a menu! Woo!

picard master nav

The presence of a menu is great but it doesn’t appear to be functioning quite how we’d expect it to. A quick search of the code shows there’s a file called site-navigation-toggle.js that has all of the contents commented out. We tried uncommenting the code but that didn’t make the menu functional. Sounds like a project idea, to me!

There’s only one menu location but it works without having to change any code. Awesome. If you head over to Appearance→ Menus you can add any menu you like and it will show up.

Custom post types don’t work out of the box so hop over to the Customizing section of this article to find out how to add your own Custom post types.

Customizing Picard

Custom Post Types

We decided to use a plugin to add our test custom post type and went with Custom Post Type UI as it seemed like one of the simpler CPT plugins.

custom post type ui

Add Custom Post

If you view the page you just created, it will be blank! Wah wahhhhh. That’s because we haven’t told our application what to do with our new custom post type.

If you open a new tab in your browser and enter in your URL name with /wp-json/posts you’ll get all of your posts returned on the page. All we really want is our new custom post type. Change your URL so /wp-json/posts ?type=movie is tacked on the end et voila! We have a our custom post type returning all of our movies! But, what if I just want to see one movie? Well, let’s try that out in our browser.

What we need to do is filter our results to only show us the custom post type of  movie with a slug of ‘frankenstein’. Try adding /wp-json/posts?type=movie&filter[name]=frankenstein:

movie-single-frankenstein

So far, so good. Make sure, in terminal, you’ve run gulp watch and let’s dig into the code!

Just like with the Picard Present theme open up /components/router/router.jsx. We just duplicated the first ‘page’ code-block and made the following changes:

  1. Replace ‘/’ with ‘/movie/:slug’
  2. Assign /wp-json/posts?type=movie&filter[name]=frankenstein  to the url variable
  3. Change the bodyClass from “index” to “movie”
    picard-master-cpt-route
  4. Save and make sure gulp ran and compiled your JS

If you followed our instructions you should now be able to navigate to /movie/frankenstein and see a page of content!

Customization Results

Now that you’ve looked at how to customize this, take it further on your own, suiting it to your own needs or interests.

Then in the next section look we will look at some possible project ideas.

Project Ideas for Picard

Out of the box, with minimal configuration, this theme would be great for any other one-off event you might have that has speakers and sponsors. It wouldn’t be that difficult to create suitable custom post types and get it up and running in a hurry.

This theme would also be a good starting point for a brochure site where a client wouldn’t be adding or removing pages on their own. With a moderate amount of work, a footer could be added and content layouts modified to suit client needs.

If you’re feeling ambitious a great project would be to make the theme work with dynamic WordPress menus. You might take inspiration from the Menu API Plugin or tinker around on your own. To make the theme even more client-friendly you could try utilizing the Customizer API to make routes and menus more accessible for those with weaker skills.

Share Your Work!

Have an example project you have built based on this?

Let Zac know and we will feature it here!