Integrating with AMP Dev Mode in WordPress

tl;dr In v1.3 the AMP plugin for WordPress no longer has to remove the Admin Bar to keep pages valid AMP.

The AMP plugin allows WordPress themes to be developed as usual and have their templates and stylesheets used to serve valid AMP pages. It does as much as possible to prevent serving invalid AMP pages, no matter what WordPress is outputting. One standard component of WordPress pages is the Admin Bar (aka Toolbar) which appears on the frontend once a user has logged-in to the Admin. The Admin Bar provides tools for administering a site, including links to create new posts, moderate comments, and access the Customizer. This Admin Bar has been a challenge for the AMP plugin to accommodate, but this is now changing.

When the AMP plugin first introduced theme support in v0.7, the Admin Bar was disabled entirely on AMP responses because of the 20KB+ of CSS that it adds to the page. In v1.0 the plugin restored the Admin Bar on AMP pages thanks in part to the CSS tree shaker, but still a checkbox was needed to turn off the Admin Bar when not enough CSS could be removed. In v1.2 the plugin was enhanced to eliminate this checkbox by automatically removing the Admin Bar when its CSS was too much for the 50KB limit on the page. As part of this, we had to fork core’s admin-bar.css to make it work with JavaScript turned off. Nevertheless, plugins also extend the Admin Bar with functionality which often requires JavaScript:

• Jetpack displays stats and notifications.
• Yoast SEO shows the page score along with notifications, alerts, and configuration links.
• Query Monitor displays performance and debugging information.
• Site Kit shows analytics for the current URL.

These Admin Bar integrations would be largely broken on AMP pages or at least limited in functionality (as if JS is turned off in the browser, since the plugin removes custom scripts).

In addition to the Admin Bar being important for normal site administration, it is also vital in an AMP context because the plugin adds an Admin Bar menu item to show the validation status, letting users know if markup was removed through sanitization to make the page valid AMP:

So the Admin Bar is important. But again, it would unfortunately often get removed due to excessive CSS, and even when it was included it could be broken or functionally limited due to plugins’ JS being sanitized out of the page. Not great!

All of this is about to change with the release of the AMP plugin v1.3 (now available as release candidate).

Introducing AMP Dev Mode

Last month I was going through the recurring task of updating the plugin to the latest version of the AMP Validator specification. I noticed something unusual at the very end of a diff of the protoascii files:

@@ -6847,6 +6874,14 @@ error_specificity {
   code: DOCUMENT_SIZE_LIMIT_EXCEEDED
   specificity: 120
 }
+error_specificity {
+  code: DEV_MODE_ONLY
+  # This should always trump any other error. It is asserting
+  # that the developer intends for this tag to be an error but
+  # that no additional errors should be reported for this tag.
+  specificity: 1000
+}
+
 # Error formats
 error_formats {
   code: UNKNOWN_CODE
@@ -7311,3 +7346,8 @@ error_formats {
   code: DOCUMENT_SIZE_LIMIT_EXCEEDED
   format: "Document exceeded %1 bytes limit. Actual size %2 bytes."
 }
+error_formats {
+  code: DEV_MODE_ONLY
+  format: "Tag 'html' marked with attribute 'ampdevmode'. Validator "
+          "will suppress errors regarding any other tag with this attribute."
+}Code language: Diff (diff)

What is this “AMP Dev Mode”? I searched through the issues in the AMP project and I found it introduced in amphtml#20974:

Allow non-AMP script tags in the JS validator if the [data-ampdevmode] attribute is present on the script tag.

This is for development environments that may want to run additional code (e.g. to do hot-reloading on code changes) while otherwise being compatible with AMP tools that do validation.

The scope for this Dev Mode expanded beyond just non-AMP script tags to apply to any element that is not valid in AMP! When the root html element has a data-ampdevmode attribute, any AMP validation errors that would normally be reported on an invalid element (or its attributes) will be suppressed if the element also has a data-ampdevmode attribute. This is exactly what we have needed for the Admin Bar.

In #3084/#3187 the AMP plugin added support for Dev Mode. The plugin’s sanitizers were updated to skip processing any elements that have the data-ampdevmode attribute, if the data-ampdevmode attribute is also at the root. The plugin adds this attribute to the link element for the admin-bar.css stylesheet which results in it not being added to style[amp-custom] and thus no longer counting against the 50KB limit for custom CSS. Similarly, the admin-bar.js script also gets this same attribute, preventing it from being removed by the sanitizers. Lastly, every element under the div#wpadminbar element DOM tree also gets this data-ampdevmode attribute; this prevents a user’s Gravatar img from being flagged as a validation error, for example. So, by adding these attributes WordPress core’s Admin Bar can be passed through without anything special done to it.

Note that an AMP page in Dev Mode is not a valid AMP page, as it’s explicitly not intending to be. The html element will only get the data-ampdevmode attribute added to it if the user is authenticated into WordPress and the Admin Bar is showing (source). This authentication requirement ensures that a crawler (like Googlebot) never encounters an AMP page in Dev Mode, thus ensuring the pages will be available on an AMP Cache and you won’t get Google Search Console complaining about AMP validation errors. There is an amp_dev_mode_enabled filter allowing you to override this. The amp_is_dev_mode() function can be used to determine if the current page is in Dev Mode, though if you’re adding code for the Admin Bar you can just assume this is the case, and add the data-ampdevmode attribute (which is just ignored if the page as a whole is not in Dev Mode).

When a page is in Dev Mode, you will currently see one single AMP validation error being reported by the AMP Validator Extension; opening the extension will show the following Dev Mode validation error:

Soon the extension will be updated to replace this error badge with something indicating Dev Mode. In any case, the AMP menu item in the Admin Bar indicates (✅) that there is no validation problems, that is, there are no unaccepted validation error sanitizations. If the AMP plugin’s sanitizers do happen to leak through a validation error, then you’ll still see a validation error count greater than one in the AMP Validator extension. Again, only elements which explicitly have the data-ampdevmode attribute can have their validation errors ignored by the AMP Validator.

How to Integrate with Dev Mode

There are a few ways that plugins can integrate with Dev Mode. First of all, if all of the plugin’s added markup is located inside the Admin Bar menu item, nothing has to be done because all descendant elements of div#wpadminbar will get the required Dev Mode attributes, as noted above.

Secondly, the AMP plugin will automatically add data-ampdevmode attributes to any enqueued stylesheets that have the admin-bar stylesheet as a dependency (recursively). This is all that was required for Yoast SEO. For example:

wp_enqueue_style(
	'my-admin-bar',
	plugin_dir_url( __FILE__ ) . 'admin-bar.css',
	array( 'admin-bar' ), // 👈👈👈
	'1.0'
);
Code language: PHP (php)

Similarly, if a plugin adds inline styles for the Admin Bar, all it have to do is use the wp_add_inline_style() for the admin-bar stylesheet, as was done in Pantheon HUD. For example:

wp_add_inline_style( 'admin-bar', 'wp-admin-bar-foo { /* ... */ }' );Code language: PHP (php)

Similarly to enqueued styles, an enqueued script can also be marked for Dev Mode automatically by just registering it with a dependency on the admin-bar script in core:

wp_enqueue_script(
	'my-admin-bar',
	plugin_dir_url( __FILE__ ) . 'admin-bar.js',
	array( 'admin-bar' ), // 👈👈👈
	'1.0'
);
Code language: PHP (php)

The AMP plugin recursively checks registered scripts and styles for a dependency on admin-bar and injects the data-ampdevmode attribute via the script_loader_tag and style_loader_tag filters, respectively. Using these filters is useful if you need to enqueue styles/scripts that don’t depend on admin-bar, for example see a pull request for Site Kit which uses these filters to mark react and wp-api-fetch for Dev Mode. This can also be seen in a Jetpack pull request to ensure mustache, backbone, and other scripts are included in Dev Mode; this is done using a script_loader_tag filter like this:

$script_handles = array( /* Handles for Dev Mode */ );
add_filter(
	'script_loader_tag',
	function ( $tag, $handle ) use ( $script_handles ) {
		if ( in_array( $handle, $script_handles, true ) ) {
			$tag = preg_replace(
				'/(?<=<script)(?=\s|>)/i',
				' data-ampdevmode',
				$tag
			);
		}
		return $tag;
	},
	10,
	2
);Code language: PHP (php)

The same approach can also be used for stylesheets using the style_loader_tag filter:

$style_handles = array( /* Handles for Dev Mode */ );
add_filter(
	'style_loader_tag',
	function ( $tag, $handle ) use ( $style_handles ) {
		if ( in_array( $handle, $style_handles, true ) ) {
			$tag = preg_replace(
				'/(?<=<link)(?=\s|>)/i',
				' data-ampdevmode',
				$tag
			);
		}
		return $tag;
	},
	10,
	2
);Code language: PHP (php)

Now, you can’t always easily add this data-ampdevmode attribute to the elements being added to the page. For example, when you call wp_localize_script() or wp_add_inline_script() there’s no way to filter the script tag that is printed. For such cases, there is also an amp_dev_mode_element_xpaths filter which allows you to provide XPath expressions to query the elements that you want to add the attribute to. While waiting for plugins to release direct support for AMP Dev Mode, it is straightforward to add the attribute to the required elements, as someone needed for Jetpack and Yoast SEO stylesheets (which won’t be necessary soon):

add_filter(
	'amp_dev_mode_element_xpaths',
	function ( $xpaths ) {
		$ids = array(
			'yoast-seo-adminbar-css',
			'wpcom-notes-admin-bar-css',
			'noticons-css',
			// Add more element IDs as desired.
		);
		foreach ( $ids as $id ) {
			$xpaths[] = sprintf( '//*[ @id = "%s" ]', $id );
		}
		return $xpaths;
	}
);Code language: PHP (php)

Similarly, in the Site Kit pull request, each of the added inline scripts get the string “googlesitekit” included. This allows all such inline scripts (added via wp_add_inline_script()) to be targeted with XPath via:

add_filter(
	'amp_dev_mode_element_xpaths',
	function ( $xpaths ) {
		$xpaths[] = '//script[ contains( text(), "googlesitekit" ) ]';
		return $xpaths;
	}
);Code language: PHP (php)

So there are several ways to add this data-ampdevmode attribute to elements on pages generated by WordPress and the AMP plugin.

Query Monitor on AMP Pages

Going back to v0.7 when the AMP plugin was suppressing the Admin Bar entirely, I proposed a pull request for the excellent Query Monitor plugin to prevent it from enqueueing the scripts and styles which would break AMP pages. I ultimately withdrew the PR from consideration because disabling Query Monitor functionality on AMP pages was fixing a symptom of broken AMP validity but not the underlying problem of being able to include its important functionality on AMP pages. Now with AMP Dev Mode, this can now be easily achieved! I’ve written a simple plugin called AMP Query Monitor Compat which adds data-ampdevmode to the scripts and styles that Query Monitor depends on, and behold the result:

Perhaps this code would make sense to be merged directly into Query Monitor.

Conclusion: AMP Hybrid Documents

One reason why I’m excited about AMP Dev Mode is that it’s an example of a hybrid document. As described in AMP as your framework, work is underway on a initiative called “Bento AMP” which intends to allow you to freely use AMP components standalone, outside the context of pages being managed by the AMP framework. AMP Dev Mode is an example of the inverse: a framework-official way of using non-valid markup in AMP pages. While this was technically possible before, you either had to remove the amp attribute from the html element or else live with the AMP Validator inundating you with validation errors (and wrestle with the AMP plugin’s sanitizers by rejecting sanitization for those errors). Now that AMP Dev Mode is a thing, the framework has a built-in way to describe these hybrid documents and still get benefits from the AMP Validator to catch problems with markup not explicitly marked as being part of Dev Mode.

Give it a try by testing 1.3-RC2!