The CoreMedia Frontend Workspace includes a script to easily create a new Hello-World brick. It comes with everything needed to work with templates, JavaScript files, style sheets and localizations. The script works on macOS, Windows, and Linux.

Quick Overview

pnpm install
pnpm run create-brick <name>
pnpm install
cd bricks/<name>

Installation

After running pnpm install the script is ready to be used like all provided scripts.

Usage

To create a new brick, run (replace <name> with a name according to the rules below):

pnpm create-brick <name>
pnpm install
cd bricks/<name>

Note

The brick name should be a simple ASCII name. Whitespace and special characters are stripped and the name will be lowercase.

This will create a directory with the name of the new brick inside the bricks folder of the Frontend Workspace. If the folder does not exist, it will automatically be created.

Note

Please note, that this script will not create new bricks in the lib/bricks folder, but in /bricks to ensure the lib folder stays untouched and ensure smooth upgrades of the frontend workspace.

The create-brick command will generate the initial brick structure as described in Section 4.3, “Bricks Structure” and creates the following files, which contain basic examples of a brick's core functionalities:

Configuration files

The Hello-World brick contains different configuration files. The most important one is the package.json. The Prettier scripts and devDependencies are already predefined in said config file, while the jQuery and js-logger dependencies are still commented out. Move these entries to dependencies to activate them. They will be used in this Brick's JavaScript.

There are also two JavaScript file entries in the package.json. These files are described further below. While index.js is the primary entry point, that can be used by other package (for example, your theme), the init.js will be called initially when the brick is loaded. Learn more about how the JavaScript entry point works in Section 4.3, “Bricks Structure”.

The Prettier files .prettierignore and .prettierrc are configuration files for Prettier code formatter. While .prettierrc contains rules on how to format the brick's code, .prettierignore excludes folders and files from formatting. Visit https://prettier.io/ to learn more about Prettier. If you don't want to use Prettier, simply delete these configuration files and remove the prettier scripts and devDependencies entries in the package.json.

JavaScript files

You can find 3 different JavaScript files in /src/js. As mentioned before, index.js serves as the primary entry point to this brick. You should use this file to export all JavaScript functionality you want to share with other packages. It currently only exports the functionality of <brickName>.js file, but could also export any other js file you create. The init.js file should be used to execute code as soon as the brick is loaded. Right now, nothing happens when the brick is loaded. To make the example function in <brickName>.js work, simply uncomment the code in this file and in init.js. And don't forget to activate the required dependencies jquery and @coremedia/js-logger in the package.json. Starting your theme with this brick enabled, should now display a "Brick <brickName> is used." output in your browser's console.

  "main": "src/js/index.js",
  "coremedia": {
    "type": "brick",
    "init": "src/js/init.js"
  }

Localization

The Hello-World brick comes with 2 localization files: src/l10n/<brickName>_de.properties and src/l10n/<brickName>_en.properties. There is already an entry in each of these files, which localizes a simple welcomeText key. This key is used in the example Page._body.ftl template. See Section 4.6, “Localization” to learn more about localization.

SCSS files

The Hello-World brick generates a src/sass/_partials.scss and src/sass/_variables.scss as entry points for the brick's SASS files. All other SCSS files should be imported in one of these files, depending on whether they contain CSS rules or variable declarations. You will find one example variable in src/sass/variables/_<brickName>.scss and a CSS rule, that makes use of this variable in src/sass/partials/_<brickName>.scss. See Section 4.4, “Sass Files” to learn more about how variables and partials are separated in the frontend workspace.

Templates

The Hello-World brick comes with just a single template: src/templates/com.coremedia.blueprint.common.contentbeans/Page._body.ftl. This template renders the localized "Hello World" string instead of everything else your theme comes with, except your theme contains an own Page._body.ftl file, which would override this one. After making sure, the new Brick works and is included correctly in your theme, you should remove this template to be able to render the real contents of your page. See Section 4.8, “Templates” to learn more about the usage of templates.

You´ll need to run pnpm install from the root of the frontend workspace to install the dependencies of the new brick before the brick can be used.

To use the created brick, you will have to install the brick in a theme as described in Section 5.3, “Using Bricks”.