Guide 04 · Developer docs

Input types, layouts, components and images

The platform's central abstraction, in one line: an input type defines what an editor can enter, a layout area binds one input type to a named slot, a layout groups areas and points at a template, a record or component holds the content for each area, and the template reads it back. Read this book straight after the template languages.

L1–L3 Start reading
9
units
45
pages

Who this guide is for

Theme developers who write page and component templates, content modellers who create input types, layouts and their areas, and anyone reviewing either. It sits at levels L1 to L2: it assumes you can build and deploy a template (Core dna for site builders) and know Smarty or Twig (Template languages). Every template example is given in both engines.

The units, in order

  1. The model, end to end: the chain from an editor's field to the HTML, and where content is stored. Read it first.
  2. Input types: what an editor can enter, and what a template gets back for each category and editor.
  3. Layouts: a template joined to a set of editable areas; page designs and reusable components.
  4. Layout areas, groups and attributes: the author's editing form, field by field.
  5. Components, collections and global components: building a block library, and blocks that query records.
  6. Rendering areas in templates: every getter, what it returns, what it costs, and testing for empty.
  7. The shorthand, and working with each input type: the normal way to print a layout area, and why it keeps live preview working.
  8. Images end to end: from the image area to the delivered file.
  9. Patterns, live preview and upkeep: the idioms every mature site reinvents, and keeping a library tidy.

A component template, the usual way

A component with a heading (Text), a body (Richtext) and a cssClasses (Text) area. Values printed on the page use the shorthand; the value inside the class attribute uses getAreaText(), because in live preview the shorthand wraps text in an editable element that does not belong inside an attribute (The shorthand and live preview):

Template code templates/components/promo.html 
<section class="promo {$component->getAreaText('cssClasses')}">
  <h2>{$component->heading}</h2>
  {$component->body}
</section>
<section class="promo {{ component.getAreaText('cssClasses') }}">
  <h2>{{ component.heading }}</h2>
  {{ component.body }}
</section>

Six things to know first

  1. Content lives in revisions. On a page, a blog post or any versioned record, every area getter reads the active revision: {$page->getAreaText('intro')} is {$page->getActiveRevision()->getAreaText('intro')}, and {$page->intro} is the shortest way to print it (Where content is stored, and what a change does to it).
  2. Renaming a layout area keeps the content, not the templates. The content follows the area under its new name; update every template that reads the old name at the same time (Renaming and retiring without losing content).
  3. Supported layouts decide what an author may add. A collection area offers only the component layouts listed there (Supported layouts: what an author may add).
  4. Books and units render through their default templates. Those templates read the layout's areas, not the layout's own template (Which records render through their layout).
  5. Smarty's empty() is never true for an image. Test the blank image instead (Testing whether an area is empty).
  6. Widgets are deprecated. A block that lists records is a component whose template uses the query helper $_query (Computed blocks with the query helper).

Contents

9 units, in reading order.

The model, end to end

The whole chain from an editor's field to the HTML, before any one link is explained in detail, and where the content actually lives. For everyone who will touch a layout or a template. 2 pages

The chain from input type to template Five links carry every piece of content to the page: an input type, a layout area, a layout, a record or component, and the template. What each link is, where it lives, why a new page type starts in the admin, and the word "area", which means two things. Read more Where content is stored, and what a change does to it Content lives in a record's revisions, and each value is linked to its layout area by the area's id, not to the template. From that you can predict what a template rewrite, an area rename, a layout switch, a type change, hiding and deleting each do to an author's content. Read more

Input types: what an editor can enter

Input types are the vocabulary of every layout: what kind of value an editor can enter, and what a template gets back. For content modellers who create them and developers who render areas built on them. 3 pages

Category and editor decide behaviour An input type's name is a label; its category and, for text, its editor decide what an author sees, what is stored and which getter reads it. The seven categories and thirteen editors, the code and colour options, and what the shorthand does with each. Read more Select options, keys and design tokens A select stores the option's key, not its label, so the key is what templates and stylesheets depend on. Writing options, changing them safely, one select type per design choice, and finding the duplicate and unused types a mature site collects. Read more Record and records pickers A record or records input type lets an author point at other content: a page, a form, a product, a custom entity record. Which content types it can reference, narrowing the picker to one parent, what is stored, and what a template gets back when the record is hidden. Read more

Layouts

A layout joins a template file to a set of editable slots, and its controller field decides whether it is a page design or a reusable component. For whoever creates and retires layouts, and the developers whose templates they point at. 4 pages

What a layout is, field by field A layout joins one template file to a set of layout areas and says which records may use it. Every field of the layout form and what it affects, the template path and how it fails, where the layout areas are defined, and custom fields on the layout itself. Read more Page and component layouts The controller field decides what a layout is for: set, it is a design that records of one kind can choose; empty, it is a component that authors place inside other content. Which records see which layouts, which of them use the layout's template, and how a component lists records. Read more Thumbnails, categories and the author's picker When an author adds a component, a layout's name and thumbnail are all they have to choose by. What the picker shows, what makes a useful thumbnail, what layout categories do and do not do, and how to keep a library of thirty or more components findable. Read more Site scoping, identifiers and hiding Three fields that matter once a site has history: which sites a layout belongs to, the identifier that lets code find it without an id, and hiding, the way to retire a layout without breaking the records that use it. Read more

Layout areas, groups and attributes

A layout's areas are the author's editing form, and this is where authoring quality is won or lost: every field of a layout area, the rules and defaults, groups, and attributes. For content modellers, and developers who read what they build. 5 pages

The fields of a layout area Every field of a layout area and what it does to the author's editing form: the name templates read, the label, help and info an author reads, ordering, hiding, and marking the area for search. Rules, groups and attributes have their own pages. Read more Validation and default content The checks a record must pass when it is saved, set on the input type (a pattern, a maximum length) and on the layout area (required, a minimum and maximum number of components), the messages an author sees, and how default content fills an empty area at render time. Read more Area groups Groups split a long editing form into named, collapsible sections, which is the difference between a usable form and a wall of forty fields. How groups appear to the author, how areas move in and out of them, and how to name them. Read more Attributes: settings, not content Marking a layout area as an attribute moves it out of the main editing form, so authors see content first and settings second. Attributes of a whole block, attributes attached to one field, the rule for choosing, and a worked image with alt text, crop and caption attached to it. Read more A checklist for a well-built layout A list to review every new or changed layout against, written from the author's side of the editing form: names, labels and help, rules, defaults, groups, attributes, supported layouts and the thumbnail. Read more

Components, collections and global components

Components are blocks of stored content placed in component and collection areas; global components are shared blocks reached by identifier. For developers and content modellers building a block library. 5 pages

Components and collections A component is data: one instance of a component layout with its own content. A component area holds one, a collection area an ordered list of them. Supported layouts, the whitelist that decides what an author may add, and the collection element's own published switch. Read more The collection loop and rendering a component The one loop every theme writes, in both engines, covering local and global components alike; what getHtml() hands the component's template; how to pass a value down to it; and why a variable set in the page template does not reach it. Read more Nesting components, and what depth costs A component can hold its own collection, so blocks nest to any depth. The nested loop in both engines, the two costs that grow with depth, how to count what a page renders, and the ways to flatten a tree that has grown too deep. Read more Global components A global component is one component with its own identifier and revisions, shown wherever a template or a collection asks for it. How identifiers are scoped to sites, how to reach one from any template in both engines, and when a global beats repeated local copies. Read more Computed blocks with the query helper A block whose content is computed rather than authored is a component whose template queries records with $_query, configured by an area or two. The four query methods, the entities they may read, keeping the query out of the loop, and when the result can go stale. Read more

Rendering areas in templates

The methods a template calls to read layout areas, the same on every record that has them: what each returns, what it costs, and how to tell an empty area from a filled one. For template developers working in Smarty or Twig. 5 pages

The area getters and what each costs One set of getters reads areas on every record that has them: pages, book pages, blog posts, product descriptions, custom entity records, global components and components. Every getter, what it returns when an area is filled, empty or missing, and what each call costs. Read more Text, multiselect values and dates The shorthand prints a text area's value and getAreaHtml is its explicit form; getAreaText returns what the author stored, for attributes and comparisons; getAreaValues returns a multiselect's keys as an array and getAreaDate a date object. What each returns, the empty case, and the patterns for class lists and dates. Read more Images, files, records and collections The getters for areas that point at something: an image, a file, one record or several, a component or a collection. What each returns when the layout area is empty, which ones run a query, and where the images and collections units take over. Read more Area introspection, raw content and attributes Getters most templates never need: the type, category and editor of a layout area, for components that adapt to how an author configured it; the raw content objects the typed getters are built on; and the accessors that read an area's attributes. Read more Testing whether an area is empty An area can be empty in four ways, and the getters report it as null, an empty string or array, a blank object or an empty collection. The test for each getter, the one check that covers every category, and why empty() is never true for an object in Smarty. Read more

The shorthand, and working with each input type

Reading a layout area as a property, the shorthand, and what each input type gives a template. For developers writing and reviewing page and component templates. 6 pages

How the area shorthand resolves Reading an area as a property, such as {$component->heading}, is the house style for printing it. It is not sugar for a getter: it tries a real getter first, then resolves the name by the area's category and editor. The order, and what each type returns. Read more The shorthand and live preview In the admin's live preview, the shorthand keeps every text area editable in place, while getAreaText() keeps only rich text editable. The wrapper that does it, a before and after, why it breaks attributes, and why the shorthand survives an editor change. Read more Limits of the shorthand, and the rule The shorthand resolves areas only on the frontend, loses to a real getter of the same name, throws on an unknown name in Smarty, takes no arguments and is harder to search for. Each limit, its symptom and guard, and the rule reviewers apply. Read more Text, select and switch areas in templates What text, textarea and rich text areas store and how to escape each; reading one select key or many and mapping them onto CSS classes; and why a switch is a boolean through the shorthand but the string 1 through getAreaText(). Read more Dates, numbers, colours and code areas Formatting a date or datetime in both engines and handling an empty one; what number, email and math areas check, which is less than their names suggest; feeding a colour into a CSS custom property; and the escaping decision for a code area. Read more Files, records and component areas Rendering a download link with the file's name and size, and why files are public; linking to a record and reading a set of records once; what the shorthand gives for component and collection areas; and where images are covered. Read more

Images end to end

Everything a template does with an image, from the image area to the delivered file: the image object, resizing and converting, the URL parameters, picture tags, compression and every image setting. For developers who render images and site builders who configure them. 8 pages

From an image area to an image How a template gets the image out of an image area, why an empty area gives a blank image rather than nothing, the test that tells them apart, and the setting behind grey placeholder boxes that some visitors see and others do not. Read more The image object What the image object tells you (dimensions, format, name and path), how to reserve space with its aspect ratio, the shape of the URL it builds, and the two methods that exist on it but are not available to templates. Read more Resizing, converting and rendering an image Resize an image, convert its format and render the tag: what getResized(), toOptimizedFormat(), toFormat() and getHtml() do, the order to chain them in and why, and what happens to pixel sizes in a style attribute. Read more Resize strategies The seven strategies getResized() accepts, what each does to the same photo, which dimensions each needs, and why most of the names have no effect of their own in a hand-written image URL. Read more Image URL parameters Every resize and conversion a template can ask for is also a query parameter on the image URL. The parameters, worked URLs, and when to write a URL rather than use the template object. Read more Picture tags and responsive sources Why the same template renders an img on one site and a picture tag with a WebP source on another, which sources the platform generates and how offeredSizes changes them, and when to write the picture element yourself. Read more Compression, image services and imported images What happens to an image's bytes between the file manager and the browser: lossy compression and its quality override, the image services that resize and convert, what happens when none can, and the setting that imports images pasted from other sites. Read more Image settings Every setting that changes how an image is rendered, delivered or stored, in one table with its key, default and whether you would normally change it, followed by the physical-size, title-tag and upload settings in detail and a starting point for a new site. Read more

Patterns, live preview and upkeep

Patterns to copy into component templates, how live preview keeps or loses in-place editing, and the upkeep of a library that keeps growing: naming, auditing, renaming and retiring, and a gallery for authors. For developers and content modellers who already build layouts and components. 7 pages

Pattern: attributes to CSS classes A helper that turns a component's attribute areas (selects, multiselects and switches) into one class string, given in full in Smarty and Twig, with the rules for naming option keys and switches so the classes come out right. Read more Pattern: heading levels and load priority Two values a parent decides and its children use: the heading level, kept in the template context so that nested components produce a usable outline, and the load priority, passed to each component so that the first images load eagerly and the rest lazily. Read more Safe defaults, placeholders and the adaptive component How an unfinished page can render something intentional: default content, the image placeholder, the empty test that fits each getter, and when a missing value should hide the whole block. Then the adaptive component, and why to use it sparingly. Read more Live preview and testing in-place editing What turns on in-place editing in live preview, which template calls keep it and which lose it, the three settings that govern it, and a short test to run on representative pages before handover. Read more Naming conventions and auditing a site How to name input types, layouts and layout areas so that the author's pickers stay usable and no area clashes with a getter; a quarterly audit for unused layouts, duplicate input types and orphaned areas; and what tags and categories on components actually organise. Read more Renaming and retiring without losing content The full procedure for renaming a layout area, moving content to a new area or type, and retiring an area or a layout: the order of steps that keeps authors' content, why hiding comes long before deleting, and what cannot be recovered. Read more A component gallery for authors Build a page that lists every component layout with its thumbnail, purpose and areas, read from the layout records themselves so that it cannot drift from what authors can choose, and keep its thumbnails honest. Read more