First Steps

This section describes the first steps to create a design for BSI CX from scratch using this package. If you don't want to start from scratch we recommend the master template web or the master template email. If you like so start from scratch instead, checkout our scaffold design.

Folder Structure

The following folder structure is recommended:

./
│   .gitignore
│   package-lock.json
│   package.json
│   webpack.config.js
│
├───.git
│       ...
│
├───dist
├───node_modules
│       ...
│
└───templates
    └───landingpage
        │   design.js
        │   design.twig
        │   preview.png
        │   preview.twig
        │   properties.js
        │   styles.less
        │
        ├───assets
        │       file.pdf
        │
        ├───content-elements
        │   └───content
        │       ├───title
        │       │       index.js
        │       │       styles.less
        │       │       template.twig
        │       └───text
        │               index.js
        │               styles.less
        │               template.twig
        │
        ├───modules
        │       main.js
        │
        └───static
                header.jpg

Files and Folders in the Project Root

The following files are placed in the project's root folder.

package.json

The package.json file of your project.

webpack.config.js

The Webpack configuration file. This file is mandatory.

.git

The GIT folder. Make sure your project is under version control.

dist

This folder will contain the build artifacts. It is recommended to exclude this folder from git. You don't have to create this folder, Webpack will do it for you.

node_modules

Your project's NPM dependencies will be placed in this folder.

templates

The source code for your design templates should be placed in this folder. In this example, there is only a design for a landingpage.

Files and Folders in the Template Root

A sub folder in the templates folder is called template root.

design.js

This file is mandatory and contains a CommonJS module, exporting the structure of your design. This will result in the design.json file (or design.properties, if you use the legacy format).

design.twig

This file is mandatory and contains the HTML frame of the template and will result in the design.html file in the dist folder.

preview.png

This file is optional and contains a preview image for your template, used in BSI CX. You have to require the preview image in your design.js.

preview.twig

This file is mandatory and is used to generate the preview of your design and will result in the preview.html file in the dist folder.

properties.js

This file is optional and contains a CommonJs module, exporting the properties object.

styles.less

This file is optional and contains your common CSS styles. You have to require this file in your design.js.

assets

This folder is optional and contains additional files to copy to your resulting ZIP file.

content-elements

This folder contains your content elements, organized in content element group folders. A folder containing a content element is called content element root.

modules

This folder contains your Java Script modules and is called modules root.

static

This folder contains your static assets (e.g. images, plain CSS or simple Java Script files).

Files in the Content Element Root

It is recommended to organize your content elements in folders. One folder per content element.

index.js

This file contains the definition of your content element as a CommonJs module.

styles.less

This file can contain the CSS styles for your content element. You have to require this file in your content element's index.js.

template.twig

This file contains the template of your content element. You have to require this file in your content element's index.js.

Configuration

Since this package uses Webpack under the hood, we have to create a webpack.config.js file. It is recommended to place this file at the root of your project folder. In order to use the @bsi-cx/design-build package, you must create the Webpack configuration using BuildConfig objects and the WebpackConfigBuilder. The template from the folder structure in the previous section would result in the following webpack.config.js:

const path = require('path');

const {BuildConfig, ModuleConfig, WebpackConfigBuilder} = require('@bsi-cx/design-build');

module.exports = WebpackConfigBuilder.fromConfigs(
  new BuildConfig()
    .withName('landingpage')
    .withVersion('1.0.0')
    .withRootPath(path.resolve(__dirname, 'templates', 'landingpage'))
    .withPropertiesFilePath('properties.js')
    .withModules(
      new ModuleConfig()
        .withName('main')
        .withPath('main.js')));

The webpack.config.js file must export a CommonJs module. You can't use ECMA script module imports and exports.

Design Specification

One of the most important files in a design build is the design.js file in the template root. It contains all necessary information about a design. For example what content elements, styles and HTML configurations are available.

Design

Here is one possible example for the content of a design.js file:

require('./styles.less');

const {cx, Locale} = require('@bsi-cx/design-build');

module.exports = cx.design
  .withTitle('Landingpage')
  .withAuthor('John Doe')
  .withDate('18.08.2021')
  .withPreviewImage(require('./preview.png'))
  .withDefaultLocale(Locale.EN)
  .withLocales(
    Locale.EN,
    Locale.DE,
    Locale.DE_DE,
    Locale.DE_CH)
  .withContentElementGroups(
    cx.contentElementGroup
      .withGroupId('content')
      .withLabel('Content')
      .withContentElements(
        require('./content-elements/content/title'),
        require('./content-elements/content/text')));

Since this is a JavaScript file you are free to use (most) features of modern JavaScript programming. More information about any limitations in the usage of JavaScript features inside the design.js file can be found here.

Be aware due to technical limitations the design.js file and all JavaScript files it requires must be CommonJS modules.

We strongly encourage you to use the builder classes to specify your design. However, it is also possible to export a JavaScript Object of the required format directly. The following example should illustrate such a file:

module.exports = {
  schemaVersion: '22.0',
  title: 'Landingpage',
  author: 'John Doe',
  date: '18.08.2021',
  previewImage: require('./preview.png'),
  defaultLocale: 'en',
  locales: [
    'en',
    'de',
    'de-DE'
  ],
  contentElementGroups: [
    {
      groupId: 'content',
      label: 'Content',
      contentElements: [
        {
          elementId: 'content-title',
          file: require('./content-elements/content/title/template.twig'),
          icon: 'heading',
          label: 'Title',
          parts: [
            {
              partId: 'plain-text',
              label: 'Title'
            }
          ]
        },
        {
          elementId: 'text',
          file: require('./content-elements/content/text/template.twig'),
          icon: 'text',
          label: 'Text',
          parts: [
            {
              partId: 'formatted-text',
              htmlEditorConfig: 'extended',
              label: 'Text'
            }
          ]
        }
      ]
    }
  ]
};

Content Elements

Content elements can also be specified using builder classes. Take a look at the following example:

require('./styles.less');

const {cx, Icon} = require('@bsi-cx/design-build');

/**
 * @type {ContentElement}
 */
module.exports = cx.ontentElement
  .withElementId('content-title')
  .withIcon(Icon.HEADING)
  .withLabel('Title')
  .withFile(require('./template.hbs.twig'))
  .withParts(
    cx.part.plainText
      .withLabel('Title'));

Templates

You can write your templates using Twig or plain HTML. In the case of Twig templates, the resulting file will be plain HTML. Depending on your target CX version you may want to use Handlebars in your templates. Take a look at the following table for the supported template formats in BSI CX:

Version	HTML	Handlebars
Studio 1.0	Landingpage, E-Mail	-
Studio 1.1	Landingpage, E-Mail	-
Studio 1.2	Landingpage, E-Mail	-
BSI CX 1.3	Landingpage, E-Mail, Website	Website
BSI CX 22.0	Landingpage, E-Mail, Website	Landingpage, E-Mail, Website

To give the design build a hint in what format a template should result you can use the following file extensions:

Source File Extension	Target File Extension	Parser
.html	.html	-
.twig	.html	Twig
.hbs	.hbs	-
.hbs.twig	.hbs	Twig

Keep in mind when targeting .hbs files from .hbs.twig files, that you have to escape Handlebars expressions:

<div data-bsi-element="content-text" class="element content-text">
  <p data-bsi-element-part="plain-text">
    {% verbatim %}{{bsi.nls 'text_'}}{% endverbatim %}
  </p>
</div>

The example above would result in the following .hbs file:

<div data-bsi-element="content-text" class="element content-text">
  <p data-bsi-element-part="plain-text">
    {{bsi.nls 'text_'}}
  </p>
</div>

Run the Build

To run the build open a new terminal session and navigate to the project root folder where your webpack.config.js file is located. Now execute the following command:

npx webpack --config webpack.config.js --mode development --progress

This will create a development bundle. To create a production bundle use the following command:

npx webpack --config webpack.config.js --mode production --progress

It is recommended to create some NPM scripts for the build commands.

Start the Watcher

It is possible to start a file watcher, which rebuilds your design whenever one of the source files changes. To do so, run the following command:

npx webpack --config webpack.config.js --mode development --watch --progress

Start the Development Server

For better testing experience, a development web server is available. In order to start the server, run the following command in your terminal:

npx webpack serve --config webpack.config.js --mode development --progress

By default, the development server is reachable on http://localhost:8080/. The port may differ, since the development web server uses the auto setting.