Skip to main content

Build sections

A section is a block you build once and place on many templates, such as a post's hero. Build one when the same arrangement of components belongs on more than one template.

The example is the blog's Post hero section. It holds Studio's Image and Header components and the blog's own Avatar and Byline, and it shows each post's cover image, title and author. The author's photo and name are two components, so whoever builds the section decides how they sit together. See From a design to components.

Prerequisites​

  • A Canvas URL on the project. Sections open on the canvas at this address. Set it in Settings, then Configuration. See Project settings.
  • A route that renders <StudioCanvas /> at that address. See Mount the section preview route.
  • The components you need, registered. For Post hero, that's Avatar and Byline. See Register a component.
  • A content type with at least one entry, such as Blog post with the entry "AI 101", so the section has content to show while you build it.

What this is and what you get​

A section is made of:

  • Components, arranged on the section's own canvas.
  • A schema, which is the shape of the content the section shows, such as the whole Blog post content type or one group field in it. It's optional. A section with a schema binds itself to matching content when someone drops it on a template.
  • Exposed props, which are the values each template can set for itself.
  • Section slots, which are places each template can fill with its own content. See Author a section with slots.

A section has no URL. It only reaches visitors through the templates that use it.

Faster ways to do this​

  • Studio CLI. csdx studio:section:create builds a section from one of your components and a content type, with its bindings in place. csdx studio:composition:build --scope section builds a section from a design. See CLI commands.
  • Skill. Ask your agent to build the section, and it uses build-section. See What are skills?

Create the section​

  1. In Compositions, open the Sections tab and click New Section.

    The Create Section dialog opens.

  2. Enter a Name, such as Post hero, and a Section UID, such as post_hero.

    The Create Section dialog with Post hero in Name and post_hero in Section UID.

  3. Click Create.

    The section opens on the canvas. The top bar shows Section and Post hero.

  4. Drag components from the Components tab onto the canvas. For Post hero, drag in Image, Header, Avatar and Byline.

    Post hero on its canvas with an Image, a Header, an Avatar and a Byline, and their four rows in the Layers tab.

Connect a schema​

Connect a schema so the section binds itself to the right content when someone drops it on a template.

  1. Click Connect A Schema in the bar above the canvas.

    The Select Content Type dialog opens.

    The Select Content Type dialog, with Blog post selected and the Proceed button.

  2. Pick Blog post and click Proceed.

    The Select Schema Root list opens. Its first row is the content type, Blog post, marked Entire Content Type. The content type's fields are listed under it.

    The Select Schema Root list for Blog post, with Entire Content Type at the top.

  3. Pick Blog post to use the whole content type, or pick one field, such as a group, a global field, a modular blocks field or a reference. Text, number, date and other single-value fields are greyed out.

    The top bar shows the schema's name, with Schema under it.

  4. Bind each component to a field of the schema. For Post hero, bind the Image to cover_image.url and the Header to title. Bind the Avatar Photo to the author's photo.url and the Byline Name to the author's title. See Bind a component.

When the root you pick holds many items and nothing is bound yet, Studio offers to add a Repeater first:

  • A multiple group, global field, file or link field. The Add Repeater dialog asks whether to repeat the section's content for each item. Click Add, or Skip if you only need one item for now.

    The Add Repeater dialog over the Post gallery section, with its Skip and Add buttons.

  • A modular blocks or reference field. Studio adds a Repeater and opens Add Condition, so you can choose which blocks or content types to show. See Render a list of mixed things.

    The Add Condition dialog after picking Related Posts as the Related posts section&#39;s schema root, with Blog post ticked.

To remove a schema, open the schema list in the top bar and click the delete icon on its row, then click Remove in the Remove Schema dialog. Your components stay on the canvas. To switch to a different schema, add the new one first, then remove the old one.

The Remove Schema dialog for Post hero&#39;s Blog post schema, over the schema list in the top bar.

Use it on more than one content type​

A section binds itself only on templates whose content type matches one of its schemas. To use Post hero on an Author template too, add a second schema:

  1. Click the Add Schema icon in the top bar.
  2. Pick the content type and its root, the same way as the first schema.

Every schema on a section must be the same kind as the first one. If the first is a whole content type, every other schema must be a whole content type too. If the first is a field, the others must be the same kind of field, such as a multiple group. A single field and a multiple field count as different kinds.

The Author card section is linked to the author_card global field on Blog post and on Topic page. Dropped on the Blog post template or the Topic page template, it binds itself to that template's author_card field.

Switch between the schemas from the schema list in the top bar.

Post hero&#39;s schema list open in the top bar, showing its two schemas, Blog post and Author.

Let templates change a value​

Expose a prop when each template should set its own value for it, such as the size of the post title.

  1. Click Save.

    The Expose Props dialog opens. It lists every component in the section, with its props.

    The Expose Props dialog for Post hero, with the Header&#39;s Heading Level turned on and named Title size.

  2. Turn on Expose for each prop templates may change. Exposed As starts with the prop's own name. Change it to a name template builders recognize. For Post hero, expose the Header's Heading Level as Title size.

  3. Click Save.

    Studio saves the section and shows Section Saved Successfully. If you click Cancel, the section isn't saved.

The dialog opens every time you click Save on a section. To expose props for one component only, select it and use the icon on the Properties header in the Settings tab.

Save and deploy it​

Save stores the section. Deploy puts it on your site. A template doesn't copy the sections it uses. It points at them, so deploying Post hero to an environment updates every template that uses it there. See Save, preview, deploy.

The Blog post template points at the Post hero, Post body and Related posts sections instead of copying them.

What happens when you drop it on a template​

Studio binds the section to the template's content when one of the section's schemas is on the template's content type. Drop Post hero on the Blog post template and its Image, Header, Avatar and Byline show AI 101's cover image, title and author straight away. Studio uses the field you connected.

On the placed section, the Section Data row shows what it's bound to. It also offers other fields of the same shape, which you can switch to:

Schema rootOther fields that fit
Group or global fieldThe same number of fields, of the same types. The names can differ.
Modular blocksShare at least one block
ReferencePoint to at least one of the same content types

A single field only fits a single field, and a multiple field only a multiple field.

Post hero selected on the Blog post template, with its Section Data dropdown open on AI 101 and Entire Entry.

Studio doesn't bind a section on its own on a freeform template, or on a template whose content type has none of the section's schemas. Pick its data from Section Data instead.

If it doesn't work​

  • The canvas says "Canvas URL is not configured". The project has no Canvas URL. Click Configure Canvas URL and set one.

    The &quot;Canvas URL is not configured&quot; card on the section canvas, with the Configure Canvas URL button.

  • The canvas says "No Section Canvas on This Route". Nothing at the Canvas URL loads the Studio editor. Your app needs a route there that renders <StudioCanvas />. See Mount the section preview route.

    The &quot;No Section Canvas on This Route&quot; card on the section canvas.

  • The canvas says "A Page Loaded, Not the Canvas". The Canvas URL points at one of your site's real pages. Change the Canvas URL in Settings to a route of its own that renders <StudioCanvas />.

    The &quot;A Page Loaded, Not the Canvas&quot; card on the Post hero section canvas, with /about as the Canvas URL.

  • The section drops onto a template but doesn't show the entry's content. None of its schemas is on the template's content type, or the template is freeform. Add a schema for that content type, or pick the data from Section Data.

  • It shows the wrong field. The field you connected wasn't available where you dropped the section, such as inside a Repeater, so Studio used the first field that fits. Pick the right one from the placed section's Section Data row.

  • A field is greyed out in Select Schema Root. It holds a single value, or it's a different kind from the section's first schema. Pick the group, global field or block that contains it.

  • Save is greyed out in Expose Props. A name under Exposed As is empty ("Display name cannot be empty") or used twice ("This display name is already used"). Give every exposed prop its own name.

    Expose Props for Post hero with Heading Level&#39;s name cleared, the message &quot;Display name cannot be empty&quot;, and Save greyed out.

  • The section didn't save. You clicked Cancel in Expose Props. Save again and click Save in the dialog.

  • "This name is already in use" or "This UID is already in use". Names and UIDs must be unique across templates and sections. Pick another.

    Create Section with Post hero and post_hero typed again, showing both the name and UID in-use messages.

Report a problem with this page