Using Structures

So far we have introduced how to use components on a site, and how to update them live when the front matter of a page changes.

The next aspect to tackle is how to add and remove components to a page, which is where CloudCannon Structures come into the picture.

What are Structures?#

Structures are CloudCannon's answer to structured data on static sites. You can read more about structures in Create a structure and the Structures reference, but the main thing to know is that for Bookshop, Structures define the set of components that can be added to a specific key in CloudCannon.

The Bookshop component file#

Earlier, when we ran the @bookshop/init command, a sample component was created for us. Alongside the sample.eleventy.liquid templating file, a sample.bookshop.yml file was initialized.

_component-library/
└─ components/
   └─ sample/
      ├─ sample.eleventy.liquid
      └─ sample.bookshop.yml 

Similar to the live editing setup, this file isn't required when building your site. Instead, it's picked up by the @bookshop/generate command to configure your component in CloudCannon.

Here's a bare-bones file to illustrate the main keys:

spec: 
  structures:
    - content_blocks
  label: My Component

blueprint: 
  text: "Hello World!"

preview: 

_inputs: 

To get things started, we'll focus on the required spec and blueprint sections.

The component spec#

The component spec controls everything about how a component should be displayed in the CMS, and where it can be added to a page. Let's walk through a more fleshed out spec section:

spec:
  structures: 
    - content_blocks
  label: My Component 
  description: A very simple component 
  icon: nature_people 

The component blueprint#

The component blueprint is used to generate the CloudCannon Structure for your component. This object will be used as the initial data when the component is added to a page, and represents all of the editable data that your component takes.

If our sample component contained the following blueprint:

blueprint:
  text: "Hello World!"
  color: "#034AD8"
  image:
    image_url: "/image.png"
    image_alt: "My alternate text"

Then creating a new sample component in CloudCannon would present us with the following data editor:

Component blueprints contain some other powerful features for helping create your Structures. We'll see those soon in the Nesting components page of this guide.

Generating and using Structures#

The npx @bookshop/generate command that we set up when configuring live editing will automatically create Structures from your Bookshop components and make them available to CloudCannon. This process happens as part of your site build step on CloudCannon.

The Structures that your component is assigned to determines where it can be added in CloudCannon. For a sample component tagged as:

spec:
  structures:
    - content_blocks

With the page:

---
content_blocks:
---

CloudCannon will treat content_blocks as an array, and allow editors to add the sample component to it. Structures can also be accessed in CloudCannon using input configuration; if you want to use a different key, you can configure:

_inputs:
  page_components:
    type: array
    options:
      structures: _structures.content_blocks

{
  "_inputs": {
    "page_components": {
      "type": "array",
      "options": {
        "structures": "_structures.content_blocks"
      }
    }
  }
}

module.exports = {
  _inputs: {
    page_components: {
      type: "array",
      options: {
        structures: "_structures.content_blocks"
      }
    }
  }
};

Supported File Formats#

In the examples above, we have been writing the Bookshop configuration files using YAML. This is the recommended format, but you can also choose another if you prefer.

Bookshop supports reading component files written in yaml, toml, json, and js.