A template does nothing until you say where it applies. That is a display condition: include this template on these pages, exclude it from those.
“Use this single template for products, but not for the sample product.”
Where you can point a condition
| Group | Conditions |
|---|---|
| General | Entire Site, Front Page, Blog Home, Search Results, 404 |
| Singular | All Singulars, By Post Type, Specific Entry, Child Of (pages), By Term, By Author |
| Archive | All Archives, Author Archive, Date Archive, Post Type Archive, Taxonomy Archive, Specific Term Archive, and Shop when WooCommerce is active |
Each template type accepts the conditions that make sense for it:
- Single takes the Singular group and Front Page.
- Archive takes the Archive group, without Shop, and Blog Home.
- Header and Footer take the General, Singular and Archive groups, because chrome can apply anywhere.
- Loop item and Comments take By Post Type, Specific Entry, By Term and By Author.
- Product Archive takes Shop, Post Type Archive, Taxonomy Archive and Specific Term Archive. Single Product takes By Post Type, Specific Entry, By Term and By Author.
The Conditions screen shows only the conditions the template’s type accepts.
Blog Home matches the posts page. When the front page shows your latest posts, Blog Home matches the front page too.
Delta checks the conditions when a template is created. If a condition is not valid for the type, Delta does not create the template and returns the error, so fix the condition and ask again.
Which template wins
One template renders each slot. When several match, the most specific wins: Entire Site loses to All Singulars, which loses to By Post Type, which loses to Specific Entry. A condition naming one thing beats a condition naming a category of things.
If two templates tie, the higher priority number wins, then the one made last. Editing a template does not change that, and a page keeps its template when the page is updated.
A Single, Archive, Header or Footer template with no conditions never matches, unless it is a designated default on a site upgraded from before 0.2.0. Give it at least one include condition.
“List the display conditions and tell me which template wins for this page.”
The agent can also say which template one page gets, and why. When two templates tie, it names them, so you can give the one that should show a higher priority. Saving a template tells you the same: which templates it ties with, and which templates show nowhere.
Search, 404 and store pages
Some types take no conditions and match by type. A Search Results template renders the search page and a 404 template renders the not-found page. Build one of each and it applies. With WooCommerce active, the cart, checkout and account types work the same way.
Search Results and 404 still appear in the General group as conditions, which is how you give the search page its own header.
Showing and hiding chrome
Header and footer can be turned off. The controls differ on templates and on entries:
- On a template,
showHeaderandshowFooterare true or false, andchromeModesets the overall behaviour. - On an entry: a page, post, or product,
showHeaderandshowFootertakeinherit,showorhide.inheritmeans follow the template.
So a landing page that needs no navigation is one request: “Hide the header and footer on the Thanks page.”
For developers
Specificity is scored: entire_site 20, all_singular / all_archives 30, front_page / blog / search / not_found 40, post_type / post_type_archive / taxonomy 50, shop 55, child_of / term / author / date_archive 60, term_archive and author_archive with an author 70, post 80. A template with no conditions scores 10 when its type takes no conditions, or when it is a designated default on a site upgraded from before 0.2.0; otherwise it does not match. Ties break on priority (0 to 9999), then the template’s creation stamp (_21press_delta_tie_order, set once when the template is made; templates from before 0.4.0 were stamped with their last-modified time at upgrade), then post ID. delta/resolve-template takes entry or url and returns the winner, why, and any ties. Template writes answer with the warning condition_tie, and delta/list-conditions returns issues with ties and neverMatch. An empty conditions: [] never matches.
Conditions are include or exclude; an exclude match rejects the template outright. blog tests is_home, so it also matches latest posts on the front page. The catalog, including which names each type accepts, is filterable via 21press_delta_condition_catalog and 21press_delta_condition_catalog_by_type.