A Comprehensive Guide to Supporting AMP in WordPress

Standard

AMP is a new technology that’s gaining the attention of online marketers in every field.  It formats content in a way that loads blazingly fast for mobile visitors, whose page load time expectations can be as little as three seconds.

In this post, we’ll discuss what AMP is, as well as how to wire up your WordPress themes to support AMP templates.  You’ll find a large amount of information and code samples in this post.

Quick Links:


All About AMP

amp-project-logo

AMP stands for “Accelerated Mobile Pages.” It is an open source project backed by Google that makes web pages load really, really fast.  There are also some huge benefits for publishers who take advantage of AMP:

  • AMP pages are cached and served by Google itself.
  • Two versions of the page are now available to search queries: HTML and AMP.
  • They receive Google’s “Mobile-friendly” or “AMP” label in search results, notifying users that the page will load quickly.
  • Google may use AMP as a PageRank consideration in the future (“mobile-friendliness” already is).
google-amp-label

Example of the Google “AMP” label.  Don’t ask why I was googling Pokemon Go.

Further reading: Does Google AMP Affect SEO?

In order for Google to cache your pages and give it the AMP label, it must have valid AMP markup.  AMP HTML is very similar to regular HTML5, with just a few exceptions.

AMP HTML

AMP HTML is quite simple.  In most cases, it’s nearly identical to regular HTML5, with the exception that certain element tags are replaced with an AMP version.  For instance, the <img> tag becomes <amp-img></amp-img>.

Further reading: The AMP Spec Document

AMP has very specific standards. These standards are in place so that it can render each page as quickly as possible.  Here are some highlights of the requirements for valid AMP documents:

  • The document <head> must contain specific scripts and styles.
  • Only inline styles are allowed (No external stylesheets)
  • The inline styles are limited to 50Kb in size
  • Slow-loading elements — like <frame>, <object>, and  — are prohibited.
  • No custom JavaScript is allowed (but there are several AMP extensions that provide common JS functionality for you)

AMP Extensions (or, “Components”)

AMP Extensions are helpful components that expand what AMP does by default.

Below are a few noteworthy examples, but there are many other Extensions available.

amp-sidebar (or “menu”)
The AMP Sidebar extension is what is commonly used as a menu in WP.  It allows for a button (or other element, like a hamburger icon) to trigger a menu that slides into the page from the side.  I’ll discuss this in detail below.

This element can only be used once on a page, and it essentially only allows text, images, and accordions, so keep that in mind.

amp-ad
So your site depends upon ad revenue (who’s doesn’t?).  Thankfully, AMP provides a format for including these in your markup with the AMP Ad extension.

 

amp-brightcove
Hey, who doesn’t love Brightcove content?  To support the need for this feature, AMP has created the AMP Brightcove Extension.  Note that even if you have a lot of custom parameters to pass into Brightcove, you can still do that.

amp-social-share
AMP Social Share is really quite handy, as it takes care of integrating a bunch of sharing into your template by passing just some basic attributes.


The WordPress AMP Plugin

wp-amp-plugin

The good news for you is that the team at Automattic has created a very nice plugin to handle creating valid AMP documents in WordPress.  It’s simply called “AMP,” but for clarity’s sake, I’ll refer to it as “WP AMP” throughout this discussion.

To a user, the plugin simply makes an AMP version of a post is available.  This post is found at the same URL as the post, but with “/amp” tacked on to the end.

So if the URL is yoursite.com/hello-world, the AMP version is found at yoursite.com/hello-world/amp/.

For developers, WP AMP is basically a templating system.  It contains a basic AMP HTML template, and uses hooks and filters to ensure your content is rendered as valid AMP markup.  For example, the provided template includes the required code for the <head>, and it filters the post content to ensure your <img> tags are replaced with <amp-img>.

Further reading: WP AMP plugin documentation

Screen Shot 2016-07-21 at 10.43.13 AM

The default WP AMP post template.


AMP Template Customization for Themes

So, if you’re a theme developer, you’ll want to customize this document’s appearance to match the rest of your layout so that your users will have a seamless visual experience.  The rest of this post discusses how to do just that.

Customizing the WP AMP plugin to work with your theme takes a bit of work, but it will definitely be a big bonus to your users.  As this is a growing technology, there will be increasing demand for the fast page load times and Google recognition that AMP provides.  At this point, it will set your work apart from other WordPress themes.

Basic AMP Support Setup

Note that this tutorial is written for WP AMP version 0.3.2.

1. Set Up Your AMP Directory

To get started, create a directory in your theme called “amp/”.  Inside that directory, create “amp.php.”  We’ll add all of our backend code inside this file.

Now take a step back, and require the amp/amp.php file near the top of your theme’s functions.php:

require( dirname( __FILE__ ) . '/amp/amp.php' );

2.  Register Your Custom Templates

Here’s where the fun begins.  We’ll be adding your own template files so that you can customize them to match your theme.

After this following step, your theme’s file structure should end up looking like this:

your-theme/
   amp/
      templates/
         single.php
         style.php
      amp.php
   functions.php
   index.php
   style.css

 

Start by creating a directory inside of “amp/” called “templates/”.  Not surprisingly, this will hold your template files.

Next, create a file inside templates called “style.php” (note that it’s a PHP file, not CSS).  If you like, you can just copy the default style.php from the WP amp plugin: wp-content/plugins/amp/templates/style.php.

Now, go into the WP AMP plugin and copy the default single.php file (wp-content/plugins/amp/templates/single.php).  Place this in your theme’s “amp/” directory.  It’s important that you copy this one instead of starting from scratch, as there’s important data in its <head>, plus it also contains some of the actions we’ll be hooking into later.

3.  Register Your Custom Templates

Add the function below to include support for both your new “single.php” and “style.php”


Going Further

Support Custom Post Types

If you have Custom Post Types in your theme, you’ll need to tell WP AMP what they are so that those posts will have AMP versions available.

Next, we’ll add our CPT templates.

Custom Post Type Templates

Adding special templates for your custom post types is optional, but the previous step is not.  You’ll want a special CPT template if your CPT posts have a different layout or functionality than a typical post.

In your /templates directory, copy the single.php and rename it after the slug of your CPT.  For instance, you may have a “book.php” now.

Then, we need to tell WP AMP to redirect to this template.  Edit the function that I called jr3_amp_custom_templates() earlier.  It will now look like this:

Component Scripts

Each AMP Extension (once again, also called a “Component”) has a supporting JS resource.

If you’re using any other Extensions in your template files, like amp-ad, amp-social-share, or amp-sidebar, you must register the JS with WP AMP so it gets loaded correctly.


Customizing Your Template

Custom CSS

As AMP does not allow external stylesheets, all CSS must be found in the document’s <head>.  WP AMP gives us a tool for hooking styles into the <head>, which we’ve already set up.  As a reminder, it will use our our templates/style.php file.

The contents of that file are pretty easy to understand.  Open up the default WP AMP style.php and you’ll see that it’s almost all just plain text, except for a few places where colors and a few other settings are pulled in to render the desired CSS styles.

Keep in mind that the total size of CSS on the page cannot exceed 50Kb.

Here is an example of how the PHP interacts with the CSS:

Add A Nav Menu

A Navigation Menu is one feature that is glaringly lacking from the default WP AMP template.  Naturally, its authors are unable to know if you have a nav menu in your theme, and even if they did, they don’t know what location label you’ll give it, so it’s understandable why they left it up to you to customize.

AMP has an Extension called “amp-sidebar.”  This is a block of content that is triggered by a click that slides in from the side of the page.  We’re going to use this for our menu.

Screen Shot 2016-07-21 at 12.58.52 PM

Example of a basic Navigation Menu using amp-sidebar.

First, following the example code below, add two functions to your amp.php:

jr3_amp_sidebar_component_scripts() tells WP AMP to load the amp-sidebar JS into the template’s <head>.  (Check to make sure you didn’t already add this if you added the component scripts earlier)

jr3_clean_nav_menu_items() is a helper function I wrote to make a barebones list of menu items.  It skips adding all of the unneeded wrappers and classes to the nav menu.

Below those functions are two blocks of HTML to add to your single.php (and other template files).  The first is the HTML that holds our primary nav menu.  The next is the actual button that will trigger the opening/closing of the amp-sidebar menu.

By default, featured images are not included in the WP AMP templates.  Here’s how you do that, taken almost directly from the WP AMP docs.

Social Share Buttons

Since social share buttons often require JS to function, AMP has added support for them via its amp-social-share Extension.  The code below can go directly into your template file.  Don’t forget to register the amp-social-share component script with WP AMP.

I’ve found that Facebook requires an App ID, so be sure to add yours into your code.  Naturally, you’ll need to add some PHP support for this to draw the Fb App ID from wherever you have it in your theme’s settings.


Bonus: Handling Shortcodes

As AMP has very specific rules about what markup is allowed, we need to be careful to only allow valid HTML to our templates.

Shortcodes are a way that unintended output can be slipped in to our content and render the page invalid.  One simple (but not preferable) way to prevent this is to remove shortcodes from the content altogether.

Unfortunately, this approach is pretty brutish.  You should really use another solution for this issue, as you may want to allow certain shortcodes, or even filter the content to replace the shortcode with custom formatting.

Here’s an example of how I modified a hypothetical shortcode called “podcast” to accommodate <amp-audio>.  You’ll note that I also include a helper function to grab the shortcode attributes that we need so we can add that data to our <amp-audio> tag.

Final Thoughts

AMP is going to be a big deal, and soon.  In my experience, clients are already asking us at XWP to integrate it into their WP sites.

If you want to stay ahead of the competition in the WP theme world, or offer your clients another valuable service, you definitely need to integrate this into your themes.

I hope that my experience in this speciality will help you on your way.

Happy coding!

Resources

 

Advertisements

The First Step To Coding Like A Pro: Formatting

Standard

At its core, good formatting is more than putting a spit shine on your plugin or theme. Its something that is done from the moment you crack open that first blank text document and begin writing. Formatting is the practice of careful, conscious coding.

I interviewed for an awesome job last week. They were interested in me and wanted to see a code sample of my work. I didn’t have much that was ready for review (because I’ve been working in Front End Development for the last year), so I wrote a Plugin from scratch. I went 96 hours with only a couple of naps, working my hardest to crank out coding perfection. I threw in everything that I could think of: AJAX, OOP, Validation/Sanitization, Actions & Filters, the Settings API, even localization. When I was done, I proudly submitted it for review.

What was the reviewer’s response back to me? “Your code is sloppy.” In fact three-fourths of his comments related to tabs and spacing.

Why did he care so much about such small details? Once I took the time to think about it, the answer became obvious.

Why Formatting Matters

1. It makes your code better.

If your code is written to the correct standard, it has been written and reviewed with attention to detail. It takes several passes to get any file up to standard, and in the course of formatting, you’d be surprised how many bugs you can find. Reviewing your code means refining your code. To put it another way, I can’t imagine you’ll ever see beautiful code that throws lots of errors or breaks things.

Furthermore, organizing functions in a logical way helps you see new ways to write your program. It can show you places where you are repeating yourself, revealing good sections to turn into classes/methods. Don’t forget the DRY principle of programming: Don’t Repeat Yourself.

Good formatting includes commenting your code. It makes your work easy to navigate, allowing others to troubleshoot errors, as well as reminding you of whatever the heck you were doing during the late night coding binge when you wrote it. Well documented code is much easier to extend as well.

2. It makes you look better.

It requires a lot of discipline to write clean code, and it is quickly assumed that the author of organized, well-planned code is a person with an eye for detail. Adherence to coding standards demonstrates that you are well-versed in the language/platform you’re working with. Most of all, it shows that you care; if you’re going to put in the time to do excellent work, chances are you’ll do excellent work for a client or employer.

Principles of WordPress Formatting

So, what goes into good formatting? If we need to adhere to the standards, what are they?

First of all, go take a look at the WordPress Coding Standards Doc. There are four sections, one for PHP, HTML, CSS, and JavaScript. Take the time to review each document. Here are some highlights from the docs:

PHP Highlights

  • Indent your code, and use Tabs instead of Spaces
  • Include commas after the last items in arrays
  • No shorthand PHP tags
  • Read up on the section “Space Usage
  • Commenting/Documenting code. There’s a lot here about the PHPdoc format of commenting, the industry standard.

HTML in a Nutshell

CSS Notes

  • Each Selector should be on its own line
  • Use lowercase, hyphenated selectors (not camelCase or underscored)
  • Always end in semicolons (C’mon, folks, is it necessary to say this?)
  • Order Properties alphabetically

JavaScript Formatting

  • “Always put spaces on both sides of the opening and closing parenthesis of if, else if, for, forin, do, while, and switch blocks.”
  • Name functions and variables using camelCase, not underscores.
  • Use the var keyword as much as possible to keep variables out of the global scope
  • Never end an Object with a comma
  • jQuery and that pesky $

Best Practices

Some of these rules will be natural for you based on your background, but for those which aren’t, keep a list of important formatting points handy. Practice these standards in everything you write, no matter how seemingly insignificant, and they’ll become part of your personal style of coding.

Unless you’re still using NotePad, your IDE (text editor) should have some good tools to help you format your code correctly. Turn on syntax highlighting based on the language you’re using, and set your preferences to eliminate trailing spaces on save.

One of the best ways to clean up your code is to have it reviewed by others. Find some other WordPress geeks and review each other’s code. Be teachable. The process will be humbling, but it will grow you as a developer.

Conclusion

In the end, I got the job! When all was said and done, the reviewer was able to see past my amateur-ish-ness and see potential in my work. Good leaders acknowledge that this is a learning process for us all (In fact, in writing this post I’ve noticed a few things I need to go back and fix in my own code).

So what questions do you have about WordPress formatting? Do you have a horror story about ugly code? Leave a note in the comments!