Adding, Removing, and Reordering Components
Last updated
Last updated
Components are added, removed, and reordered in fields called component lists, of which there are four types.
Components that contain child component lists need to do two things: Render an editable list in their template, and specify a config in their schema.yml.
You'll notice that data-editable is the same attribute used to specify editable fields. The component-list handlebars partial comes from our included library of helpers and partials, and renders a list of components with their data. The element with data-editable must be the immediate parent of the components in the list.
This would create a basic list with drag & drop functionality. When selecting components inside this list, you'd see Remove and Add Component buttons that would allow you to remove those components or add new instances of some-component and some-other-component. When adding components to a list, a component's default data is cloned into a new instance.
Basic lists also allow placeholders, which will display (and prompt users to add components) when the list is empty.
In edit mode, basic component lists may be expanded and collapsed. This feature only affects edit mode, so it's useful for removing visual clutter in component lists that aren't displayed in view mode. Note that this is different than invisible component lists, which are editable through the "Find on Page" / "Find on Layout" drawer.
Collapsible lists will always display their placeholder, as well as an expand/collapse toggle.
When collapsible lists are empty, they'll display the same "Add Component" button as other component lists.
Similarly to editable fields, component lists may contain validation for min and max lengths.
Similarly to text inputs, component lists may also prevent users from adding components over the maximum with enforceMaxlength.
Components in the <head> of the page require a different syntax. Much like how you denote the start of <head> components with a <!-- data-editable --> comment, you use html comments for the beginning and the end of these component lists.
The schema.yml config of a head list is the same as a basic list.
Head component lists get added as tabs to the Find on Page drawer in Kiln automatically, allowing them to be edited.
It's useful to have a component list for various components that might not have public-facing visual elements, such as tracking scripts, affiliate marketing scripts, pixels, or lightboxes. If these components must live in the <body> (rather than the <head>), you may add a property to the component list to make them appear as tabs in the Find on Page drawer, allowing them to be edited.
Page areas are a special type of component list that only exists in layouts. By adding a property to the layout's schema.yml, you can specify that certain component lists exist in the page's data (and thus are specific to that page) rather than the layout's data (thus being shared amongst all pages with that layout).
The data for component lists inside components (including layouts) looks like an array of objects:
Meanwhile, the data for component lists inside page data looks like an array of strings:
Page areas may also have placeholders.
All types of component lists allow whitelisting of components using the include property in the config. You may also specify that components in a list should be included or excluded on a specific site. To do so, add a comma-separated list of sites in parenthesis after the name of the component in the include list:
Additionally, all types of component lists may be set to fuzzy. The default include list is appropriate for most situations, but there are certain scenarios where you might want to be less strict. For example, the body of an article might be restricted to paragraphs and images 99% of the time, but you still want to allow your interactives team to create one-off components and add them through Kiln's UI.
You may make any component list fuzzy by adding that property in the config. This will add a View All Components button into the header of the Add Components modal, which will list all components available in your Clay installation.
In addition to component lists, you can use component properties if you want a single child component instead of an array of children.
This allows you to swap out different components in a specific place, for example if you have two different tagging components with different styles and functionality. As with component lists, you may include a _placeholder. If your component property is editable, the child component's selector will allow you to remove it (and the placeholder that displays will allow you to add it).
Component properties are not allowed in the layout or page data, only in normal components. Because of this, they are also not allowed in the <head> of the page.
