Create and assign POM Theme templates

A template is markup applied to many pages at once. That multiplier is what makes templates useful and what makes a mistake in one expensive.

Requirements

• The POM theme active.
• Allow POM Theme writes open.
• pom_theme:read and pom_theme:write.
• manage_options on the acting user — templates sit behind a higher bar than content.
• Staging. This is the group where that stops being advice.

The tools

Plus, from the authoring group, pom_get_template_schema, pom_get_available_mergetags and pom_validate_template_markup.

Three template types

Archive, single and feed. Each expects a different structure, and each has its own published prompt: create_archive_template_pom, create_single_template_pom and create_feed_template_pom.

Those prompts encode the sequence below including the validation step. Start from one where it applies. See Prompt recipes.

The sequence

1. pom_theme_list_html_templates — see what exists. Creating a near-duplicate of an existing template is a common and avoidable mess.
2. pom_get_template_schema for the type you are creating.
3. pom_get_available_mergetags — the valid tags for this site.
4. Compose the markup.
5. pom_validate_template_markup — validate, including the merge tags.
6. Fix and re-validate until it passes.
7. pom_theme_upsert_html_template — write it.
8. pom_theme_get_template_assignments — see current assignments before changing them.
9. pom_theme_assign_template — assign it.
10. Look at the rendered pages.

Steps 2, 3 and 5 are the ones an assistant skips unless instructed. Say so:

Read the template schema and available merge tags first. Validate the markup and show me the result before writing anything.

Merge tags fail quietly

An invalid merge tag does not raise an error. It renders as literal text, or as nothing, on every page using the template.

Because that is invisible in the stored markup and visible on the site, validation is the only practical way to catch it before publication. Never skip step 5.

Assignment is the moment of impact

Writing a template changes nothing. Assigning it changes every page that matches.

Read the current assignments first, and know what you are replacing:

Show me the current template assignments before changing anything.

Assign to the narrowest target you can while testing. If the theme allows assigning per post type or per specific archive, use that rather than a site-wide assignment for a first trial.

After assigning

Check more than one page. A template that looks right on the post you were thinking of can be wrong on:

• a post with no featured image;
• a post with a very long or very short title;
• an archive with one result, and one with none;
• the first page and a paginated page;
• mobile width.

Then purge the cache. Templates affect every page they cover, so a cached copy is the difference between "it worked" and "it appears to have worked".

Deleting templates

pom_theme_delete_html_template removes a template. Check assignments first — deleting an assigned template leaves the pages that used it without one.

If a template is unused, deleting it is safe. If you cannot establish that it is unused, do not delete it.

Common problems

Related

• Theme template tools
• Validate builder or template markup before writing
• Configure POM Theme settings