Blocks Plugin

The Sidekick library comes with a blocks plugin.

Blocks Plugin Setup

To generate content for the blocks plugin, you need to prepare a separate Word document for each block you want to include.

1. Create a directory inside the /tools/sidekick directory where you will store all the block variations. For example, you could create a directory called blocks inside /tools/sidekick.
2. For this example, let’s assume we want to define all the variations of a block called columns. First create a Word document called columns inside the blocks directory and provide examples of all the variations of the columns block. After each variation of the block add in a section delimiter.
3. Preview and publish the columns document.
4. Open the library workbook created in the last section, inside the helix-blocks sheet, create two columns named name and path.
6. Next we need to add a row for our columns block. Add the name of the block in the first column and the url to the document that defines the block variations in the second column. For instance, if you want to add the columns block, you could create a row with the name Columns and the path /tools/sidekick/blocks/columns. In order for the library to work across environments (page, live, prod) you should not use an absolute url for the path column.
7. Preview and publish the library workbook.

> Since the example blocks are being published you should use bulk metadata to exclude the content inside of /tools/** from being indexed.

Screenshot 2024-04-09 at 2 54 19 PM

Example library.xlsx

Library Metadata

The blocks plugins supports a special type of block called library metadata which provides a way for developers to tell the blocks plugin some information about the block or how it should be rendered.

Supported library metadata options

Key NameValueDescriptionRequired
nameName of the blockAllows you to set a custom name for the blockfalse
descriptionA description of the blockAllows you to set a custom description for a blockfalse
typeThe type of the blockThis tells the blocks plugin how to group the content that makes up your block. Possible options are template or section (details below)false
include next sectionsHow many sections to include in the block itemUse if your block requires content from subsequence sections in order to render. Should be a number value that indicates how much subsequent sections to include.false
searchtagsA comma seperated list of search termsAllows you to define other terms that could be used when searching for this block in the blocks pluginfalse
tableHeaderBackgroundColorA hex color (ex #ff3300)Overrides the table header background color for any blocks in the section or page.false
tableHeaderForegroundColorA hex color (ex #ffffff)Overrides the table header foreground color for any blocks in the section or page.false
contentEditableA boolean value (default: true)Set to false to disable content editing in the preview window.false
disableCopyA boolean value (default: false)Set to true to disable the copy button in the preview window.false
hideDetailsViewA boolean value (default: false)Hide the block details panel inside the preview window.false

Default Library metadata vs Library metadata

There are two types of library metadata. Library metadata that lives within a section containing the block, or default library metadata that applies to the document as a whole and lives in a section on it’s own (a block called library metadata as the only child in a section).

Let’s take an example of a hero block that has 5 variants. Suppose you want to add the same description for each variation of the block, rather than duplicating the library metadata with the description into each section containing the variations. You could instead use default library metadata to apply the same description to every variation of the block. If you decide that one variation actually needs a slightly different description you could add library metadata to the section containing the variation and it would override the default library metadata description when it’s rendered within the blocks plugin.

Authoring block names and descriptions using Library Metadata

By default the block name (with variation) will be used to render the item in the blocks plugin. For example, if the name of the block is columns (center, background) then that name will be used as the label when it’s rendered in the blocks plugin. This can be customized by creating a library metadata section within the same section as the block. Library metadata can also be used to author a description of the block as well as adding searchTags to include an alias for the block when using the search feature.

Example block with custom name and description

Content

Screenshot 2023-06-08 at 1 11 09 PM

Display

Screenshot 2023-06-08 at 1 13 32 PM

Autoblocks and Default Content

The blocks plugin is capable of rendering default content and autoblocks. In order to achieve this, it is necessary to place your default content or autoblock within a dedicated section, which should include a library metadata table defining a name property, as previously described. If no name is specified in the library metadata, the item will be labeled as “Unnamed Item.”

Blocks composed of content in subsequent sections

There are situations where developers may want a block to consist of content from subsequent sections. This pattern is discouraged for reasons stated here, but if you choose to use it the blocks plugin can render these items using the include next sections property in library metadata.

Templates

Templates are a way to group an entire document into a single element in the sidekick library. To mark a document as a template set type to template in default library metadata.

> Important, the library metadata needs to be in it’s own section and be the only child to be considered default library metadata.

Supporting metadata is also desirable for templates. To add a metadata table to the template you can use a Page metadata block.

266064147-12883ee0-147b-4171-b89a-c313e33eef24

When the template is copied a metadata with the values will be added along with the content to the clipboard.

Sidekick plugin setup

Since the sidekick library is hosted on the same origin as the content, a static HTML page needs to be created to load and configure the content.

1. Create a file called library.html in tools/sidekick/;

2. Paste the following code in library.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
    />
    <meta name="Description" content="AEM Sidekick Library" />
    <meta name="robots" content="noindex" />
    <base href="/" />

    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        font-family: sans-serif;
        background-color: #ededed;
        height: 100%;
      }

      helix-sidekick { display: none }
    </style>
    <title>Sidekick Library</title>
  </head>

  <body>
    <script
      type="module"
      src="https://www.aem.live/tools/sidekick/library/index.js"
    ></script>
    <script>
      const library = document.createElement('sidekick-library')
      library.config = {
        base: '/tools/sidekick/library.json',
      }

      document.body.prepend(library)
    </script>
  </body>
</html>

In the code above we load the sidekick library from aem.live and then create a custom sidekick-library element and add it to the page. The sidekick-library element accepts a config object that is required to configure the sidekick library.

Supported configuration parameters

Parameter NameValueDescriptionRequired
basePath to the libraryThe base library to be loadedtrue
extendsAbsolute URL to the extended libraryA library to extend the base library withfalse
pluginsAn object containing plugins to register with the sidekick library.The plugins object can be used to register plugins and configure data that should be passed to the pluginfalse

The blocks plugin supports the following configuration properties that can be set using the plugins object.

Blocks plugin configuration parameters

Parameter NameValueDescriptionRequired
encodeImagesA boolean value that indicates if images should be encoded during copy operationsIf your site has a Zero trust network access (ZTNA) service enabled such as Cloudflare Access then images should be encoded for copy/paste operations to work correctly with images.true
viewPortsFull or simplified configuration object, see examples below.Configuration to overwrite the default viewport sizes. The default is 480px fo mobile, 768px for tablet and 100% of the current window for desktop.false
contentEditableA boolean value to disable content editing globally in previews.Set to false to disable content editing.false