In order to use a brick, you need to adjust your theme accordingly. This includes adjusting your theme's package.json, using a so called "smart-import" mechanism from your SCSS files and adding a resource bundle for all bricks to the theme.

Caution

To keep the bricks maintainable and easy to upgrade it is highly recommended to make no changes to the files and folders in the brick directory, except creating your own brick. Otherwise, upgrading via a patch file may no longer be possible.

Installing a brick

First of all, the brick needs to be added to your theme's dependency list. This can be done using the shell:

cd themes/<name>
pnpm add @coremedia/brick-media@^1.0.0

This will install the brick and all its dependencies (which might also be bricks) in your node_modules folder and add it to the "dependencies" list of your theme's package.json. The order in which bricks are installed does not matter.

Activating a brick

Most parts of a brick just like templates and initializing JavaScript code will automatically be included in the theme build after installing a brick. Because of technical reasons this automation needs to be added for SCSS and resource bundles when adding the first brick. For all further bricks no additional adjustments need to be made.

Caution

A brick always assumes that all of its parts are activated. Activating only parts (for example only JavaScript, not its styles) of a brick is not intended. CoreMedia strongly suggests considering this when using the brick so future updates to the Frontend Workspace or bricks will not break the theme.

Including SCSS code

Including the SCSS code of all brick dependencies is handled by using the "smart-import" mechanism. As explained in Section 4.4, “Sass Files” SCSS code is separated into variables and partials. The variables of all bricks need to be included before any partial. Adjustments to the variables of a brick need to be made even before that. A usage of the "smart-import" mechanism in the SCSS entry file of a theme (src/sass/$theme-name.scss) looks like this:

...
// Dependency variables
@import "?smart-import-variables";
...
@import "?smart-import-partials";
...

Including Resource Bundles

The resource bundles of all bricks are aggregated and merged into a "Bricks" resource bundle. CoreMedia Bricks include English and German by default. English is the master resource file language. In case you are including any bricks, you need to add it to the l10n.bundleNames entry of the Section 6.2, “Theme Config”. For more information about localization and resource bundles read Section 4.6, “Localization”.

<resourceBundles>
  <resourceBundle>l10n/Bricks_en.properties</resourceBundle>
</resourceBundles>

Note

Make sure that the theme's resource bundle is always the first entry so you can override any localization provided by the bricks with your own.

<resourceBundles>
  <resourceBundle>l10n/ThemeName_en.properties</resourceBundle>
  <resourceBundle>l10n/Bricks_en.properties</resourceBundle>
</resourceBundles>