menu   UA Europe - Training & Consulting
UA Europe - Training & Consulting
UA Europe - Training & Consulting

Specialists in
User Assistance
technology

Using CSS variables in MadCap Flare 2019

Published in ISTC Communicator, Autumn 2019.

If you are responsible for a Flare project, then you probably create and edit CSS code. Whether you are using Flare's own Stylesheet Editor or a text editor such as NotePad++, you might have been frustrated by having to re-select or re-type the same colour values within multiple styles. This seems counter to Flare's philosophy of single-sourcing, and increases the risk of errors, particularly if you are working with hexadecimal colours. Lack of support for variables has, until a couple of years or so ago, been a weakness of CSS, and some developers have turned to CSS preprocessors such as Sass or Less to provide this functionality.

However, in December 2015 the W3C's candidate recommendation for a new CSS module called CSS Custom Properties for Cascading Variables formally laid out how variables should work in CSS. This recommendation has now been implemented by the current versions of all the major browsers (with the exception of Internet Explorer), and earlier this year MadCap added support for CSS variables within its 2019 release of Flare. This article explains how they might help you, and how to go about using them.

How CSS variables can help

I'm sure you're familiar with the situation of being given a standard colour value by your marketing department to use for a range of elements (such as headings and borders) within your pages. You've probably needed to repeat this colour value in multiple declarations throughout your stylesheet, with the consequent risks of introducing typos or of missing one of the occurrences in the case of the colour needing to be updated.

This is where CSS variables come in: the idea is that you store the colour value as a variable, and then use the variable name in declarations where you would previously have included the value. As a result, if the value needs to be changed, you only have to update it in one place. Although CSS variables are probably most useful for colours, you can in fact use them to store any values including size (in units such as px, pt, or em), font-family, or image URL (for example: url('../images/Alert.png')).

As well as being able to define a value once and re-use it repeatedly, CSS variables have other benefits:

  • You can use semantic identifiers. For example: --MainHeadingColour is probably more meaningful to you than a hexadecimal colour value.
  • Unlike Sass or Less variables, CSS custom properties can be defined dynamically by JavaScript. This could be useful for special effects.

The syntax of CSS variables

Variable names must always start with a double-dash --. You define a CSS variable in your stylesheet using a declaration of the form shown by this example:

:root
{
    --main-company-colour: # bed420;
}

The :root pseudo class refers to the highest-level 'parent' element (the html element in your Flare topics), which means that the variable can be used by any element within the topic (h1, h2, p, li, etc.). If, for any reason, you want to define a variable for a specific element or selector, then you can do so using a declaration of the following form:

h1
{
    --heading-colour: #25282e;
}

In this case, the --heading-colour variable can be used only by the h1 element, or classes of the h1 element. Given that the main benefit of CSS variables is that they can be defined once and then used in multiple styles, I don't believe you would normally want to restrict the scope of a CSS variable in this way.

Having defined a variable, you can then use it as a value within a style declaration by inserting var(--variablename).

For example:

h1.Title
{
    color: var(--main-company-colour);
}

Using CSS custom properties in Flare 2018 and earlier

CSS variables have been supported in most of the major browsers for two or more years, and you could actually have used them with Flare 2018 or earlier by using a text editor to write the required code into your stylesheet. However, there would have been a couple of problems:

  • Flare's own CSS Editor would have subsequently refused to open the stylesheet, and would have displayed the error shown here:

    Screenshot showing Flare 2018 error message

  • Even if you had worked around this issue by moving the code for your variable definitions into a separate linked stylesheet, Flare's CSS parser would still have displayed errors within the Messages window every time you had opened a topic.

If you had ignored these errors, then the final HTML5 output from Flare would have included the CSS variable correctly and been fine. But the authoring experience within Flare would have been compromised.

Top of page

What's new in Flare 2019

Flare now understands CSS variables and the code is no longer treated as invalid. In addition, Flare's current Stylesheet Editor has additional controls for adding new CSS variables and for inserting a CSS variable in any location where a value is required.

Defining variables in Flare

If you are comfortable working with CSS code, you can define and insert your CSS variables in a text editor by using the syntax described above. If you prefer to use Flare's Stylesheet Editor, then you can define a new CSS variable by selecting Add New CSS Variable from the new CSS Variable control on the Stylesheet Editor toolbar.

Screenshot showing how to add new CSS Variable

Then you enter the required details for the variable using the dialog shown below. Note that you don't need to type the two dashes at the beginning of the variable name — Flare will include them for you automatically.

Screenshot showing Add New CSS Variable dialog box

Using variables as values in styles

Using Flare's Stylesheet Editor, you can insert a CSS variable in any field that requires a value. With your cursor in the field, select Insert CSS Variable from the CSS Variable control (see screenshot below). Then you can select the required variable from a drop-down list.

Screenshot showing how to insert a CSS Variable

There is one potential pitfall to watch out for: if you insert a CSS variable within a field that contains multiple values, then any values that were already in the field are removed. For example, if border-bottom was already set to dashed 3px #000000 (as shown in the first screenshot below) then inserting a new colour as a variable would result in the other two properties being lost (as shown in the second screenshot below). The workaround is to type the required code for the variable, in this example: var(--StdGreen), directly into the field.

Screenshot showing Border-bottom properties

 

Screenshot showing Border-bottom properties lost

Browser support for CSS variables

CSS Variables are supported by the current versions of all the major browsers, both desktop and mobile. However, they are not supported by any version of Internet Explorer. If you have users that access your content using Internet Explorer, then you can still use CSS Variables in your Flare projects. However, you will need to select an Advanced option in your HTML5 Target that replaces CSS variables with standard values in the stylesheets that are generated in the output.

Screenshot showing Resolve CSS variables option

Summary

CSS variables add functionality which you can use to ensure consistency in your Flare projects.

Further reading

CSS Custom Properties for Cascading Variables Module Level 1. W3C. 3 December 2015:
w3.org/TR/css-variables-1/

Introducing CSS Custom Properties (Variables) (Backticks & Tildes):
https://medium.com/backticks-tildes/introducing-css-customproperties-variables-fabe2dc697c0

CSS Variables: Why Should You Care? (Rob Dodson):
https://developers.google.com/web/updates/2016/02/css-variables-why-should-you-care

Demo of how custom properties can be changed dynamically using JavaScript:
https://googlechrome.github.io/samples/css-custom-properties

Sass Variables:
https://sass-lang.com/documentation/variables

Less Variables:
http://lesscss.org

 

 

 

Horizontal line

Training and Consulting in MadCap Flare

UA Europe provides specialist consulting and training (either face-to-face or via the Web) in MadCap Flare.

 

Top of page