Making a Page Builder with CloudCannon

|
|
Headshot of Jordan smiling on a white background.
Jordan Trbuhovic
07 October 2021 | 5 mins

Page builders give editors an intuitive and easy way to manage and build websites. All editing can be done within CloudCannon’s Visual Editor in real time.

Live editing on CloudCannon is enabled with the use of Bookshop. Bookshop is a component development workflow for static websites which currently supports Jekyll and Eleventy, and will support a wider variety of static site generators in the near future.

Bookshop helps you to create a component-based file structure, which works out of the box with CloudCannon’s array structures. (See our documentation on array structures for more information.) This setup allows CloudCannon to immediately re-render any changes to page components and edits within the Visual Editor.

Getting started

Download or fork our example repositories ( Jekyll, 11ty ) from GitHub. If you’ve downloaded the example website you will need to unzip it. With your terminal, change directory into the website. e.g. cd ~/desktop/page-builder-example-jekyll/

To run the website locally run the following commands:

  • Install (11ty): npm i
  • Install (Jekyll): npm i && bundle install
  • Run the stack: npm start

Your website can now be opened in a web browser by visiting the URL listed in your terminal. Once the website is built and uploaded to CloudCannon you will be able to use the live editing features.

Directory structure

After unzipping or cloning the example website you will see the following directories:

  • .cloudcannon
    (This is a hidden directory so it will only be visible if you open the website with your text editor)
  • component-library
    • bookshop
    • components
    • shared
  • site

These are all necessary for Bookshop, and enable live editing with CloudCannon.

.cloudcannon contains a pre-build script that tells CloudCannon to install any dependencies, and run the Bookshop script. Without this, live editing on CloudCannon won’t be possible.

component-library has three directories which contain the website components, shared styles, Bookshop config, etc. The components directory is where all of your components should be built. Each component has its own folder which holds everything relating to it:

  • component.<framework>
    The component template
  • component.bookshop.toml
    The configuration/front-matter settings for the component on CloudCannon
  • component.scss
    The styles for the component

This gives you an easy to manage component library with self-contained components. Bookshop automatically compiles the styles on build, and turns all components into array structures for CloudCannon. You don’t need to worry about adding, including, or importing these files anywhere.

site contains all of the Jekyll or Eleventy files for your website. You can build your website as you would with any other site within this directory. Your site is separated from Bookshop for better organization.

Creating new components

Page components give editors a collection of different content types/layouts that can be used to build pages. Bookshop only enables live editing for components, so if you have other hard-coded content structures these will not live update when modified via front matter.

When creating new components they should be added to a folder with the name of the component, inside the component-library > components folder. This component folder must contain the three files mentioned in the Directory structure section (component template file, component TOML file, component styles).

An example of a new component would look like this:

- component-library
   - components
      - my-new-component
         - my-new-component.bookshop.toml
         - my-new-component.jekyll.html
         - my-new-component.scss

To help with this process you can run the Bookshop gen command, which will create a skeleton for any new component:

npx @bookshop/gen --name my-new-component

Using components

To give editors access to components, you need to add the content_blocks key to the front matter of any page you want components to be accessible on.

Example:

index.html
---
title: Welcome to our website
content_blocks:
---

Once the website has been built on CloudCannon, content_blocks will be shown as a button within the Visual Editor that lets you choose which components to add to the page. content_blocks links to the structure listed in the TOML file of each component, which auto-populates the component picker.

Components that get added to the content_blocks array are rendered onto pages with the following code, which is located in the default page layout.

<body>
    <main>
        <!--  The `page` include loops through all content_blocks and renders them.
        Using a bookshop tag here means that live previewing will catch new components. -->
        {% bookshop_include "page" content_blocks: content_blocks %}
    </main>

    <!-- This tag registers live previewing on CloudCannon. -->
    {% bookshop_live _cloudcannon/bookshop-live.js %}
</body>

page.<framework> (referenced in the codeblock above)

{% for block in content_blocks %}
    <div class="cms-editor-link"
        data-cms-editor-link="cloudcannon:#content_blocks[{{ forloop.index0 }}]">
        <span class="cms-editor-button"></span>

        {% bookshop {{block._bookshop_name}} bind: block %}
    </div>
{% endfor %}

You can modify the default page layout in the example website if you want to change the way components are rendered.

Uploading/syncing to CloudCannon

To get your new Bookshop site on CloudCannon you need to log in to your account and create a new site. You can choose to sync a repository, upload a folder, or upload the zip downloaded from this post.

If you’re uploading a folder, make sure the .cloudcannon folder is checked when selecting files to upload. If this is unchecked you will get build errors and won’t be able to use the live editing features.

Summary

After learning the basics of how Bookshop can be integrated into a website, you should now have live editing for components in CloudCannon’s Visual Editor. The structure in the example website is a good base for starting, or converting any static website to a Bookshop component-based website. To dive deeper into Bookshop and how it works, check out the Bookshop Guides.

You can also use Bookshop in a theme to save duplicating components and styles across websites that use the same themes or layouts. We do this for our Bookshop templates, which are free for anyone to use and modify.

For further reading on themes, see our other posts on creating themes with GitHub, or with Gemfury.

You might also be interested in

blue lightning bolt illuminated in the night sky

Bundling JavaScript for Jekyll

Ryan Collins

12 November 2020 | 7 mins

Read more
Google sign displayed on top of an office building

G Suite Authenticated Sites with CloudCannon and SAML

George Phillips

4 February 2020 | 2 mins

Read more
Tray of rings with gems in them.

Private Jekyll themes with Gemfury

Jordan Trbuhovic

13 June 2019 | 4 mins

Read more
Don’t miss the latest
A monthly newsletter to keep you up-to-date with the latest CloudCannon news
Illustration of woman holding an envilope