Platform Specific Templates

This page will briefly outline some techniques to build platform-specific templates like AMP, Facebook Instance Articles, and Apple News.

The key thing with building templates for the above platforms is that you need a URL to display the specific format at. Often that will be a different URL from your main content.

For example, if you have a blog and one of your blog posts has a URL like this:

https://www.domain.com/blog/post/my-blog-post

then the following URLs might be used to display the same content for AMP, Facebook Instant Articles, and Apple News.

  • AMP: https://www.domain.com/blog/post/my-blog-post/amp
  • Facebook Instance Article: https://www.domain.com/blog/post/my-blog-post/fia
  • Apple News: https://www.domain.com/blog/post/my-blog-post/apple-news

Note that the above URLs are just examples. You don't have to follow that specific URL pattern.

Once you figure out the URL pattern that you're going to follow you then need to use the appropriate logic in your templates to output the correct code. There are two major techniques that you can use.

  1. Use Routes
  2. Append a specific value to the end of every URL

For the rest of these examples, we're going to use AMP as the template format. The same approach should also work for Facebook Instance Articles and Apple News.

Technique 1: Using Routes

If you use Routes then you have some more flexibility in what your URL could be. However, you also need to create a Route for each section of your website so that your templates know if you're displaying a blog post or a page.

A recommended pattern for creating your routes would be to prepend "amp" or some other string that you can easily use to identify the platform-specific template format. For example, the URL pattern you can use for blog posts could be:

/amp/blog/post/[slug]

This is a good approach as you can easily add the necessary <link> tag to the <head> section of your template by using the post URL.

{% do _page.addHead('<link rel="amphtml" href="https://www.example.com/amp/' ~ post.url ~ '">') %}

Using the above URL pattern as an example this is how we'd set up a Route for our blog posts.

Step 1 - create the Route

First, we'd create a new Route. We'd call it "AMP blog posts", enter /amp/blog/post/[slug] as the URL to match and specify the path to our AMP template. In this case our template is going to be located at blog/post-amp within our theme's templates folder.

The [slug] portion of the URL will match the ending section of the URL as long as it does not contain a "/". In this case, it would contain the blog post's URL slug value. We can then use that to retrieve the blog post.

Step 2 - create our template

Our template would first check to see if the slug value is available. If so, then it would try to retrieve the blog post. If that's successful then we can output the appropriate AMP code.

If the slug value is not available or the post could not be retrieved (usually because the slug didn't match a published post) then we could either redirect to another URL (like the home page) or show a 404 error.

{% if variables.slug %}
    {# Get the blog post based on the URL slug. #}
    {% set post = _api.blog.post.slug(variables.slug) %}
    {% if post|length > 0 %}
        {# Post was successfully retrieved. Output the AMP HTML here #}
    {% else %}
        {# Post could not be found. Show a 404 error or redirect to another page #}
    {% endif %}
{% else %}
   {# Can show a 404 error here or redirect to another page #}
{% endif %}

Technique 2: Append a specific value to the end of every URL

The other approach to your AMP URL patter would be to append a specific value to the end of every URL. A possible value could simply be "/amp". 

For example, if your blog post URL is

https://www.domain.com/blog/post/my-blog-post

then the AMP URL could be

https://www.domain.com/blog/post/my-blog-post/amp

This approach works with apps like the blog because the BranchCMS platform has already used the other parts of the URL to identify that the app to load content from is the blog app, that the content is a blog post, and that the post to load is the one whose URL slug is "my-blog-post". Everything after "/blog/post/my-blog-post" is by default ignored because that portion of the URL already matched a blog post. This allows you to use that portion of the URL in your template logic. Other apps like the gallery or store app work the same way.

You would then need to add some logic to each of your templates to test for the "/amp" value in the URL.

{% if _page.request.url ends with "/amp" %}
  {# Display AMP HTML #}
{% else %}
  {# Display regular HTML #}
{% endif %}

Instead of outputting the full HTML in this template it may be cleaner to include other templates to do the actual output. This can keep your code more organized.

{% if _page.request.url ends with "/amp" %}
  {# Display AMP HTML #}
  {% include ('blog/post-amp') %}
{% else %}
  {# Display regular HTML #}
  {% include ('blog/post-html') %}
{% endif %}