Repository files navigation

Accelerated Mobile Pages Module (AMP Filter) is a custom module for Kentico CMS and EMS. It consists of anOutput Filter for transforming regular HTML to AMP HTML format and a macro method that makes it easy to adjust and fine-tune the rendered output. The project is based on amaster thesis (EN) of Daniel Minarik (full text).

💡 Readhow we implemented AMP on Kentico Advantage website.

1. Install the NuGet packageKentico.AcceleratedMobilePages

To enable AMP Filter on a site:

1. Go to Settings -> System -> Output filter -> AMP Filter
2. Check that "Enable AMP Filter" is on
3. Set an AMP domain name (e.g.:amp.domain.tld if the web is hosted onwww.domain.tld).
4. Go to Sites -> Edit site -> Domain aliases
5. Create a new domain alias corresponding with AMP domain name specified earlier

There are two options for how to activate an AMP Filter for a specific page:

• In Accelerated Mobile Pages application, add pages by selecting them from the site content tree.

• In Pages application, by selecting a particular page from the content tree, navigating to Properties -> AMP Filter, and then selecting "Enable AMP for this page".

There are several ways of including cascading style sheets into an AMP page:

• Set a default CSS stylesheet for the whole site (in Settings -> System -> Output filter -> AMP Filter).

• Set a CSS stylesheet for every AMP page separately (Pages -> Edit -> Properties -> AMP Filter -> uncheck "Use default stylesheet" and select the desired stylesheet)

• If none of the previous options is set, the AMP Filter will use the regular CSS stylesheet assigned to the page (either the site's default stylesheet or the page-specific one). This option is not recommended, as the stylesheet could be bigger than 50kB (e.g., if it contains styles for the whole website).

The AMP standard offers a lot of components or tags which do not have an ordinary HTML equivalent, and therefore, they can't be automatically injected or replaced in the page's source code.

You can use the{% AmpFilter.IsAmpPage() %} macro to find out whether the AMP Filter is enabled and active on the current page. This is useful for showing and hiding different parts of a web page. To do that, use the macro as a visibility condition of a web part.

Some advanced components, such as social media embed, advertisement, analytics, video or audio require ascript to be included in the head element. To do that, use the Head HTML Code web part.

For pages that have the AMP Filter enabled:

• If the page is accessed from a non-AMP domain:

  • AMP Filter will insert anamphtml link to the head tag of the page (this allows discovery of AMP-enabled pages)

• If the page is accessed from an AMP domain, the AMP Filter:

  • Removes restricted elements, attributes and their values
  • Replaces regular tags with their AMP HTML equivalents (these 5 tags: img, video, audio, iframe, form)
  • Inserts compulsory AMP markup required by the AMP standard (such as the AMP runtime script, boilerplate code…)
  • Injects a stylesheet as described above

This transformation is done via the HtmlAgilityPack library. It creates a DOM structure and the AMP Filter removes and replaces the elements according to theAMP HTML specification.

Some advanced replacements (which were not possible to implement using the HtmlAgilityPack) are done by regular expressions.

The AMP Filter does not transform cascading stylesheets in any way. The developer must ensure that the stylesheet complies withAMP HTML specification - stylesheet restrictions.

AMP Filter has two types of global settings:

• Font providers settings - a white-list of font providers of custom fonts available for usage via the<link> tag. (Other fonts can be used via the@font-face CSS rule.)
• Script URL settings for five different AMP HTML elements. This allows loading of specific (or latest) versions of the runtime scripts.

Both types of settings depend directly on the AMP HTML specification and should be changed only according to the AMP specification.

Even when using the AMP Filter there are still some things that need to be handled by the developer:

• Write valid CSSs according to theAMP specification.
• Follow theAMP specification when using SVG tags (AMP Filter does not affect SVG tags at all).
• Use only white-listed font providers via<link> tag or use other fonts using@font-face CSS rule.
• Explicitly state the size for every image (height and width attribute).
• In case of sites with complex styling, the stylesheets need to be reduced so that they do not exceed 50kB in total.
• If a page contains scripts, on-line forms, social media embeds, advertisements, or other interactive elements, the elements need to be replaced withAMP extended components.

• For simple sites with CSS totaling no more than 50kB in size (and adhering to the officialAMP rules), there's no need to create AMP-specific stylesheets - the sites will work correctly with the regular stylesheets.

• The AMP filter is mainly intended for simple, static pages, i.e. pages containing regular HTML. Only the<img>,<video>,<audio>, and<iframe> interactive elements (adhering to theAMP HTML Specification) are allowed. Pages that fulfill these requirements will be transformed into the AMP format.

• The static<form> element used by ASP.NET web forms to store metadata and viewstate information is also converted to the AMP format. However, standard<form> elements included in the page's markup will not be submitted and processed by the server at all. To implement standard on-line form functionality (via the<form> tag), refer to theamp-form section of the official AMP documentation.

1. Read thecontribution guidelines

2. Enable thecontinuous integration module

3. Remove<ObjectType>cms.settingskey</ObjectType> from theCMS\App_Data\CIRepository\repository.config

4. Serialize all objects to disk

5. Open a command prompt

6. Navigate to the root of the project (where the .sln file is)

7. Fork this repo

8. Init a git repo and fetch the web part

   git initgit remote add origin https://github.com/OWNER/kentico-amp.gitgit fetchgit checkout origin/master -ft

9. Restore DB data

   Kentico\CMS\bin\ContinuousIntegration.exe -r

10. Open the solution in Visual Studio

11. Add the following projects to the solution:

    • Kentico.AcceleratedMobilePages\Kentico.AcceleratedMobilePages.csproj
    • Kentico.AcceleratedMobilePages.Publisher\Kentico.AcceleratedMobilePages.Publisher.csproj

12. Reference the added projects from the CMSApp project:

    1. Right-click the CMSApp project and select Add -> Reference...
    2. Click Browse... and locate the projects on your filesystem
    3. Click Add

13. Rebuild the solution

14. Resign all macros

15. Optional: Assign the module to one or more sites

16. Make changes

17. Use a combination ofgit add,git commit andgit push to transfer your changes to GitHub

    git statusgit commit -a -m "Fix XY"git push

18. Submit a pull request

Tested with Kentico 12.0 (net461).