Styling of (grouped) questions and texts
The goal of this document is to try to guide you through the HTML structure of the part where questions are asked and answered. The documentation is geared towards front-end developers developing or maintaining CSS code to style the presentation layer.
This document assumes the presentation layer uses
form-group, a core feature introduced in the fall of 2020, providing implicit and explicit grouping of texts and questions. This feature needs to have been turned on in the presentation layer.
Any classes or attributes present in actual code not documented here are only used for application logic, and not meant to be used as hooks for styling.
First of all, an ASCII-art representation of the structure. Further explanation follows below.
+--#bb-q---------------------------------------------------------+
| |
| Container for shown steps within a decision model |
| |
| +--fieldset.group-----------------------------------------+ |
| | | |
| | A single step within a decision model, divided into | |
| | one or more .form-group divs | |
| | | |
| | | |
| | +--div.form-group.form-group--text--------------------+ | |
| | | | | |
| | | Auto-generated, containing readable text | | |
| | | | | |
| | | +--legend/h1——h6/div-----------------------------+ | | |
| | | | | | | |
| | | | .form-group__item--author-class-<authorclass>(opt)| | |
| | | | .bb-text | | | |
| | | | .bbm-<authorstyle> | | | |
| | | | _ _ | | | |
| | | | | |_ _____ _| |_ | | | |
| | | | | __/ _ \ \/ / __| | | | |
| | | | | || __/> <| |_ (or further elements -- | | | |
| | | | \__\___/_/\_\\__| authors can use Markdown) | | | |
| | | +------------------------------------------------+ | | |
| | | | | |
| | +-----------------------------------------------------+ | |
| | | |
| | +--div.form-group.form-group--interface---------------+ | |
| | | | | |
| | | Auto-generated, containing questions and | | |
| | | question-like elements. | | |
| | | | | |
| | | .form-group--required: all questions are required | | |
| | | | | |
| | | +--div.form-group__question----------------------+ | | |
| | | | | | | |
| | | | .form-group__question--<type> | | | |
| | | | .form-group__item--author-class-<authorclass>(opt) | |
| | | | .question--required (opt) | | | |
| | | | | | | |
| | | | | | | |
| | | | [data-form-group-layout="aside|below|inline"] | | | |
| | | | | | | |
| | | | +--label -----------------------------------+ | | | |
| | | | | | | | | |
| | | | | .bb-label | | | | |
| | | | | .bb-for-required (opt) | | | | |
| | | | | .bbm-<authorstyle> | | | | |
| | | | | [data-type="label"] | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | +-------------------------------------------+ | | | |
| | | | +-(spanned) answer--------------------------+ | | | |
| | | | | | | | | |
| | | | | .bbm-<authorstyle> | | | | |
| | | | | .validatable (opt) | | | | |
| | | | | .validated (opt) | | | | |
| | | | | .invalid (opt) | | | | |
| | | | | | | | | |
| | | | | [aria-required="true|false"] | | | | |
| | | | | [aria-invalid="true|false"] | | | | |
| | | | | [data-datatype="<type|datades:id>"] | | | | |
| | | | | | | | | |
| | | | +-------------------------------------------+ | | | |
| | | | | | | |
| | | | | | | |
| | | +------------------------------------------------+ | | |
| | +-----------------------------------------------------+ | |
| | +--div.form-group.form-group--author------------------+ | |
| | | | | |
| | | Author-defined, containing texts, questions and | | |
| | | nested .form-group divs | | |
| | | | | |
| | | Inherits from the other two, in classes, attribs | | |
| | | and elements, plus: | | |
| | | | | |
| | | [data-form-group-name="<authorname>"] | | |
| | | | | |
| | | ... and of course nested | | |
| | | | | |
| | | +-div.form-group.form-group--*-------------------+ | | |
| | | | | | | |
| | | +------------------------------------------------+ | | |
| | | | | |
| | | +-div.form-group.form-group--*-------------------+ | | |
| | | | | | | |
| | | +------------------------------------------------+ | | |
| | | | | |
| | | +-div.form-group.form-group--*-------------------+ | | |
| | | | | | | |
| | | +------------------------------------------------+ | | |
| | | | | |
| | +-----------------------------------------------------+ | |
| | | |
| +---------------------------------------------------------+ |
| |
+----------------------------------------------------------------+
First of all, a decision model consists of a sequence of steps.
Usually only a single step is shown on a page, but authors may choose to keep previous steps in view.
The visible steps are grouped in a top-level div#bb-q.
Each step is a fieldset.group.
These steps in their turn contain one or more div.form-groups.
These .form-groups have three further variations:
.form-group--text: a group with a (single) text block.form-group--interface: a group with a label and a question.form-group--author: a group defined by the author of a decision model, may contain any number of questions, text blocks, and further nested.form-groups.
Any .form-group has the attribute data-form-group-level, set to
the level of nesting within the fieldset.group (1-based).
If a .form-group is also .form-group--required all of the
questions within are required.
.form-group--text
Text groups contain a single legend, h1, h2, h3, h4, h5, h6 or div.
.form-group--interface
Interface groups contain a single div.form-group__question.
.form-group--author
Author-defined groups can contain any number of questions, text
blocks, and further nested .form-groups. Everything said about
.form-group--interface and .form-group--text also holds true for
.form-group--author, except, of course, that they can have multiple children.
The attribute data-form-group-name contains the name the author put
on the group.
.form-group__question
This .form-group__question in turn tells us, via the attribute
data-form-group-layout whether its child question widget is to be
displayed inline (for check boxes), below or aside to its
label. The default placement is the following:
-
inline: checkbox
-
aside: input (edit), date picker, number input, free-box, range, grid
-
below: textarea (memo), link (linklabel), list (listlabel), select (combobox, listbox, multilist), check list, radio group (radio)
This placement can however be configured. The configuration that is used can be viewed at custom/<theme-name>/conf.json (Tip: use view source, and the first script tag has a link to that file). If a design needs this to change, the configuration needs to be changed and the layer needs to be recompiled.
The type of question present in a .form-group__question is shown via
classNames: .form-group__question--<question type>. See below at
Question types to what these mean.
Whether the question within is required is reflected in the class .question--required.
Its children are labels, input widgets and optional strong.errortext error elements.
An author may have given the question a certain “style”, which is
translated into a class of the form
.form-group__question--author-style-<author-provided-name>.
Question types
The names of question types are a bit odd to us front-end developers, reflecting their origin in a Windows desktop world. So here’s an explanation.
- edit: your omnipotent
<input type="text" />.* - numedit:
<input type="number" />.* - datetimepicker:
<input type="date"/>.* Enhanced with jQuery-UI and custom accessibility feedback. - combobox:
<select>.* - freebox:
<input type="text">with a datalist.* - checkbox:
<input type="checkbox" /> - linklabel:
<a href> - listlabel: A
ULwith list items - memo:
<textarea>, - checkmultilist: a
ul.bb-option-list[data-type="checkmultilist"]with list items containing check boxes (a check list). - grid: an interactive table; label should be rendered as a caption, but often isn’t, for backwards compatibility. Each cell can have further texts or question widgets.
- radio: a
ul.bb-option-list[data-type="radio"]with list items containing radio buttons (a radio list).
And two that should not be used, ever:
- listbox: awful
SELECT singlewith a height => use radiogroup instead - multilist: awful
SELECT multiplewith a height => use checkmultilist instead
* These first five input types may be wrapped in div.bb-input-wrap
to account for pre- and post texts (€, m³). In some configurations
(arbitrary.core.wrapAllSingleLiners = true) they all are. That makes
some designs easier. The .bb-input-wrap says what kind of interface
it wraps with the attribute data-wraps-type. If the interface it
wraps has an error, this wrapper also has the class .bb-input-wrap--error.
Styles given by the author
There are two ways an author may indicate a styling requirement. The
first is via a single author style (<authorstyle). The author style is
intended only for base text classes. In the Windows desktop version of
the Expertsystemen software authors could define any style name (and
their looks), but those are days of yore, and currently they are
predefined and restricted to the following semantic list:
- Standard title ( => h1 )
- Heading2 ( => h2 )
- Heading3 ( => h3 )
- Standard text
- Standard remark
- Standard message
- Standard error
- Standard conclusion
Note the headings start with h1, but the configuration of the presentation layer will demote them as needed to fit in hierarchically with the rest of the page.
These styles are conferred to the HTML as .bbm-<authorstyle>.
The second and preferred one for anything beyond the base classes is
directly via classes an author may add to a text or
question: <authorclass> (via the metadata cssclasses).
These are attached to form group items as zero or more
.form-group__item--author-class-<authorclass>.