Introduction

Create experiences that delight customers. For marketing, sales, and service: Find, win, retain, and understand customers with BSI CX. Design, execute and optimize perfect customer journeys. Everything is cross-departmental, individualized for every customer, in real time, across all touchpoints, and fully automated – for extraordinary and emotional experiences.

Learn more about all features of BSI CX by visiting our product website.

You wan’t to build a BSI CX Design? Learn how to use BSI designs by taking part in the e-learning for designs!
CX, Customer Experience and Studio. The BSI Customer Suite consists of multiple Products, BSI CX is one of it. Formerly called BSI Studio, CX is an abbreviation of BSI Customer Experience.

Getting started

Learn how to use BSI designs by taking part in the e-learning for designs.

The interactive e-learning helps you to reach your goal faster. We have developed this e-learning from years of experience with various customers, with the aim of learning how to work with designs quickly and delivering good results to the customer in a timely manner. In particular, you will learn how to work with our templates so that you don’t have to start from scratch.

We recommend to start by adopting an existing design for BSI CX. This will help you to get started and will already come with existing content elements which act as examples for your customizations. BSI provides a set of design templates that are called Master Templates. The Master Templates for email and web (including landingpage and website) are publicly available on GitHub as an MIT licensed open source project.

Besides, the design build which is used to build the templates, as well as the library for email content elements and web content elements on which the templates are based, are MIT licensed open source projects.

Alternatively, you can start off from scratch by using the Scaffold Design and following the guidance in this documentation to build a completely new template.

Technical Introduction

This documentation acts as the primary resource for developers that wish to implement a design for BSI CX. For implementation of designs for BSI CX 22.0 and later, see also Designs since BSI CX 22.0 and our wiki at GitHub.

Designs are a vital part of BSI CX. While focusing on BSI CX Designs, a basic knowledge of the following layers is necessary:

cx illustration story content design
Story

The Story controls the flow of a participant. It offers various steps which can be placed on the storyboard via drag and drop. Your next customer journey delivering a landing page, event invitation, website or newsletter will be born here.

Content

Websites, landing pages and newsletters require rich content. The content editor of BSI CX is here to configure such contents. By user using Content Elements – reusable building blocks that can be placed in your content via drag and drop – you can build attractive newsletters, innovative landing pages and feature rich websites.

Design

The foundation of every Content is its design. The design defines the available „Content Elements“, the visual representation of the content and the behavior of the content and content elements. The Design must be created externally and uploaded into BSI CX. This documentation covers how to build such designs.

Branding & Visual Design

Each brand has its own and unique visual design language. The branding guidelines of your company or customer define the boundary conditions for building a design. As a design developer for BSI CX, it is your responsibility to get a specification on how the website, landing page or newsletter should look like and what elements it should consist of. Especially when it comes to designing HTML emails, you may have to find a compromise between the developers' ideas of visual design and the actual technical possibilities of HTML emails.

Constraints

Our build and the CX-Editor has to be taken "as-is".

If the Design Validation fails or the Editor doesn’t show the Elements properly, it’s the responsibility of the developer (probably you) to adjust the template accordingly.

There are some web technologies we do NOT support. Two common examples are:

  • Webcomponents might work in the resulting landingpages, but are not supported within the CX editor.

  • Other Frameworks like Angular or React are familiar to most web developers, but not supported by CX.

We strongly recommend you to use our npm build or the CX-Design-Creator. Feel free to contact the design team, if you miss a feature or have an improvement idea.

We recommend to start by adopting an existing design for BSI CX. This will help you to get started and will already come with existing content elements which act as examples for your customizations. BSI provides a set of design templates that are called Master Templates. The Master Templates for email and web (including landingpage and website) are publicly available on GitHub as an MIT licensed open source project (see Designs since BSI CX 22.0). Alternatively, you can start off from scratch by using the Scaffold Design and following the guidance in this documentation to build a completely new template.

Designs since BSI CX 22.0

As of BSI CX 22.0, a new design build has been introduced to create design ZIP files that are uploaded to BSI CX using a webpack build. The build is NPM based and replaces the previous BSI Design Creator, which used to be available as an executable file. The technical adjustments that come with the new design build are documented in the design build wiki at GitHub. Existing designs can be migrated to the new design build using the migration instructions (see [design-build-migration-guide]).

In addition, new Master Templates for email, landingpage and website have been developed. As a new feature, a library is available as a read-only core for these templates. This Standard Library includes all content elements and the Master Template finally builds on this library. Furthermore, new content elements, such as charts, are introduced in the Master Template and more CX features (especially styles) come into play.

Both the Standard Library and the Master Templates are available as MIT licensed open source software on GitHub to enable access to the source code, to enable notifications about new versions and to collaborate on the templates through pull requests and issues:

The current design zip files for uploading to CX are available for download in the GitHub releases of the respective Master Templates.

File format

Please refer to version 16.3 of the CX design documentation for file format up to BSI CX version 16.3.

A BSI CX design is stored in a ZIP archive. A valid design for BSI CX since version 22.0 must contain the following mandatory files:

design.html

Defines the design, particularly the dropzones the user can use in the BSI CX content editor to place content elements. The exact design.html syntax is described below. This file must be in the root of the ZIP file.

design.json

Contains metadata on the design, such as names and descriptions of the content elements and groups. The exact design.json syntax is described in chapter [designjson]. This file must be in the root of the ZIP file.

Besides these two mandatory files your design will need some content elements. Typically, a folder named content-elements contains all content elements of the design as html files. These elements can later be drag and dropped into the dropzones of the design.html. A content element is an HTML snippet that does not require any Doctype, <html>, <head> or <body> tag.

Additional optional files and folders may be supplied in the ZIP file as well. Note that one ZIP file can only contain a single design.

The files and folders in the ZIP file must not contain any umlauts.

The following folder structure showcases the content of a simple design:

design.zip
│   design.html (1)
│   design.json (2)
│   preview.html (3)
│
├───content-elements  (4)
│       button.html
│       text.html
│
├───css
│       styles.min.css
│
├───img
│       logo.png
│
└───js
        3rd-party.min.js
        scripts.min.js
1 The mandatory file design.html defines the base layout of the page/email.
2 The mandatory file design.json contains meta information about the design and its elements.
3 The optional file preview.html contains a preview of the base layout including some elements.
4 The content-elements folder holds all content elements html files.

Content Editor

The content editor is where specific websites, newsletters and landing pages are created. The content creator relies on a design of good quality to build contents which on the other hand are referred from a story.

Content Editor
Figure 1. example of the BSI CX content editor

  1. Design preview in content editor

  2. List of available content elements

  3. Use of a customizable content element

Content Security Policy (CSP)

If a design requires resources from external servers, e.g. from a Content Delivery Network (CDN), two settings must be checked in the BSI Customer Suite and, if necessary, adjusted according to the needs of the design. The settings can be configured by a user with the appropriate permissions in the BSI Customer Suite administration.

Observe the notes on the integration of CSS and scripts in chapter [Control Attributes].

HTTP headers for public links

The HTTP headers including CSP settings for CX landing pages and websites are configured here. These are relevant for displaying the landing pages and websites in the end user’s browser.

HTTP headers for the index page of the BSI Customer Suite

The HTTP headers including CSP settings for the index page of the BSI Customer Suite are configured here. This includes the CX Content Editor. This setting overrides the server-side configured default values for CSP.

This setting should be configured more restrictively than the setting for landing pages and websites above. Only what is absolutely necessary for error-free display in the content editor should be allowed. As a rule, styles and fonts are allowed, but not JavaScript.

The CSP settings configured here apply to the entire BSI Customer Suite GUI, not just the CX Content Editor.

Structure Reference

The file design.html contains the frame of the design and must include at least one outermost dropzone. It must contain valid, XHTML conform HTML with Doctype, <html>, <head> and <body> tags.

The individual content elements are HTML snippets that are inserted into the content using drag & drop.

structure reference
Figure 2. structure reference

Dropzones

While dragging a content element into the content area, you will notice blue lines and blue areas. These areas are called dropzones and identify areas where certain content elements can be placed. Each dropzone has a list of allowed content elements that are specified in the design. A dropzone is defined by adding the attribute data-bsi-dropzone to an HTML container element (e.g. <div> or <table>). The list of allowed content elements is specified by the data-bsi-dropzone-allowed-elements attribute. An optional limit of elements that can be placed inside the dropzone is defined by adding the data-bsi-dropzone-max-number-of-elements attribute.

dropzone example
A dropzone that allows to place a maximum of one pre header element inside a newsletter design
<div data-bsi-dropzone="preheader-zone" data-bsi-dropzone-allowed-elements="nl-preheader" data-bsi-dropzone-max-number-of-elements="1">
    <!-- Add element -->
</div>
Problems can occur when placing a dropzone into a link or button element. In this case, we recommend using a style.

Groups

Groups1

All content elements can be structured in groups. In the example screenshot on the left side, three groups are defined: Header, Headings and Text & Images. The structuring of content elements in such groups is implemented in the design.json file. For more information see chapter [groups-designjson]. A group may be defined only once.

Additions to Designs in BSI CX 25.1

Starting BSI CX 25.1 a new Schema-Version of the design.json file is allowed: 25.1. This schema version enables handlebars content elements. Handlebars is a templating engine that decouples the user input in the content element editor from the concrete DOM structure that is rendered into the BSI CX content.

Since Handlebars templates always need an object supplying the variables for rendering (in our case as a JSON-document), the structure of the design ZIP changes slightly.

design.hbs

Instead of a design.html a handlebars template can be supplied. It will be preprocessed (rendered) before being loaded into the content editor.

design-context.json

This JSON-document supplies the variables used to render design.hbs. In the case of websites this file can be omitted, since in the context of BSI CX websites, the context is supplied on include-level.

design.zip
│   design.hbs (1)
│   design-context.json (2)
│   design.json
│   preview.html
│
├───content-elements
│       button.html
│       text.html
│
├───css
│       styles.min.css
│
├───img
│       logo.png
│
└───js
        3rd-party.min.js
        scripts.min.js
1 The file design.hbs supplants the formerly used design.html.
2 Once Handlebars content elements are being used in design.hbs, the design-context.json file becomes mandatory.

Including Handlebars Content Elements in design.hbs

HTML content elements could be included in the design.html by copying the DOM from the content element source file into the body of the design. Changes in the default value took place directly in the DOM of the design. Handlebars content elements work analogous.

The template from the content element source code can be copied into the design.hbs, but two additional steps are necessary. Let’s take the example of a simple text paragraph content element.

The content element consists of a Handlebars template, and a variable context as such:

The template of the content element as defined in the design ZIP.
<div class="paragraph-light" data-bsi-element="paragraph">{{paragraph.value}}</div>
The accompanying context with the variables for the template.
{
  "paragraph": {
    "value": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
  }
}

After copying the Handlebars template to design.hbs, we need to supply the values for the variables contained in the element in design-context.json. This is achieved by adding the custom attribute data-bsi-context-scope with a unique name for the element on content element. All variables used within the element need to be prefixed with this unique name. This unique name then also refers to the element in design-context.json:

Part of design.hbs.
<div class="paragraph-light" data-bsi-element="paragraph" data-bsi-context-scope="headingParagraph">{{headingParagraph.paragraph.value}}</div>
A complete design context referencing the Handlebars content element above.
{
  "headingParagraph": {
    "paragraph": {
      "value": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
    }
  }
}

E-mail Preview

This section applies only to BSI CX 25.2.22 and greater.

E-mails that are viewed in the browser through the "Show e-mail as website" redirection on the e-mail step have the CSS class bsi-email-webview added to the HTML tag. Using this tag the design can react to web-previews and e.g. hide the link used to open the web-version.