Design Documentation: BSI CX 24.1

To customize the color picker for textColor and backgroundColor, provide a list of colors as follows:

Paragraph formatting and headings can be configured as well. This may be customized through the formats value list, which will only have an effect if the feature paragraphFormat is active.

The following formats can be provided:

To customize the lineHeight value list, provide a list of heights in percentages, comma separated. The line height values define the factor by which factor the current line height is multiplied based on the font size used.

To customize the list of font sizes, provide a list of sizes for fontSizes. A custom default value can be set by using fontSizeDefault.

Size information is provided numerically. If several sizes are permitted, then each individual entry is listed in a comma separated format. The data on font sizes (font size and font size default) are absolute values.

The unit of measurement (fontSizeUnit) defines which unit to be used for information regarding the font sizes. The following are permitted:

By defining the entry mode (enter), you define what happens in the editor when the Enter key on your keyboard is pressed. The following options are available:

In p and div modes, there is the option to force a simple line break with Shift+Enter. This will add <br> without immediately ending the block and starting a new one.

The part plain-text can be applied to any HTML element that can contain text. The text is inserted within the element. The element must not have children with other content element parts (content is removed). A single-line text field without formatting is available as the editor. When using the optional attribute data-bsi-multiline, the text field becomes multiline.

The part formatted-text can be applied to any HTML element that can contain text. The element must not have children with other content element parts (content is removed). The rich text field with a limited number of formatting options is available as an editor. For more information about the available configuration options see chapter Configuration capabilities of the Rich Text Editor.

The html part can be applied to any HTML element. The code is inserted within the element. The element must not have children with other content element parts (content is removed). A text field is used as the editor. HTML can be written directly into this field.

This part can be useful for:

The video part can be applied to any block level HTML element. This part can be used to display information and thumbnails of external videos. It can also be used to embed external videos. Within the element, various elements can be used as placeholders:

The following external video providers are supported:

Be aware that there are two kinds of URLs involved: One is the link to the video platform itself for the href attribute on the <a> tag and there is the embedded URL for the <iframe> player. In the case of YouTube https://www.youtube.com/watch?v=YpnFs4aBLQA is the link to the video platform. The corresponding embedded URL would be https://www.youtube.com/embed/YpnFs4aBLQA. If you want to provide sample content for your element you may have to fill both URLs in the right tag. The following listing illustrates the use of sample content for a simple video element:

This results in the following content element:

A more complex video element would be the following:

This results in the following content element:

The video part is quite powerful and can be used in various ways:

The image element part can only be placed inside of a <img> or <a> tag. The source is inserted in the src attribute.

It is not possible to omit the image of an image part. Therefore it is mandatory to specify an image in the content editor. Otherwise a validation error will occur.

An arbitrary element which permits the use of a CSS background-image. It places the CSS attribute background-image. The image selection is available as the editor just like with the image part.

A <div> oder <td> element with a table element as a direct child element. The table content is filled according to the editor (including colgroup). Colspan is not supported. On even or odd rows or columns, the CSS class even or odd is placed. The <th> tag is used for header columns, if specified. This part does not support <thead> and <tbody> tags.

An arbitrary element. The attribute data-bsi-iterator can be defined on this element. The attribute data-bsi-iterator-item must be defined on the element or on one of the included elements. This defines the element to be duplicated. If data-bsi-iterator is defined and the iterator does not provide any data, the entire element is removed. Otherwise, only the element to be duplicated is marked with data-bsi-iterator-item.

A text field is used as the editor. The name of the iterator can be placed in this text field.

An arbitrary element. Displays a news item. Within the element, elements with the data-bsi-property attribute can be defined. This attribute may have the following values: image, title, headline, or text. The content of these elements is then replaced accordingly with the value of the selected news item. In that context, elements from property title, headline, and text are mandatory.

If a link in CX is configured into a news snippet, title and image are automatically supplemented with a link. When generating the news list, the following CSS classes are automatically set on a news snippet to permit better styling of the individual elements:

A <form> element. The element must contain a submit button and may also contain a reset button. Those buttons must be <input> elements. In the form configuration, the reset button can be hidden or displayed. In that case, the DOM attribute disabled is set on the input element.

The form element must contain an element with the data-bsi-form-validation attribute, and this attribute must contain an element with the data-bsi-form-validation-item attribute.

Within the element with data-bsi-form-validation, the element with data-bsi-form-validation-item is duplicated for each error in the server-side form validation, and the validation message is inserted as the content of the validation item element.

In addition to the display in the above-described element, a data-bsi-form-validation-message attribute is set for each defective form field. It contains the validation error for the respective field. The attribute can be used to style the field with CSS if there is an error (CSS selector checks for the presence of the attribute) or to display the error message with CSS and/or JavaScript in the respective field.

The following form fields can be marked as mandatory fields in the content editor. If this is done, the required attribute is set in the relevant HTML element. Thus, the mandatory elements are styled using the respective CSS selectors.

To exclude a certain form from CX you set the data-bsi-form-ignore attribute on the form tag. Any form with this marker will be left untouched by CX.

A <div> element. Contains a <label> and an <input> element. In the configuration, the label, initial value, mandatory field, and input type can be defined. The following input types are supported:

To fixate the form field type, the data-bsi-form-field-fixed-type attribute can be used on the element. Doing so allows the setup of a customized date field, for example. The type of the form field is then set and cannot be changed in the content editor.

The attribute data-bsi-hide-required controls whether the mandatory checkbox is visible and editable in the content editor. If the checkbox is not shown, the original state of the required attribute is preserved, as defined by the content element.

A <div> element. Contains a <label> and an <input> element with the checkbox type.

The attribute data-bsi-hide-required controls whether the mandatory checkbox is visible and editable in the content editor. If the checkbox is not shown, the original state of the required attribute is preserved, as defined by the content element.

A <div> element. Contains a <label> and a <textarea> element.

The attribute data-bsi-hide-required controls whether the mandatory checkbox is visible and editable in the content editor. If the checkbox is not shown, the original state of the required attribute is preserved, as defined by the content element.

A <div> element. Contains a <label> and a <select> element with the elements option. The pre-allocation of the element can be controlled with the data-bsi-value and data-bsi-value-list attributes. The data-bsi-value attribute contains the preal-location, and the values available for selection are defined in the data-bsi-value-list attribute. A line break (\n or \r\n) separates each of those.

To fixate the values that are available for selection, the data-bsi-form-select-fixed-value-list attribute can be set on the element. Then, the list of values cannot be changed in the content editor. Only the preselection can be changed.

The attribute data-bsi-hide-required controls whether the mandatory checkbox is visible and editable in the content editor. If the checkbox is not shown, the original state of the required attribute is preserved, as defined by the content element.

A <div> element. Contains a <label> and a <div> element as a radio group. The radio group is marked with the data-bsi-radio-group attribute. The radio group contains radio items. These are identified with the data-bsi-radio-item attribute and contain a <label> and an <input> element with the radio type. The preselection of this element can be controlled with the data-bsi-value and data-bsi-value-list attributes. Same as the form-select part. The same applies to the data-bsi-form-select-fixed-value-list attribute.

The attribute data-bsi-hide-required controls whether the mandatory checkbox is visible and editable in the content editor. If the checkbox is not shown, the original state of the required attribute is preserved, as defined by the content element.

The part is defined on the <a> element. As an option, the link content can be set with the data-bsi-link-fixed-inner-html attribute. If this attribute is present, only the href attribute of the link can be edited in the content editor. If the link text is to be placed in a tag within the hyperlink (e.g. in a span next to an <img> tag), the optional data-bsi-link-text-part attribute can be set on the tag.

Currently it is not possible to put a dropzone inside this link element.

A <div> element, contains <div> elements with a data-bsi-social-follow attribute. These attributes contain the value of the respective social media service, such as "Facebook", "Twitter", "Pinterest", etc.

The elements with data-bsi-social-follow must have the social-media-item class. This class is used to manage the visibility of each individual social media channel in the editor.

The elements with data-bsi-social-follow must also contain an <a> element. The link href can be preselected with a URL or with CX links in square brackets (e.g., [Facebook]).

The <a> element, in turn, can contain additional elements.

A <div> element, contains <div> elements with data-bsi-social-share. These attributes contain the value of the respective social media service, such as Facebook, Twitter, Pinterest, or even e-mail.

The elements with data-bsi-social-share must have the social-media-item class. This class is used to control the visibility of each individual social media channel in the editor.

The elements with data-bsi-social-share must also contain an <a> element. The link href can be preselected with a URL or with Studio links in square brackets (e.g., [Facebook]).

To share it via e-mail, the content of the href is then a mailto:?subject=(subject.with.title)&body=(description.with.url)

The <a> element, in turn, can contain additional elements.

The URL supports a list of wildcards that are specific to the social share part. When they are issued, all wildcards are automatically URL-encoded. These wildcards cannot be selected in the step configuration in Studio. The following wildcards exist:

The URL provider content element part can be used to load dynamic data inside a story. Inside the content editor, the URL provider part only offers a text field to define its name. When using the content inside your story, each URL provider part will produce a separate outlet. This outlets can be connected to any URL provider (e.g. the Charts Step).

When a story renders the content, the HTML tag with the url-provider part will have a data-bsi-url attribute. This attribute will contain an absolute URL to the CX server, where the data can be requested.

The presence of an HTML element in the generated content can be controlled by using data-bsi-remove-if. The attribute value can use the following boolean variables:

The attribute value may have a negate operator (!). Using this operator you can negate the condition, for instance !authenticated will only be removed in case the visitor is not logged in.

The attribute value can be a complex expression, see example below.

data-bsi-hide-edit-button may be used to prevent editing of a content element. The attribute must be located on the same tag as the data-bsi-element attribute.

data-bsi-hide-move-button, data-bsi-hide-copy-button, and data-bsi-hide-remove-button are working in the same manner, but on dropzone level. They will prevent from moving, copying, or removing content elements on a dropzone.

The template-engine Handlebars is available to the design developer on 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 conciously 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 may also be used for the content-elements.html file; especially for the NLS-helper to define multilingual default texts for each content-element.

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.

Besides the built-in standard helper, BSI CX may also use the following helpers:

This helper is used to display localized texts or resources inside the design. The syntax looks like this: {{bsi.nls "[textKey]"}}.

It can also be used inside the content-elements.html file to deliver localized default texts for different languages.

Text keys are created inside the design.json at the property nls. Text that doesn’t depend on the locale is defined with the key *. The resolution follows from the most specific locale up to the default, e.g.:

Following variables are available to the design developer on runtime. The variables can be used in mustache-templates, e.g.: {{navigation.activePage.contentId}}.

This example shows the possible content of a variables object on runtime.

The design.json file is a metadata file for structured configuration data.

Example for the design.json file for website designs:

The design.html file is equivalent to the "master" of the website. On the creation of a website, an include "Design" with this file’s content is created. This include can’t be edited by the user. However, the design can reference other includes that may be edited, so that e.g. the footer can be edited by the user.

A design can contain exactly one include for a page (attribute "pageid"). For the editor this include has a special meaning: when displayed in the editor, the full page (including the master) is displayed, but when saved, only the content of the respective page is saved.

Advice: There should be no tags of the template-engine used for includes or pages that the user may edit.

The include "footer-text" loads the built-in include footer-text.html. This file looks like this:

There are some limitations to pagination:

Your upload is missing a mandatory file. Please refer to File format where the mandatory files for your design type is described in detail.

In one of your data-bsi-dropzone-allowed-elements='' definitions, there is an element listed which does not exist in the content-elements.html file. Common cases where this happens:

The specified data-bsi-element-part is not supported by CX. For a list of supported element parts, visit the Parts documentation chapter.

A discrepancy was discovered when using a content element as sample content. The example must have the same HTML structure as the specified content element.

A dropzone can contain 0…​n content elements. Only content elements are allowed as direct child nodes of dropzones. Therefore, HTML that is not part of a content element must not be placed in a dropzone.

Make sure to user proper HTML tags for your element parts. Consult the content element Parts documentation for the validation error causing element.

In the example above, this would be the Image content element Parts documentation.

Make sure to user proper HTML tags for your element parts. Consult the content element Parts documentation for the validation error causing element.

After hitting the design update button or after a modification of your content, you may see a validation error indicated in the top-right corner.

In such a case, there is an issue in the design used by your content. The most typical error messages related to design issues are described in the following chapter. You may also see some that are already described in the Design Upload section.

The structure of one of your content elements that is being used right now in your content does no longer match it’s specification.

The details of such an error message always have the same structure:

If the difference is difficult to find, we recommend using a diff tool to compare the concrete content with the content element specification.

The root cause of a difference between a concrete content and the content element specification may be one of the following: