Content Editor

When you display data in a table, you will use the iterator feature of BSI CX. In this example we display a list of blog articles.

In the content editor you use a table content-element. You activate the 'Dynamic table' checkbox in the editor form. Now you define the columns. Let’s assume we have 3 columns:

The third column defines two iterator bracket links. The link ID must start with the entity prefix, which is followed by an arbitrary name that defines the function of the link.

When you use this content in a media step in the storyboard, the step will provide a GUI, to pick an entity and the values for the placeholders 'title' and 'releaseDate'. For the two links the step will generate two outlets. A consequent step connected to these outlets can pick from the iterator property which is labeled with 'Chosen via link' and can access the properties of that distinct iterator item.

When BSI CX converts a [placeholder] term internally into a link tag, it adds the CSS class placeholder-link to the a tag. This allows bracket links to be selected and styled separately from other link elements.

It should be noted that the CSS class is not set until the live content is rendered. For this reason, you won’t find the styling, referring to the CSS class placeholder-link, in the content editor, but only - in the case of email content - in the sent email.

First of all, it is possible to use anchor links in the form of #top inside a BSI CX design. Anchor links are allowed as targets of link parts. However, it is not possible to use anchor links as url of a bracket link. This is due to the fact, that bracket links meant to be trackable by BSI CX and this requires a complete roundtrip to the server.

The template engine Handlebars is available to the design developer at runtime. The templates are parsed server-sided. We’re using the Java-Port by JKnack. In the design, handlebars templates are important especially for display of the navigation.

Handlebars templates can only be used for parts of a website that can’t be edited by the user. We set that rule, because templates are parsed server-sided. When the content-editor receives the HTML source, the templates have already been resolved. If the user would edit a content-element that contained handlebars syntax, we could only save the rendered content that the user edited. The original handlebars code would be lost.

For that reason, handlebars should mostly be used for includes that can’t be edited. Examples for such includes are the master (design.html), the navigation or areas outside a dropzone.

This mechanism can also be used consciously to set multilingual default texts, which are deposited inside the website.json file. An example for an include for the website header in handlebars code could look something like this:

On the initial rendering of the page inside the content editor, the text "website.title" is resolved. As the user saves the page, the initial handlebars code is substituted by the actual text.

Handlebars syntax can also be used in the content-element source files; especially for the NLS-helper to define multilingual default texts for each content-element. Content-elements with Handlebars must have the file extension .hbs.

Important: Files that contain Handlebars syntax aren’t valid HTML documents. They shouldn’t be handled with HTML parsers like JSoup, otherwise the handlebars syntax gets corrupted. Files that include handlebars code should use the suffix .hbs. IntelliJ supports this syntax with respective plugins.

This chapter describes the necessary configuration files.

All files that are inherited to the database on the creation of a website as navigation item or include have to be referenced in the design.json file. All includes from the design.zip are inherited automatically with content-type=built-in, unless content-type=pre-defined is set explicitly.

The file design.html matches the master and is automatically created inside the website internally as an include with the reference master. For that reason this include should not be defined in the design.json file, as it is defined already.

The minimal include is page, which works as a template for new pages within a website.

The key, which is used for the bsi:include-tags, is used as a unique reference to the include.

For each include, the following properties can be configured:

Before the content is displayed in the editor, it has to be preprocessed by the WebsiteProcessor. It resolves includes and starts the template-engine. Just like the live-website, the content editor also creates an object with website variables.

Here is an example for content, when it’s loaded from the database:

Here is an example for content, when it’s shown in the editor:

Pagination can be used to distribute data supplied by an external system (e.g. via REST) to several pages on a website, so that only part of the data is displayed on one page. With Next and Back buttons on the website page, it is then possible to display a separate set of data on each page.

The pagination must be defined via website: pagination in design.json and provided via an include. The include must exist in the design.json file and have the special include type pre-defined (see Website-specific metadata inside design.json). The include itself should have the extension .hbs and use handlebars. The possible values for the Handlebars templates are documented in the chapter on website variables (see Pagination (Object)). Besides, the attribute data-bsi-hide-edit-button should be set, as includes that use handlebars should not be editable in the website editor. The following is an example of a possible template:

This template (include) is then rendered by the template engine at runtime. One possible output is the following. Everything except page 20 are links pointing to the respective pages.

[First Page] [18] [19] 20 [21] [22] [Last Page]

The data to be rendered via pagination can finally be displayed with the table content element. For this, a content element with the element part table should be extended by the attribute data-bsi-show-pagination-field. The following is an example of a possible table template:

If the attribute data-bsi-show-pagination-field is set, the checkbox with Pagination will be displayed in the configuration of the table content element. In order to use pagination, the checkbox should be activated.

Each page and each folder of a website can have JSON metadata and an image to describe the navigation. These two elements are special, because they can only be edited programmatically and within a project-specific step. A possible use case is a REST webservice, which is embedded to the design through javascript. The project-specific step can return the image and the metadata on a GET request. This allows the rendered website to give images and information to the navigation.

These two attributes are invisible per default. However, they can be enabled through the BSI CX setting Website-Editor. Both attributes are the same for every language, so it’s not possible to deposit different images for a German and an English website.

It’s highly advised to use the Google reCAPTCHA service "I’m not a robot", when using username/password authentication with non-internal users (public). For that we use the optional BSI CX module com.bsiag.studio.media.googlerecaptcha, which can be configured in the BSI CX settings.

Example for including the dependency in the BSI CX app and the dev pom.xml:

A script can be included on the website’s design.html:

The captcha-field can be added to a login form content element as follows:

The label text can be added to the design.json as follows:

After that, the field ID of the captcha field (on the website, that uses the design, simply open the edit dialogue and scroll down to the captcha field ID) has to be set to g-recaptcha-response. This value has to match the settings of the Google reCAPTCHA in the administration view.

The last step is to generate a reCAPTCHA key on the Google Cloud of the customer/company and register it in the settings under Administration - Customer Experience - Settings - Google reCAPTCHA Settings.

For local testing, the URL of the BSI CX website can’t be localhost. For this purpose, the local domain bsiag.local may be used. Simply go to the administration view - CX - Settings under base URL for public links and register a second path, e.g. bsiw0160:

Then select this URL on the smart field base path on the website step.

Here is an approximate guide for the creation of a reCAPTCHA site on the example of BSI (customers have to adapt it to their company):

Documentation:

The following steps are necessary to create a website template from an existing landingpage template:

The BSI CX design must provide a teaser content element, based on a Handlebars template.

Here is an example for a teaser content element (teaser.hbs):

Here is an example for the context file for the teaser content element (teaser-context.json):

The following properties in the JSON are mandatory:

You must set these properties in the context JSON, in order to render a proper preview in the BSI CX content editor. All other properties in the context JSON are regular properties required for the Handlebars feature. In this example the design defines two fields 'teaserTarget' and 'teaserRendering' for this content element.

The following data BSI attributes, can be used for teaser content elements:

If the value for the attribute data-bsi-teaser-rendering is set to client-side the HTML remains untouched by the BSI CX backend. However, the attribute data-bsi-teaser-endpoint will be added to the DOM. The attribute value provides an absolute URL to make a REST call from the web frontend to the EIP system.

If your BSI CX design must support client-side rendering, you need to add some JavaScript code to your design. A simple example implementation can look like this:

This function manipulates the DOM to apply the values from the teaser data request. See the code snippet for the teaser.hbs above, to understand how the HTML looks like for this example. Also note that some properties values can contain HTML, to avoid security issues, you should always sanitize the HTML before adding it to the DOM.

When the BSI CX backend detects, that it is not possible to request teaser data, for the current participant in BSI CX, the attribute data-bsi-teaser-endpoint will be empty. This can happen, if the participant is not a CRM customer. In that case the design author should skip the REST request and hide the teaser content element, or show a generic placeholder instead.

You have already learned that teasers are basically JSON data. This means a content author must configure JSON data for a teaser, as he or she would do with HTML content. In order to do that, BSI CX defines the content type 'Teaser'.

BSI CX comes with a special built-in design for this content type. Basically this design type works as a regular HTML based design. BSI CX uses the regular content editor to work with teaser content. However, although we work with HTML content in the content editor, this content is later transformed to JSON data by the BSI CX framework.

In order to do that, the content elements in the JSON design must use the following data BSI attributes:

Example 1: a simple plain text content element for the JSON editor. The content user can freely define a property name in the content editor.

Example 2: an image element for the JSON editor. The content user can freely define a property name in the content editor.

Note, the DIV with the class "json-property" is just eye candy to visualize the property name in the content editor (see the image below).

As in a regular design, you can use existing element parts to build your JSON content elements, like the image element part, for choosing images from the BSI CX media library.

You can also build JSON content elements that emit multiple json properties, like a CTA button that emits a ctaText and a ctaUrl.

With that you can provide a reasonable content preview to the content user, although he or she configures just JSON data. This is how the JSON design looks like in the content editor: