Atlas Blocks

The built-in Atlas blocks, in React and in Gutenberg.

Atlas ships with a variety of useful blocks. The advantages of these blocks over others in WordPress, is:

• They're designed to work well in React. Written in Typescript, they're even type-safe.
• They're tightly integrated into the Atlas theme system.
• They are WYSIWYG between how they work in Gutenberg and how they look in React.
• They're documented in Storybook.

A quick tour

A great way to learn how the blocks work is to just play with them in Gutenberg. All the properties have appropriate controls and help text.

Here they are:

Box

Encloses any other blocks, providing tools for padding, horizontal and vertical alignment or stretching, setting desired or maximum width and height, background color, and other general settings. By putting those things in a generic container-block, it's easy to compose it with other blocks, rather than having to repeat copious settings on every type of block. This is especially nice when used in layout blocks.

Column & Row

A single-column or single-row of blocks, with very similar controls. Optionally use a specification akin to that used in grid-column-template for fine-tuned control over how much space each cell occupies. Place any other blocks in the column or row. Nest Box components for more control over things like horizontal and vertical alignment within a cell.

Grid

A set of blocks that should be displayed in rows, where all rows have the same number of elements. It automatically selects the right number of columns based on viewport width, the number of elements, and other tuneable settings. Blocks are edited in a single column, mimicking the view on a smartphone.

Prose

General text area, including styling inside the text (e.g. bold, italic, hyperlinks, etc). Has special options for selecting typefaces, presets, and colors from the theme, ensuring consistent display no matter how the theme is tweaked, or the viewport width, or even in dark mode.

Image

Generic image, supporting uploads into or selecting from the WordPress gallery, specifying arbitrary URLs from the internet. Automatically computes things which are used by the theme for features like automated dark-mode support and lazy-loading with placeholders.

Using Atlas Blocks directly in React

Atlas blocks are just normal React components, so using them is trivial. Everything is in Typescript, so you're type-safe as well:

import { Box, Prose } from '@asmartbear/gutenberg-bridge/dist/registerAll';
...

return <>
    <AtlasContainer theme={theme}>
    <Box marginLeft={1} marginRight={1} innerMaxWidth="850px" backgroundColor="backdrop">
    <Prose preset="h1" content="Hello Atlas" />
    <Box alignH="center" backgroundColor="mirage" marginTop={1} marginBottom={1}>
        <Prose content="This is some centered text." />
    </Box>
    <AtlasGutenberg htmlRaw={raw} />
    <CopyBlockConfig />
    </Box>
    </AtlasContainer>
  </>;

Here the outer Box maintains margins horizontally, never allows the inner content to get very wide, and uses a theme palette color from the previous example.

Note the use of Prose with the preset for the h1 tag. This may seem useless, but watch what happens when you reduce the width of the browser: The font size scales down appropriately for smaller devices. Note that heading fonts scale down much faster than regular text, which again is appropriate for that form-factor. All this is tuneable in the theme.

Also note that the text in the inner Prose is white, even though we never told the system what color it should be. It automatically understood that because mirage is a dark color, the text has to be light-colored to be visible. But note that the mirage background color was set on a parent object -- the parent Box. This demonstrates another convenient feature of the Atlas theme and block system: Styles like colors and fonts aren't just inherited because of CSS cascade, but React is aware of it as well. That means a Prose component can know what background color it's rendered on, and select an appropriate text color in Javascript.

To see how powerful this system is, try switching to dark mode with new StandardThemeGenerator(false,true). Watch as the mirage color becomes pastel (because dark colors on black backgrounds vibrate or are unreadable), and also notice how the text becomes dark to contrast with that background. (More about dark mode here.)

This system is so smart, it even works with gradients! Try supplying linear-gradient(90deg,#3f1ba6,#7a1ba6) for the background color of the text, and then see what happens in light mode and dark mode.

Blocks in Gutenberg

All these blocks are configurable in Gutenberg.

Furthermore, all theme settings are represented as well. Here's a box with the theme palette colors that we used in our example from before. Typeface, presets, palette colors, spacing -- everything is transposed into Gutenberg so that everyone is synchronized to the same design.

And, if you update the theme, all the blocks in Gutenberg will still have the correct settings.

Now that we're familiar with Atlas blocks, let's create our first custom block by composing existing blocks into a layout.