AMPIFY your MODX Resources
PHP Smarty
Latest commit 827d352 Oct 14, 2016 @sepiariver sepiariver bump vers in config
Permalink
Failed to load latest commit information.
_build bump vers in config Oct 14, 2016
_packages pkg vers Oct 13, 2016
core/components/ampify remove wp-specific stuff Oct 14, 2016
.gitignore add pkg for testing Aug 18, 2016
LICENSE initial commit poc Aug 18, 2016
README.md docs Aug 25, 2016
config.core.php initial commit poc Aug 18, 2016

README.md

Ampify

Effortless Google Accelerated Mobile Pages, aka "AMP", for MODX Revolution.

What is it?

Ampify is a MODX Revolution Extra that includes a toolset to easily serve AMP HTML for Google's search results pages. The package includes a Plugin, and a sample AMP Template.

What does it do?

When triggered, the Plugin switches the Template used by the currently requested Resource, to the specified AMP Template.

I want details

The Ampify Plugin fires in two different modes: 'param' and 'context'.

Context Mode

In 'context' mode, the Plugin action is triggered when a request is made to a specified AMP Context. (Context routing and setup are outside the scope of this Extra, but there's an example implementation below.)

The AMP Context will automatically route requests to Resources that have been added to the ContextResource table. Resources are added automatically when they are saved. In future versions, a CMP will be provided to add/remove Resources from the table, with bulk actions.

This mode has the advantage of being able to include and exclude Resources from having an AMP view.

However, it has the disadvantage that AMP views will be rendered at a different URI than the canonical. At the minimum, the Context's base_url will be prefixed, for example: /amp/resource-alias.html versus /resource-alias.html

Also, if you have a lot of pre-existing Resources for which you want to provide an AMP view, you'll need to add them all to the ContextResource table by triggering the OnDocFormSave Event on all of them—or modify the ContextResource table yourself, programmatically. Until the CMP with bulk actions is developed (in a later version soon-to-come) this is a drawback of the 'context' mode.

Param Mode

In 'param' mode, the Plugin action is triggered when the GET param specified is set, in the URL string. This will override the amp_context property. In this mode:

  • If a request does not have the GET param specified, the Plugin will not fire, even if the request is in the specified amp_context.
  • The Plugin action will not be triggered on the OnDocFormSave Event, and the ContextResource table will not be modified while in this mode.

This mode has the advantage of rendering the AMP view at the same URI as the requested Resource. Nothing about the Resource's URI needs to change, except the presence of the specified GET param.

Also, the AMP view becomes immediately enabled for all your Resources, without any additional modifications of database records.

However, it has the disadvantage that Resources cannot be specifically included or excluded from having an AMP view—the Plugin will fire for all Resources if the GET param is present.

Another, perhaps more critical drawback, is that the AMP view will not be cacheable. This can cause serious performance issues, depending on the complexity of the AMP Template used. It's true that Google caches the AMP views, but it opens a door for anyone to trigger high loads on your site, if your AMP Template requires processing.

A workaround for excluding Resources from the AMP view, would be to use the amp_tv property, and for Resources you want to exclude from having an AMP view, set the TV value to the same Template that the Resource uses natively. However, if the URL param is set, the Resource will not be cacheable. There's no workaround in this version of Ampify, for the caching limitation in 'param' mode.

AMP TV

If a value is provided in the amp_tv Plugin property, then the Resource will only be added to the ContextResource table, if the Resource has a valid Template ID set in the TV. In that case, it will override the Template ID in the Plugin's amp_template property OnLoadWebDocument for that Resource.

If the TV is empty for a given Resource, that Resource will be removed from the ContextResource table.

In 'param' mode, no modifications happen to the ContextResource table, but the amp_tv value will be used to render the AMP view, falling back to the amp_template Plugin property as default.

Installation

Install via the MODX Revolution Extras Installer (aka "Package Manager").

Usage

The default Plugin property values are:

  • amp_context = "" If this property is empty or doesn't contain a valid Context key, the Plugin will try to run in 'param' mode.
  • amp_url_param = "" If this property is set, it will override the amp_context property and trigger the AMP Template view if a GET param with the specified key is set in the URL string. If this property is empty and amp_context is also empty, the Plugin effectively does nothing.
  • amp_template = "" This property is required. At least 1 Template must be dedicated to an AMP view, and that Template's ID set here, in order for the Plugin to work at all.
  • amp_tv = "" If a valid TV name is entered here, it will transform the Plugin's actions in the following way:
    • OnLoadWebDocument it will switch the Template of the Resource to the one specified in the TV with name amp_tv, falling back to the default set in amp_template
    • OnDocFormSave it will only add the Resource to the table for automatic routing if there's a truth-y value in the TV with name amp_tv. If the TV is empty or false-y, it will remove the Resource from the table. This provides primitive "remove" functionality until such time a CMP is made to manage ContextResources.

Example Implementation

In this example, we'll install Ampify into an almost fresh MODX install, and use Context Gateway for Context routing. Both can be installed via the Extras Installer:

Extras Installer

Create a new Context.

Hover over the cog icon in the top-right corner of the Manager, to reveal the "Contexts" menu item.

Contexts menu item

In the Contexts view, click "Create New".

Create Context button

Give the new Context a key, a user-friendly name, and optionally a description.

Create Context window

Once the Context is created, you'll see it in the grid-list of Contexts. Right-click on it and select "Update Context".

Update Context

In the Context Edit view, select the tab "Context Settings".

Context Settings tab

If you're not familiar with Context Settings, here are the documentation pages for Contexts and System Settings, which you might find useful to review before moving on to the next step.

Click the "Create New" button. You'll need to create 5 new Context Settings, at a minimum:

  1. ctx_alias is a requirement of the Context Gateway router, and defines the URI-bit for this Context. You'll use this string again in other settings.

ctx_alias setting

  1. site_url overrides the default System Setting, appending the ctx_alias.

site_url Context setting

Notice the syntax {site_url}amp/. The part in curly braces references the default MODX site_url dynamically.

  1. base_url does essentially the same as site_url but for a specific component of the URL.

base_url setting

  1. site_start and error_page should both have, as their values, the ID of the Resource that MODX will render as the "homepage" of the new Context. If you haven't created a Resource in the new Context yet, you can do so without leaving the current view, by right-clicking on the Context node in the Resource Tree, and selecting the "Quick Create" » "Document" option:

Quick Create

Give the new Resource a title, and ensure it's published. Once you hit save, the Tree will refresh and you'll see the new Resource with it's ID in parenthesis:

Resource Tree

Friendly URL System Setting

If you haven't already enabled Friendly URLs for your site, you'll need to do so for Ampify and Context Gateway to work. Hover over the cog icon again and chooose "System Settings".

System Settings menu item

At the top of the grid, choose the "Friendly URL" option from the "Area" dropdown:

Area dropdown

Locate the "Use Friendly URLs" setting and set it to "Yes".

FURLs

Plugin Properties

Next you'll setup the AMPIFY Plugin's properties, without which the Plugin doesn't fire. You'll need the ID of the AMP Template that you want to use. Ampify installs a sample Template.

sample AMP Template

In this installation the ID is 4. In the "Elements" tab of the Tree, open the "Plugins" section if not already open, and locate the AMPIFY Plugin:

Elements Tree

AMPIFY Plugin edit

In the Plugin Edit view, select the "Properties" tab:

Plugin properties

Click the button "Add Property Set". It's recommended to use a custom property set that will not be overwritten when you update the Extra.

Add Property Set

In the "Add Property Set" window, select "Create New Property Set" and give it a name:

Add Property Set Window

Hit save. In the property set dropdown, select your new set:

Dropdown

Modify the property values, as per your desired configuration. In this implementation, we'll add the Context Key and Template ID:

Property set for AMP

Save the property set.

Save property set

You'll also need to select the custom property set for the Plugin's Event triggers. Go to the "System Events" tab, and select the custom property set for both enabled Events:

Plugin Events

Don't forget to "Save" the Plugin!

Save Plugin

Now the Plugin should be running in 'context' mode. When you save a Resource, it will be added to the ContextResource table for the amp Context. The AMP view for the Resource will be a the Resource's URI, prefixed with the ctx_alias: amp/.