Slabs: Assembling partials with Gutenberg

Mocking up and filling sections within a React page, using sections within Gutenberg.

A blog post page is often just a big chunk of Gutenberg content, surrounded by standard components like a header and footer. But unless you're building a media site, most pages aren't like that.

Most pages are designed by designers, and built by React developers, using components from their own design system, with different layouts for smaller devices, maybe even some fancy effects and imported 3rd-party libraries. How does all that mesh with Gutenberg?

Often there are pieces of those pages, for which it makes sense for the marketers to write the content in Gutenberg, but not the entire page. Examples might be the subtitle at the top of the page, the content of the "three key features" highlighted on the home page, the content of "four impressive statistics" in the middle of the page, a case study with a description, link, and image, or maybe some call-to-action buttons and text.

Atlas has a unique system to support this use-case, called "Slabs." A "slab" is one of those pieces of the page which ought to be controlled by Gutenberg.

Replacing content with Slabs

Create a simple web page, with a few zones that we want editable by Gutenberg. Here's some generic React code, that doesn't do anything fancy, but shows the general idea.

import React from 'react';
import { AtlasContainer, AtlasGutenberg, StandardThemeGenerator } from '@asmartbear/gutenberg-bridge';
import { Box, Row, Prose } from '@asmartbear/gutenberg-bridge/dist/registerAll';

const Page: React.FC = () => {

    // A basic theme
    const themeGen = new StandardThemeGenerator(true);
    themeGen.baseFontScale *= 1.3;
    const theme = themeGen.getTheme();
  
    return <AtlasContainer theme={theme}>
      <Box marginLeft={1} marginRight={1}>
        <Prose preset="h2" content='Atlas Slab Example' />
        <AtlasGutenberg htmlRaw={`<p>Load me from WordPress!</p>`} />
  
        <Row itemWidthSpec='7fr 3fr' gutter={2}>
  
          <div>
            <Prose preset="h3" content='About us' />
            <Prose preset="p" content='This is everything you need to know about us:' />
            <div style={{ fontStyle: "italic" }}>
              (content from Gutenberg should go here)
            </div>
  
            <Prose preset="h4" content='And now for something completely different...' />
            <div style={{ fontStyle: "italic" }}>
              (content from Gutenberg should go here)
            </div>
          </div>
  
          <Box backgroundColor="primary" marginLeft={1} marginTop={1} marginRight={1} marginBottom={1}>
            <Prose preset="h3" content='As an aside...' />
            <div style={{ fontStyle: "italic" }}>
              (content from Gutenberg should go here)
            </div>
          </Box>
  
        </Row>
      </Box>
    </AtlasContainer>;
  }

export default Page

This creates a basic layout, with two columns of width 70% / 30%, and three areas that we want to replace with Gutenberg content:

Now we'll replace one of the placeholders with a Slab. The steps are:

1. Install the Atlas Slab npm module into your project:

npm install @asmartbear/gutenberg-bridge-slab

2. Add the Atlas Slab blocks to your WordPress theme configuration in package.json:

"block-dirs": [
    "node_modules/@asmartbear/gutenberg-bridge/dist",
    "node_modules/@asmartbear/gutenberg-bridge-slab/dist",
    "blocks"
  ]

3. Import the Atlas Slab React components into your page:

import { AtlasSlabProvider, AtlasSlab } from '@asmartbear/gutenberg-bridge-slab';

4. Just as you're already wrapping all your Atlas components inside AtlasContainer, you must now do the same with AtlasSlabProvider. Just enclose everything in <AtlasSlabProvider> ... </AtlasSlabProvider>. No properties.

5. Replace one of the divs that currently contains "content from Gutenberg should go here" with the Atlas Slab component. Also give the slab a simple label; we'll use that to tie slabs from Gutenberg to slabs in React:

...
<Prose preset="h3" content='About us' />
<Prose preset="p" content='This is everything you need to know about us:' />
<AtlasSlab label="about-us" />
...

6. Refresh your WordPress theme. Don't forget to first grab a new copy of atlas-block-config.json, since we added new blocks.

In React, this creates a visual placeholder that displays the label name (which the WordPress user will need in Gutenberg):

Now we'll fill in the content from WordPress. In Gutenberg, use the new "Slab" block, and put some content inside it:

The "Slab" block can contain any other blocks. The label can be set from the sidebar or by directly typing in the yellow area.

After saving the content, refresh the original page to see the content has been loaded into the right place:

You simply repeat this for all Slab areas, using labels to distinguish them.

Mock-ups: Better placeholder content

Before website content is written in WordPress -- indeed, possibly before the front-end is even connected to WordPress -- designers and front-end developers are already creating designs and writing code. While the big yellow boxes certainly make a strong statement, they are not a good way to get a feel for how the site will look when real content is loaded in.

What you probably want, is to indicate where the slabs are, but to supply your own placeholder content instead of the yellow boxes.

This is trivial to do! Just put the mock-up content inside the <AtlasSlab> tag. That content will be used when there's nothing from Gutenberg, and will be ignored when there is something from Gutenberg.

...
<Prose preset="h3" content='As an aside...' />
<AtlasSlab label="aside">
    <Prose preset="p" content='This is some example sidebar content.' />
    <Prose preset="p" content='There can be multiple paragraphs, and in general, there will be.' />
</AtlasSlab>
...

To make it clear where the slabs are, red push-pins mark the top-left corner of slabs:

When your mouse hovers over a slab, the yellow box appears. This makes it easy for the Gutenberg author to see what the slabs are:

Now, designers and coders can mock up websites, and seemlessly accept content from marketers.

Gutenberg content outside of Slabs

What happens to blocks which are outside of any Slab?

The answer is: The <AtlasGutenberg/> component emits that content, just like it always does. This can be useful if there is "main content" which can be emitted in a particular place, with extra (optional?) Slab areas as well.

Next, let's dive into the Atlas Theme system in more detail.