Skip to content

Component Lists

Jump to bottom
Nelson Pecora edited this page Jun 26, 2017 · 3 revisions

Component Lists are a special type of field. These fields don't have behaviors or labels, and don't appear in forms, but rather contain lists of component references and the logic for adding and removing components.

content:
  _componentList:
    include:
      - paragraph
      - blockquote
      - image

This will allow you to specify what components should be included in each list. In your template, use the component-list partial supplied by nymag-handlebars to display the child components. Add the data-editable attribute if you want the component list to be editable.

<div data-editable="content">{{> component-list content }}</div>

Components in editable lists will get buttons in their selectors to remove them (trash can) and add new components after them (plus button).

They'll also get drag drop functionality to reorder them.

Component lists allow a _placeholder property, which will display if the list is empty.

content:
  _placeholder:
    text: Article Content
    height: 600

Component Properties

Components may include a single child component in a property, rather than in a list. Like lists, component properties don't have behaviors or labels, and don't appear in forms, but rather contain component references and the logic for adding and removing components.

sideShare:
  _component:
    include:
      - share
      - share-mini

Component properties currently do not have a lot of functionality, but in the future they will support the same things as component lists.

Site-specific Components

You may optionally specify that components in a list or property 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:

content:
  _componentList:
    include:
      - article (site1, site2) # allow on site1 and site2 ONLY
      - paragraph # allow on all sites
      - image (not:site1) # allow on all sites EXCEPT site1
      - link (site1, site2, site3, not:site2, not:site3) # only allow on site1
      # if (for some reason) you both include and exclude a site, it'll filter by the
      # included sites first, then filter out the excluded.

Fuzzy Component Lists

By default, component lists and properties allow strict whitelisting and blacklisting with include and exclude. This 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 paragraphs and images 99% of the time, but you still want to allow your interactives team to create one-off components and add them to articles.

You can accomplish this by adding fuzzy: true to your component list / property. This will add a "View all components" button to the bottom of the component list in the Add Components pane. When a user clicks the button, it'll open a different add-components pane with a list of all available components.

articleBody:
  _componentList:
    include:
      - paragraph
      - mediaplay-image
    fuzzy: true # to allow one-off infographics, etc

Page Areas

As this overview explains, pages in Clay reference both a layout and page-specific components. In layout schemas, you can specify that a certain list or property lives in the page data by adding page: true.

pageHeader:
  _component:
    include:
      - header-small
      - header-large
    page: true

sidebar:
  _componentList:
    include:
      - ad
      - masthead
      - tag-cloud
    page: true

Head Component Lists

Components that live in the <head> of a page are somewhat special, as <meta> tags are different than other tags. They cannot contain other components, and some <meta> tags get messed up if you add arbitrary attributes (like our data-uri which denotes components). To get around this, we use html comments to denote both components and the lists they live inside.

<!-- data-editable="listPath" -->
<!-- data-uri="domain.com/components/foo/instances/bar" -->
<meta name="some-tag" content="some-content">
<meta name="some-other-tag" content="some-other-content">
<!-- data-editable-end -->

As you can see above, component lists are simply denoted with <!-- data-editable -->, the same way we use the data-editable attribute in elements. In head component lists, you must also add a <!-- data-editable-end --> comment after the last component in the list. This allows us to add, remove, reorder, and re-render components inside the list.

Components themselves are denoted with <!-- data-uri -->, similarly to the data-uri attribute in body components. Components do not need a comment after them, but they need to live in a component list if you want to edit them.

Head component lists get added as tabs to the Find on Page pane in Kiln automatically, allowing them to be edited.

Invisible Component Lists

It's useful to have a component list for various components that might not have reader-facing visual elements, such as tracking scripts, affiliate marketing scripts, pixels, modals, etc. If these components have actual elements (i.e. they're not just <meta> tags in the <head>), you can add a property to the component list to make them appear as tabs in the Find on Page pane, similar to Head Component Lists.

footerMetadata:
  _componentList:
    include:
      - pixel-tracker
      - gpt-script
    invisible: true

Clone this wiki locally