XalokNext Documentation

Appearance

AMP ​

Intro ​

XalokNext comes with some features to ease developing AMP pages.

Platform template ​

Defining ​

One can define a template to be used only for a specific platform (AMP, in this case).

To do so, one needs to create a twig file with the -__PLATFORM_NAME__ suffix (e.g. src/App/Bundle/CmsBundle/Resources/views/Template/Article/default-amp.html.twig). Usually this file should overwrite the "non-platform" one (e.g. default.html.twig) and overwrite the blocks that need special HTML for the given platform.

Using ​

To render the article using the given platform, one needs to pass the platform name as a parameter to the wf_cms_render_page function.

Example: Display the article using the template for the amp platform (default-amp.html.twig):

html
    {{ wf_cms_render_page(pageSlug, pageVersion, { platform: 'amp' }) }}

Note: The second argument is pageVersion - this is useful if the editors can preview an unpublished version from the admin, but one can pass null otherwise

AMP filter ​

Intro ​

XalokNext comes bundled with the AMP PHP Library, a library that automates the conversion of HTML to AMP HTML.

Using ​

Example: Pass the amp_filter option to the wf_cms_render_page function:

html
    {{ wf_cms_render_page(pageSlug, pageVersion, { platform: 'amp', amp_filter: true }) }}

Extending ​

XalokNext provides the wf_cms.amp.filter service that one can overwrite in the project to extend the AMP filter functionality.

The most common way of extending the AMP filter is to add custom AMP transform passes.

Example: Adding a custom transform pass:

php
<?php

namespace App\Bundle\CmsBundle\AMP;

use Lullabot\AMP\AMP;

class AmpFilter extends \Wf\Bundle\CmsBaseBundle\AMP\AmpFilter
{
    protected function setupAmp(AMP $amp)
    {
        parent::setupAmp($amp);
        
        $amp->passes[] = MyCustomTransformPass::class;
    }
}

Check out the AMP PHP Library passes or the ones provided by XalokNext to see how the transform passes work.

Image dimensions ​

The AMP HTML makes the images' width and height attributes mandatory. In order to find out the dimensions of the images, the AMP library needs to download the image first in order to read its dimensions. This can be very slow, especially if the image is hosted on S3 (as opposed to existing on the local hard drive).

In order to speed up this process, XalokNext implements a shortcut: if the name of the imagine filter follows the format image_filter_name__WIDTH_HEIGHT (e.g. image_500_300), XalokNext will take the width and the height from the name of the imagine filter, instead of downloading the image.

Note: This works only for mode: outbound filters, where the dimension of the thumbnail will always be the ones defined. For mode: inset, only either the width or the height will be the same, the other one will be calculated depending on the aspect ratio of the original image.