Agent Guidance Core User Guide

Please email support@creovai.com for omissions or errors.
×
Menu

Configuring Stylesheets

 
Agent Guidance allows the creation and management of multiple Stylesheets that can be configured using the CSS or SCSS styling languages, and then easily applied to one or more Workflows. This allows ensuring an easily-applied and consistent visual style across Workflows, simplifying the Workflow design process and agent usage and handling.
 

How To

Within the Stylesheet editor, there are three key sections: choosing a background image, choosing a logo, and specifying the CSS or SCSS code to implement page styling.
 
The background image and logo do not have to be configured via these pickers (instead being configurable directly from the code editor), but they allow an easier configuration as well as seeing a preview of the relevant image(s).
 
CSS or SCSS code can be entered directly into the code editor, making use of core HTML selectors, Agent Guidance-specific identifiers and classes, or custom classes.
 
The definitions within the Stylesheet act as the default for a Workflow, with it then being able to be overridden per-Field, per-element, and per-attribute by simply configuring the Field's styling as usual through the Styling tab.
 
Stylesheets are assigned to Workflows from a modal accessed from the toolbar in the Designer.
 
See the Example Stylesheet Structure article for an example of a fully-defined Stylesheet that can be used as a basis for your own Stylesheets.
 
Important: any changes made to a Stylesheet will be immediately applied to all assigned Workflows upon saving, including for agents who are part-way through a record. If you wish to test out a new styling option, it is recommended to try it in a test Stylesheet that is only assigned to a test Workflow.
 
 
CSS Concepts and References
CSS is the core technology used to style all websites, taking the form of defining styling content (such as font size or colour) against selectors. These selectors can be limited to a specific element on the page by its ID, types of elements (such as labels or inputs), or assigned classes against these elements. Definitions can also be made against multiple selectors simultaneously by separating them with commas, or against combinations of selectors to filter the selection down further.
 
A key feature of CSS is that it is hierarchical, with elements inheriting their styling from any and all relevant "ancestors". In cases where aspects of these styling definitions conflict, the most specific styling definition for that aspect is used for the child element. This is only overridden by the special !important property, which can be used to override the definition for a selector regardless of the existence of any more-specific styling definition; the only way to override an !important declaration is with an even more specific usage of another !important declaration. As such, the !important property should only be used where necessary.
 
Most styling is configured against classes, be they Control- or element-specific classes added by Creovai, or custom classes specified by the Workflow's designer. Styling can also be configured against HTML element types, and this can be used in conjunction with a Control-specific class name to modify the individual elements of a Control's styling. Least commonly, it's also possible to configure the styling against specific elements by their ID; this is less-commonly used because it doesn't provide the genericity and consistency that are the core features of using a Stylesheet, but may be used for specific unique elements like the background or logo images.
 
CSS is widely documented across many online references and courses, with resources such as W3Schools providing a free guide as to usage of CSS, as well as reference documentation of the CSS properties and selectors.
 
 
SCSS Concepts and References
SCSS is an extension of the core CSS styling language, acting as a strict superset: anything that can be written in CSS can be written in SCSS identically, but SCSS also allows more powerful functionality to be written that is then automatically converted down to the relevant CSS when it is applied to the Workflow.
 
Three powerful SCSS features that can be used to produce Stylesheets are nesting, variables, and mixins and includes:
 
SCSS has an introductory guide, and more general documentation. For the purposes of checking feature functionality and compatibility in the documentation, Agent Guidance is currently using LibSass version 3.3.7.
 
 
Control Classes
Each type of Control that has some visual component also has an Creovai-defined class assigned to it to allow easy modification of each type of Field in a Workflow. The classes are defined in the "How To" section of each visible Control's article, for example the Text Box.
 
This Control-specific class will refer to the top-most element(s) of the Control, specifically the "cell" that surrounds the Control. This means that to modify individual elements of a Field's styling will often require a more specific CSS definition than just the Control-specific class.
 
See the Example Stylesheet Structure article for examples.
 
 
Styling Elements
It is also possible to use a shorter version of the Stylesheet definitions that allows broader definitions to be applied across multiple types of Fields or common elements in fewer definitions. This does, however, mean that there isn't the same per-Control customisability that is available in the above approach.
 
See the Example Stylesheet Structure article for examples.
 
 
Background
A background image can be specified for use in your Stylesheet via the background image picker, or can be referenced directly in your CSS, or even created dynamically as a colour or gradient.
 
To add or manipulate your background via CSS, no further class or element is required - the default scope of the Stylesheet will style the background element. This is most commonly used for purposes such as adjusting tiling or scaling options, or defining non-image backgrounds.
 
For example, to create a gentle and non-intrusive coloured background:
background-image: linear-gradient(
    to bottom right,
    PaleGreen 5%,
    WhiteSmoke 50%,
    SkyBlue 85%,
    DeepSkyBlue 95%
);
 
 
Logo
A logo image can be specified for use in your Stylesheet via the logo image picker, or can be reference directly in your CSS.
 
To add or manipulate your logo via CSS, specifying styling against the #logo element (and optionally the #stylesheetLogo element to control the visibility inside the Designer). This is most commonly used for the purpose of controlling the size or background of the logo.
 
For example, to limit the size of your logo without adjusting the scaling (aspect ratio):
#page-logo {
    width: 300px;
}
 
 
Additional Classes
Additional classes can be specified against individual elements of Controls that offer a Styling tab, letting shared styling be defined for different uses of Fields that can then be centrally managed from the Stylesheet.
 
Any additional classes that have been defined can then be addressed in the Stylesheet CSS editor by adding a full-stop character (.) immediately before the specified class name. For example, if an additional class of optionalQuestion had been defined, then it could be controlled in the CSS editor by referencing .optionalQuestion
 
These additional classes can either be styled in isolation, or in combination with the Control or element styling definitions. For example:
.control-text-box .optionalQuestion {
    // Style any optionalQuestion field elements that are also Text Box Fields
}
 
 
Custom Validation Styling
It is possible to modify the appearance of Fields that fail Validation, with the default appearance simply being a red background being added to the input element of the Field.
.validation-failure {
    // This is the default styling for all Fields that have failed Validation
    background-color: #ff5555;
    &.table-fv {
        // Table Controls have additional styling, adding an outline
        background-color: rgba(#ff5555, 0.1);
        outline: 2px solid #ff5555;
    }
}
 
 

Examples

Optional Questions
Define an optionalQuestion additional class against the left-hand label element for all relevant Fields, and make it so that all of these fields are consistently styled with grey italic text:
.optionalQuestion {
    font-style: italic;
    color: #aaaaaa;
}
 
Alternatively, you could define the optionalQuestion class against multiple/all stylable elements of the relevant Fields (from the Example Stylesheet Structures article), and make it so that the left-hand label elements are styled with grey italic text, and the input elements are styled with a slight background tint. Note that in this case, the .optionalQuestion selector has to be placed directly in contact with the other elements without any spaces, so as to indicate that the requirement of combined selection rather than descendent selection:
.textlabel:not(input + label).optionalQuestion {
    font-style: italic;
    color: #aaaaaa;
}
input:not(div + input).optionalQuestion, textarea.optionalQuestion, select.optionalQuestion {
    background-color: #f8f8f8;
}
 
 
Button Styling
Define a common button style to make button elements green by default - but also define variants such as a red and blue style for btn-dangerous and btn-significant respectively by the use of additional classes. This is a more complex approach that allows easy extension on to multiple different styling by the use of parameterised SCSS Mixins and Includes, and colour scaling:
// This defines the "Mixin", which accepts a pair of $background and $text colour parameters to define the eventual button's colouration
@mixin button-def($background: #6aa84f, $text: #ffffff) {
    background-color: $background;
    border: 1px solid scale-color($background, $lightness: -40%); // Make the border a darker tint of the button's colour
    color: $text;
    font-weight: bold;
    font-size: 18px;
 
    &:hover {
        background-color: scale-color($background, $lightness: 40%); // Make the button lighten when hovered over
    }
}
 
// This then uses the mixin to apply the default style to all button elements, as well as buttons that we have specified additional classes for
.btn {
    @include button-def(); // Default green
    
    &-dangerous { // btn-dangerous additional class
         @include button-def($background: #cc0000); // Dark red
    }
   
    &-significant { // btn-significant additional class
        @include button-def($background: #3d85c6); // Mid blue
    }
}
 
 

Recommendations

Making use of variable definitions for your Stylesheets has three great benefits: it ensures that your Stylesheet has a consistent visual appearance, allows rapidly trying out changes such as updating font size or colour, and means that if you are regularly copying Workflows or Templates that you can then easily and consistently rebrand the resulting Workflow by changing only a few values.
 
The element styling approach is less intuitive, but allows far more brevity in the produced Stylesheet, and avoids over-granularity in redefining styling against many Controls that are visually and functionally similar.
 
If your styling doesn't appear to be being applied to certain elements, try temporarily applying the !important flag against those styling definitions. If the styling still isn't applied, then it suggests that your selector definitions aren't correctly constructed.
 
If a syntactic error is made in the CSS editor, it will display a red ribbon with the error message below. Most importantly, it will indicate either the line that caused the failure or the line immediately following it.