CWA 2 is a prerelease (2.0.0-alpha), heading for a beta. It runs production sites; configuration can still change between releases, always with upgrade notes. View versions and support
Building Your Ui

Categorise and Restrict

Best practice for the components you give editors — an icon and a group on every component, descriptions written for editors, and limits on what each component group and UI variant offers.

Editors build pages from the add component dialog. Every component you write appears there, so a site with twenty components and no organisation gives them a long list of names to guess from. A few minutes in each component's defineCwaConfig, and in each <CwaComponentGroup>, keeps the choice short and clear.

IMAGE: the add component dialog with its search, the "Already in this group" chips, and the list in sections (Layout, Media, Text), each row with an icon

Give Every Component an Icon and a Group

// app/app/cwa/components/Title/Title.vue
defineCwaConfig({
  name: 'Title',
  description: 'The main heading of a page',
  icon: 'heading',
  group: 'Text',
})
  • group sorts the dialog into sections, listed A to Z. Once any component has a group, those without one are listed under Other, so give every component a group. Keep the set small and reuse the same words: Text, Media, Layout, Forms.
  • icon is shown in the component's row and beside its name. A row of icons is scanned faster than a list of names. Use a built-in kind such as 'heading' or 'image', a Lucide icon, or an icon.svg in the component's folder; see Component Files › Icons and Previews.
  • image, or a preview.webp beside the component, shows what the component looks like in the detail view. Add one where the name alone doesn't make that clear.

Write Descriptions for Editors

The dialog's search matches the name first, then the group, then the description. Write the description for the person adding the component, not the developer who built it:

Instead ofWrite
Renders the HtmlContent entityParagraphs, headings, lists and links, styled to match the site
Uploadable Image with imagine filtersA picture uploaded to the site, with **alt text** for screen readers
Collection of BlogArticleDataA paged list of articles. The page's search and filters apply to it

Say what it's for and where it suits, in one or two short sentences. The list shows it as plain text and the detail view formats it, so keep Markdown light: a word in bold or a link to your own help. Give the component a name an editor would use too: "Body Text", not "Html Content".

Restrict What Each Component Group Holds

Most component groups suit only some components. A navigation bar holds links, and a header button group holds one button. List them on the group:

<CwaComponentGroup
  reference="top"
  :location="$cwa.resources.layoutIri.value"
  :allowed-components="[CwaComponentNames.NavigationLink]"
/>

<CwaComponentGroup
  reference="headerButton"
  :location="$cwa.resources.layoutIri.value"
  :allowed-components="[CwaComponentNames.HeaderButton]"
  :max-components="1"
/>
  • allowed-components hides every other component from the dialog for that group, and the API refuses them. CwaComponentNames is type-checked, so a typo or a removed component fails vue-tsc.
  • max-components caps how many components the group holds.
  • A component that belongs in only a few places can be opt-in: mark its PHP class with #[Silverback\ExplicitAllowOnly], and it's offered only where a group lists it.

<CwaComponentGroup> › Allowed Components covers each rule, including the list naming every type already placed in the group.

Restrict Styles per UI Variant

A UI variant often suits only some of the primary component's styles. Declare the ones it suits in the variant's own defineCwaConfig, and the admin offers only those while the variant is picked:

// app/app/cwa/components/UiComponent/ui/JournalPageLayout.vue
defineCwaConfig({
  name: 'Journal Page',
  styles: {
    'top-rule': { label: 'Rule above', classes: 'border-t border-stone-700 pt-10' },
  },
})

A variant without styles offers the primary component's. Switching UI keeps only the stored styles the new variant defines, so an editor never ends up with a style that does nothing. Leave allowMultiple off unless the styles are made to combine.

Start New Components Filled In

A new component with empty fields shows nothing until an editor fills it in. Give it defaultData, so it shows something they can recognise and change:

defineCwaConfig({
  name: 'Quote',
  group: 'Text',
  icon: 'quote',
  defaultData: { quote: 'Add the quote here', author: 'Who said it' },
})

A component with no text of its own, such as an image, can show <LazyCwaUiEditPlaceholder> in edit mode instead; see Component Files › Part 3: Editing on the Page.