Building sites
Site parts
A site part is a recurring piece of the site built in the page builder: a header, a footer, or a whole-page template such as the not-found page. Parts are page documents with their own revisions, saved and published exactly like pages. They are listed under Theme → Site parts.
The Site parts screen
A sidebar lists the groups, each with how many it holds:
| Group | Holds |
|---|---|
| Header and footer | header and footer parts |
| Page templates | Not found, Search results, Blog listing, Blog post and Custom parts |
| Content templates | each content type's Listing and Single entry templates, and each taxonomy's Term listing |
| Styles | core's Robot check, then the styles modules add (see Styles) |
The chosen group shows beside it, and the address keeps it (/admin/theme/parts/styles), so the builder's back button returns there. The filter box above the groups searches part names, kinds, content types and style names in every group at once, and the counts change to what matches.
Kinds
| Kind | Used for |
|---|---|
| Header | the top of every page |
| Footer | the bottom of every page |
| Not found | the page served with a 404 status for addresses that do not exist |
| Search results | the page at /search |
| Listing | the listing of one content type, at /<type> |
| Single entry | one entry of a content type, at /<type>/<entry> |
| Term listing | the entries under one term of a taxonomy |
The Kind list also offers Blog listing, Blog post and Custom; core does not place those on the site itself.
Creating and publishing
Theme → Site parts → New asks for the kind, a name and a starting design, then opens the part in the builder (/admin/builder/part/<id>). A header or footer is edited above or below a dimmed sample page body; a template is edited between the site's header and footer. Templates for content preview with the site's own entries where there are some.
Each kind has one site default. The first part of a kind you create becomes the default; Set as default moves it to another part, and Unset default leaves the kind with none. A part is used only once it is published: a draft part, even the default, leaves the site on the next choice down. Unpublish takes a part off the site, and Delete removes it and its revisions (pages that chose it go back to the site default). Editing parts needs the edit theme permission; publishing, choosing the default and deleting need publish theme.
Which header and footer a page gets
For each page Gansey picks the header (and, separately, the footer) in this order, skipping any choice that is not published:
- The part the page chose for itself in the builder's page card.
- A published part whose display rules match the address, highest priority first; between equal priorities, the one changed most recently.
- The site default.
- The built-in header or footer: the site name and navigation, or the site name and the year, styled by the Header & footer tokens.
Display rules
"Where it shows", on a header or footer, adds rules. A part with rules is used wherever any rule matches, in place of the default:
| Rule | Matches |
|---|---|
Path begins with (path_prefix) | the path or anything under it: /shop matches /shop and /shop/chairs |
Path is exactly (path) | that one path |
Page is (page) | one page |
Page is, or is under (child_of) | a page and every page below it in the navigation tree |
Paths are compared with a leading slash and no trailing slash, so shop/ and /shop are the same rule. Listings, entries, search and the not-found page are not pages, so only path rules apply to them. A page that chose a part itself keeps its choice whatever the rules say.
Not found and search
With no published Not found part, a missing address shows a heading, a line of text and a button back to the home page. With no Search results part, /search shows a heading, a search-form widget and a search-results widget. Both sit between the site's header and footer and ask search engines not to index them.
Search looks at published pages (title and description) and published entries (title, summary and text fields) and lists those containing every word of the query, ignoring case; modules can add their own results after these. The page reads the query from q, so the search form sends /search?q=oak+tables. Search pages are never cached.
Content templates
Listing, Single entry and Term listing parts belong to a content type (or, for term listings, a taxonomy) and appear under Content templates on the Site parts screen. When an entry, listing or term page is served, Gansey uses, in order:
- For an entry with its own page, that page.
- The published default template for the taxonomy (term pages only).
- The published default template for the content type; a term page without its own template uses the type's Listing template.
- A published site-wide default of the same kind, if the site has one.
- A built-in layout (see Content types and entries).
The header and footer around them follow the path rules above.
Styles
A style is a set of theme controls for one kind of element wherever it appears. Core has one, Robot check, for the "I'm not a robot" box; the rest come from modules, each for its own markup: the forms module (gansey-module-forms, from 2.0) adds Forms, for every form it draws. Without such a module there is no style for it. Choosing one in the Styles group opens its controls beside a live preview of a sample inside the site's header and footer, rendered with your unsaved tokens. Every control shows its default and has a Reset, and Reset this section puts them all back. A style with several elements (Forms has one per part of a form) lists them and shows one at a time; click a part of the preview to jump to its element, and the address remembers which one is open. Each element has its own Custom CSS box under its controls, starting from that element's selector, and the last entry in the list takes CSS for the whole section. Both are added at the end of every page, after modules' own stylesheets, so they win over the controls and the defaults, and they are saved and published with the theme. The controls are theme tokens in the custom map, so Save draft and Save & publish theme are the theme's own, with the same permissions, and the Tokens screen shows the same controls (the robot check on the Buttons tab, modules' styles on the Modules tab). An unset control leaves the stylesheet's own default.
Robot check has captcha-accent, captcha-background and captcha-radius (see Settings → Robot check for where it asks; a look chosen there replaces these). Modules declare theirs with ctx.theme.style_section; their keys start with the module's id (forms-… for the forms module, whose README lists them). A switched-off module's styles leave the screen, and what was saved for them stays in the theme until it comes back.