Templates overrides

Sometimes your specific website design or content, or your customization needs will require that you entirely rework small or large parts of the HTML or CSS output of weeblrAMP built-in theme.

One very powerful way to do so is to take advantage of weeblrAMP template overrides feature. In short, the complete AMP pages weeblrAMP generates is built based on a number of template files we call layouts, each representing a small part of the page. For instance, we have individual layouts for:

• a page header
• a page footer
• a page body, which in turns loads multiple smaller layouts
• each social sharing buttons
• generating the CSS output
• outputting Open graph meta data
• another for Twitter cards
• and many more

Most importantly, you can override any of these layouts files by your own, simply by placing your version in a specific folder inside your theme, or better, inside a child theme.

Child themes are the preferred options, as they will not be replaced when you update your theme, should a new version of it becomes available

How does this work?

All built-in layouts are stored hierarchically starting from the layouts directory within weeblrAMP. Here is how it looks:

Let's zoom-in into the tags folder:

We can see/guess that an Instagram image is displayed by a single layout, in the instagram.php file. Starting from the base layouts directory, the path to the layout file is:

weeblramp/frontend/amp/tags/instagram.php

We will usually refer to this layout file in a simpler way by using dots and dropping the php suffix:

weeblramp.frontend.amp.tags.instagram

Assuming we want to modify the way Instagram images are displayed on AMP pages, we should do the following:

1. Create a child theme of our current theme, say:
   /themes/twentyseventeen-child
2. Inside that child theme, create a weeblramp/layouts directory: it will serve as a new root for any overrides we will create
   /themes/twentyseventeen-child/weeblramp/layouts
3. Copy the instagram.php using the same sub-directories as the original:
   /themes/twentyseventeen-child/weeblramp/layouts/weeblramp/frontend/amp/tags/instagram.php

Things should look like this now:

That's it: this new instagram.php file is the template weeblrAMP will now use instead of its own to display Instagram images. Changes made to this file will be propagated to any situations where an Instagram image is shown.

This was just an example of course. As you can see on previous screenshots, there are many layouts files, and you only need to pick the ones you need for your customization.

You may have noticed that those layouts files are not always for visual element such as Instagram images. Anything output on an AMP page is output through a layout file. For instance:

• weeblramp.frontend.amp.tags.analytics: create the amp-analytics element
• weeblramp.frontend.amp.metadata.meta: output page title, meta description and such
• weeblramp.frontend.amp.metadata.ogp: output Open Graph meta data

IMPORTANT: you can modify any layout any way you like, but in the end, this will all be converted to AMP content. So simply don't use javascript, or add links to externall CSS files: javascript will be stripped, and external CSS links as well.

That's not all

Just like WordPress (documentation on this page), weeblrAMP also accepts per post, per post type, per page name overrides. To do that, create a separate override files, using the same naming convention as WordPress. Here is an example:

We have created overrides for:

• the Sample page page
• all Jetpack posts using the Jetpack portofolio custom post type

This uses the same naming convention as WordPress:

• 'page-' followed by a page "slug" (URL) will only apply to a single page
• 'single-' followed by a single post "slug" will only apply to a single post
• 'single-' followed by the "slug" of a custom post type will apply to all posts of that type.

This allow pretty extensive, yet granular customization of all your AMP content.

One more thing

Though for clarity we tend to prefer the use of layouts override in files, as described above, you do not have to put your overrides in separate files, using the same folder hierarchy as the originals. You can use filters instead.

After finding out the suitable layout file for a given piece of content (say our previous Instagram or Open Graph data examples above), weeblrAMP will always run the resulting output (the HTML to display the image or the OGP HTML) through a WordPress filter before using it, following this naming convention:

weeblramp_layout_weeblramp_frontend_amp_tags_instagram

So we start with weeblramp_layout_, followed by the layout id where dots have been replaced with underscores

Here is an example: to modify the way Instagram images are displayed using a filter, you should udo the following:

add_filter( 
    'weeblramp_layout_weeblramp_frontend_amp_tags_instagram',
    'my_custom_amp_instagram_filter',
    10,
    2
);

function my_custom_amp_instagram_filter( $rawOutput, $data)
{
    return $rawOutput . '<div>(c) My little company - 2017</div>';
}

One last thing

weeblrAMP will automatically pick-up layouts files you place in your theme or child theme, in the appropriate folder. But you can also store those overrides in other locations, as long as you inform weeblrAMP that these overrides are available. This is done very simply, using the weeblramp_template_dir filter.

Use this filter to register the root path where you have stored all your additional layouts, and weeblrAMP will check it before using a layout, looking for an override you may have created there.

This is very convenient to package what we could call an AMP theme. This is what we did to build our WooCommerce theme, which packs a set of layouts, that replaces the default built-in posts and categories layouts with some suited for WooCommerce products.