Who this is for. Content modellers building pages from blocks, and developers writing the block templates. After this page you can choose between a component area and a collection, set what each may hold, and explain to an author how to stage a block without deleting it.

What a component is

A component is an instance of a component layout: a name, the layout, and its own content for each of the layout's areas. It is data, not a template. One Card layout yields any number of cards, each with its own title and image, all rendered by the layout's one template.

A component belongs to the area that holds it. It has no site, no publication date and no URL of its own; it is stored with the revision whose area holds it, copied into each new revision, and deleted with the area. Its Component name is an editorial label used when searching for components in the admin, not something the template needs.

Component areas

An area whose input type has the component category holds exactly one component. The author sees an Add component button, picks a layout from the picker, and fills the component's own fields in place. A component area can hold a global component instead of a local one: see Global components. Use one for a fixed, single slot: one hero, one call to action at the foot of the page.

Collection areas

An area whose input type has the collection category holds an ordered list of components that the author adds, drags into order, hides and removes. This is how a page is built from sections. # Min. components and # Max. components on the area bound the list, checked when the record is saved.

Choose a collection when the author should decide how many blocks there are and in what order. Choose separate component areas when the design has a fixed number of different slots, each with its own rules, such as exactly one hero and exactly one footer banner.

Supported layouts: what an author may add

A component or collection area's Supported layouts is the whitelist of component layouts its picker offers, and it also limits the global components the picker offers to those of the same layouts. Two defaults to know:

  • An empty list offers every component layout of the site, including the layout the area belongs to, so a block can be placed inside itself. On a site with fifty component layouts, the author sees all fifty.
  • A list whose layouts have since been hidden or moved to another site offers nothing for them: the picker shows only layouts that are not hidden and belong to this site or to all sites.

Fill it in on every component and collection area, with only the blocks that make sense in that position. It is applied by the picker, when an author adds a component through the admin form. Because content can also arrive through the API, write the area's template to handle any component layout it supports, not only the ones offered there.

Collection elements and their published switch

Each item of a collection is an element with a position, a published switch, and either a local component or a reference to a global component. The published switch, on each element in the editing form, is widely missed: it lets an author stage a block, or take one down for a while, without deleting it.

  • An unpublished element is left out of the page for every visitor.
  • Signed-in admin users see it anyway while their Show unpublished setting is on, which is the default; add ?retrieveUnpublished=0 to a page's URL to see it as visitors do.
  • Elements added through the API are published unless the write says otherwise.

A template that loops over a collection receives only the published elements. The loop itself, written once in both engines, is on The collection loop and rendering a component.