Who this is for. Content modellers who own a site's component library, and anyone handing a site over to authors. After this page you can make the add-component picker usable at any size.

What the author sees

Clicking Add component in a component or collection area opens a picker with three tabs: the component layouts the area accepts, the global components it accepts, and a clipboard of copied components. Each layout is a tile: the layout's image above its name, or a generic puzzle icon when there is no image, with a search box that filters by name. The same image appears as an icon in the header of every component of that layout in the editing form. That is the whole of the author's selection experience; there is no description and no grouping.

Page layouts are chosen differently, from a plain list of names on the record's form, so their images are not shown to authors.

Making a useful thumbnail

Set the image on the layout's Categorization tab. A good thumbnail is a schematic of the block's shape, not a screenshot of one filled-in instance:

  • grey boxes for images, lines for text, a filled shape for a button, in the positions the template puts them;
  • the same size and proportions for every thumbnail, so the grid of tiles reads evenly;
  • nothing that varies between instances, such as a photo or a headline: real content differs from one instance to the next;
  • a visible difference between variants: a two-column and a three-column block should not look alike.

Redraw the thumbnail whenever the template's structure changes, and keep an out-of-date thumbnail high on the list of things to fix.

Layout categories

Layout categories are a tree kept under Customization › Layout Categories, and a layout can be placed in one from its Categorization tab. In this version neither the picker nor the layout list uses them: they group nothing an author sees. They are readable through the API (/cdna-api/common/layout-categories, and category on a layout) and from a template (getCategory() on a layout), so they are useful for your own tools, such as a gallery of the component library grouped by family.

Keeping a large library findable

Past about thirty component layouts, authors stop finding the right one. In order of effect:

  1. Supported layouts on every component and collection area. An area then offers only the handful of blocks that make sense there, and its global component tab offers only global components of those layouts. An area with no supported layouts offers every component layout of the site: see Components and collections.
  2. Names that sort and search well. The search box matches names, so give related blocks a shared word (Card: image, Card: icon, Card: quote).
  3. A thumbnail on every component layout, drawn as above.
  4. Hiding retired layouts. A hidden layout leaves the picker; components already using it keep rendering. See Site scoping, identifiers and hiding.
  5. Tags and categories on components. Two switches in the Common module's Component settings, Use tags for components and Use categories for components, both off by default, let components and global components be tagged and categorised. In the picker they filter the global components tab, which otherwise shows at most fifteen of the site's global components and fifteen shared ones until the author searches.

For authors, a page that shows every component with its thumbnail and purpose is worth more than any of these: see Documenting your component library.