Skip to content

Legacy Templating And Customization

Jump to bottom
Ryan Kienstra edited this page Apr 4, 2018 · 5 revisions

Version 0.7 introduced "Native AMP" and "Paired Mode (more details). These allow you to use either all of your theme's templates ("Native AMP"), or those which you select ("Paired Mode").

But this plugin also ships with a default template that looks nice and clean and we tried to find a good balance between ease and extensibility when it comes to customization.

You can tweak small pieces of the template or the entire thing depending on your needs.

AMP Customizer

The plugin ships with its own Customizer that you can use to tweak various parts of the default template like colors.

Disabling the AMP Customizer Settings

If you're using a completely custom template, you may want to disable the AMP Customizer Settings:

add_filter( 'amp_customizer_is_enabled', '__return_false' );

Note that this needs to be called before the after_setup_theme hook to work.

Where Do I Put My Code?

The code snippets below and any other code-level customizations should happen in one of the following locations.

If you're using an off-the-shelf theme (like from the WordPress.org Theme Directory):

If you're using a custom theme:

  • functions.php (or via a 'require' call to files that load from functions.php).
  • Any of the options above.

Theme Mods

The default template will attempt to draw from various theme mods, such as site icon, if supported by the active theme.

Site Icon

If you add a site icon, we will automatically replace the WordPress logo in the template.

If you'd prefer to do it via code:

add_filter( 'amp_post_template_data', 'xyz_amp_set_site_icon_url' );

function xyz_amp_set_site_icon_url( $data ) {
	// Ideally a 32x32 image
	$data['site_icon_url'] = get_stylesheet_directory_uri() . '/images/amp-site-icon.png';
	return $data;
}

Logo Only

If you want to hide the site text and just show a logo, use the amp_post_template_css action. The following colous the title bar black, hides the site title, and replaces it with a centered logo:

add_action( 'amp_post_template_css', 'xyz_amp_additional_css_styles' );

function xyz_amp_additional_css_styles( $amp_template ) {
	// only CSS here please...
	?>
	header.amp-wp-header {
		padding: 12px 0;
		background: #000;
	}
	header.amp-wp-header a {
		background-image: url( 'https://example.com/path/to/logo.png' );
		background-repeat: no-repeat;
		background-size: contain;
		display: block;
		height: 28px;
		width: 94px;
		margin: 0 auto;
		text-indent: -9999px;
	}
	<?php
}

Note: you will need to adjust the colors and sizes based on your brand.

Template Tweaks

You can tweak various parts of the template via code.

Featured Image

The default template displays the featured image. If you don't want to display the featured image in your amp page, use the following code:

add_filter( 'amp_post_template_data', 'xyz_amp_remove_featured_image' );

function xyz_amp_remove_featured_image( $data ) {
    $data['featured_image'] = false;
    return $data;
}

Content Width

By default, your theme's $content_width value will be used to determine the size of the amp content well. You can change this:

add_filter( 'amp_content_max_width', 'xyz_amp_change_content_width' );

function xyz_amp_change_content_width( $content_max_width ) {
	return 1200;
}

Template Data

Use the amp_post_template_data filter to override default template data. The following changes the placeholder image used for iframes to a file located in the current theme:

add_filter( 'amp_post_template_data', 'xyz_amp_set_custom_placeholder_image' );

function xyz_set_custom_placeholder_image( $data ) {
	$data[ 'placeholder_image_url' ] = get_stylesheet_directory_uri() . '/images/amp-iframe-placeholder.png';
	return $data;
}

Note: The path must pass the default criteria set out by validate_file and must be somewhere in a subfolder of WP_CONTENT_DIR.

Schema.org (JSON) Metadata

The plugin adds some default metadata to enable "Rich Snippet" support. You can modify this using the amp_post_template_metadata filter. The following changes the type annotation to NewsArticle (from the default BlogPosting) and overrides the default Publisher Logo.

add_filter( 'amp_post_template_metadata', 'xyz_amp_modify_json_metadata', 10, 2 );

function xyz_amp_modify_json_metadata( $metadata, $post ) {
	$metadata['@type'] = 'NewsArticle';

	$metadata['publisher']['logo'] = array(
		'@type' => 'ImageObject',
		'url' => get_template_directory_uri() . '/images/my-amp-metadata-logo.png',
		'height' => 60,
		'width' => 600,
	);

	return $metadata;
}

Template Meta (Author, Date, etc.)

For the meta section of the template (i.e. author, date, taxonomies, etc.), you can override templates for the existing sections, remove them, add new ones.

Example: Override Author Template from Theme

Create a folder in your theme called amp and add a file called meta-author.php with the following:

<li class="xyz-byline">
	<span>Anonymous</span>
</li>

Replace the contents, as needed.

Example: Adding custom templates for homepage and page for posts

As for v0.6 pages are supported by the plugin, including the homepage (page on front) and page for posts (blog). After enabling “page” post type support in the AMP general settings, all pages will be enabled for AMP by default, unless the page is the homepage, the blog page, or a page that is assigned to a custom template. (You can auto opt-in to AMP support for all pages via add_filter( 'amp_post_status_default_enabled', '__return_true' ).) To opt-in these pages for AMP, just enable support via the AMP support toggle in the page's publish metabox. The homepage can re-use the single.php template as a default, but the page for posts should get a custom template assigned so that the list of posts (The Loop) is present. To modify the template for the homepage or page for posts, put the following in your theme's functions.php:

function xyz_filter_home_and_blog_amp_post_template( $template, $template_type, $post ) {
	if ( 'page' === $template_type && 'page' === get_option( 'show_on_front' ) ) {
		if ( (int) get_option( 'page_on_front' ) === $post->ID ) {
			$template = dirname( __FILE__ ) . '/amp/home.php';
		} elseif ( (int) get_option( 'page_for_posts' ) === $post->ID ) {
			$template = dirname( __FILE__ ) . '/amp/blog.php';
		}
	}
	return $template;
}
add_filter( 'amp_post_template_file', 'xyz_filter_home_and_blog_amp_post_template', 10, 3 );

Then you can add an amp/home.php which is basically a fork of the plugin's bundled single.php and the same for amp/blog.php with this key addition:

<ul>
	<?php while ( have_posts() ) : the_post(); ?>
		<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
	<?php endwhile; ?>
</ul>
<?php the_posts_pagination(); ?>
Example: Override Taxonomy Template via filter

This will load the file t/meta-custom-tax.php for the taxonomy section:

add_filter( 'amp_post_template_file', 'xyz_amp_set_custom_tax_meta_template', 10, 3 );

function xyz_amp_set_custom_tax_meta_template( $file, $type, $post ) {
	if ( 'meta-taxonomy' === $type ) {
		$file = dirname( __FILE__ ) . '/t/meta-custom-tax.php';
	}
	return $file;
}

In t/meta-custom-tax.php, you can add something like the following to replace the default category and tags with your custom author taxonomy:

<li class="xyz-tax-authors">
	<?php echo get_the_term_list( $this->get( 'post_id' ), 'xyz-author', '', ', ' ); ?>
</li>
Example: Remove Author from header_meta

This will completely remove the author section:

add_filter( 'amp_post_article_header_meta', 'xyz_amp_remove_author_meta' );

function xyz_amp_remove_author_meta( $meta_parts ) {
	foreach ( array_keys( $meta_parts, 'meta-author', true ) as $key ) {
		unset( $meta_parts[ $key ] );
	}
	return $meta_parts;
}
Example: Add Comment Count to footer_meta

This adds a new section to display the comment count:

add_filter( 'amp_post_article_footer_meta', 'xyz_amp_add_comment_count_meta' );

function xyz_amp_add_comment_count_meta( $meta_parts ) {
	$meta_parts[] = 'xyz-meta-comment-count';
	return $meta_parts;
}

add_filter( 'amp_post_template_file', 'xyz_amp_set_comment_count_meta_path', 10, 3 );

function xyz_amp_set_comment_count_meta_path( $file, $type, $post ) {
	if ( 'xyz-meta-comment-count' === $type ) {
		$file = dirname( __FILE__ ) . '/templates/xyz-meta-comment-count.php';
	}
	return $file;
}

Then, in templates/xyz-meta-comment-count.php:

<li>
	<?php printf( _n( '%d comment', '%d comments', $this->get( 'post' )->comment_count, 'xyz-text-domain' ) ); ?>
</li>

Custom CSS

Rule Additions

If you want to append to the existing CSS rules (e.g. styles for a custom embed handler), you can use the amp_post_template_css action:

add_action( 'amp_post_template_css', 'xyz_amp_my_additional_css_styles' );

function xyz_amp_my_additional_css_styles( $amp_template ) {
	// only CSS here please...
	?>
	.amp-wp-byline amp-img {
		border-radius: 0; /* we don't want round avatars! */
	}
	.my-custom-class {
		color: blue;
	}
	<?php
}
Completely Override CSS

If you'd prefer to use your own styles, you can either:

  • Create a folder in your theme called amp and add a file called style.php with your custom CSS.
  • Specify a custom template using the amp_post_template_file filter for 'style' === $type. See the "Override" examples in the "Meta" section for examples.

Note: the file should only include CSS, not the <style> opening and closing tag.

Head and Footer

If you want to add stuff to the head or footer of the default AMP template, use the amp_post_template_head and amp_post_template_footer actions.

add_action( 'amp_post_template_footer', 'xyz_amp_add_pixel' );

function xyz_amp_add_pixel( $amp_template ) {
	$post_id = $amp_template->get( 'post_id' );
	?>
	<amp-pixel src="https://example.com/hi.gif?x=RANDOM"></amp-pixel>
	<?php
}

AMP Endpoint

If you don't want to use the default /amp endpoint, use the amp_query_var filter to change it to anything else.

add_filter( 'amp_query_var' , 'xyz_amp_change_endpoint' );

function xyz_amp_change_endpoint( $amp_endpoint ) {
	return 'foo';
}

Custom Template

If you want complete control over the look and feel of your AMP content, you can override the default template using the amp_post_template_file filter and pass it the path to a custom template:

add_filter( 'amp_post_template_file', 'xyz_amp_set_custom_template', 10, 3 );

function xyz_amp_set_custom_template( $file, $type, $post ) {
	if ( 'single' === $type ) {
		$file = dirname( __FILE__ ) . '/templates/my-amp-template.php';
	}
	return $file;
}

Note: there are some requirements for a custom template:

  • You must trigger the amp_post_template_head action in the <head> section:
do_action( 'amp_post_template_head', $this );
  • You must trigger the amp_post_template_footer action right before the </body> tag:
do_action( 'amp_post_template_footer', $this );
  • Within your amp-custom style tags, you must trigger the amp_post_template_css action:
do_action( 'amp_post_template_css', $this );
  • You must include all required mark-up that isn't already output via the amp_post_template_head action.

Notice: Please also see the plugin documentation on amp-wp.org

Clone this wiki locally