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
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
Display
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.
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
The blocks plugin supports the following configuration properties that can be set using the plugins object.