How to :: make CSS on your apps : complete tutorial

Before Starting

  • Do not abuse of CSS in Toucan Toco apps, change only the most necessary things (like bar colors for example).  Why? → Toucan’s design team are experts in dataviz and UX, let them make the good choices for you. → Toucan Toco gives you CSS tips to be able to customize your app, but we don’t guarantee the durability of the CSS in time.
  • Be careful, when you change the style of an element, it will change the style for all the elements in the app! (refer to the lower chapter to know how to custom only one chart).
  • When you add CSS for an element, check if it’s OK on desktop, mobile and tablet.
  • If recently something is weird or seems to be “broken” in a story, check before report a bug if it’s not your custom CSS that breaks it!

Basics of HTML & CSS

What are HTML,CSS and Javascript ?

A web page is like a house. HTML is the blueprint, CSS is the interior decorating scheme, and JavaScript is the electricals. The web browser is the builder.

In other words, HTML is the content and the structure, CSS is the appearance, what it looks like, and JavaScript is the dynamic behavior, it animate stuff on screen.

How to see html and css code in the browser?

Make a right click anywhere in the page, and click “Inspect”.

inspect

inspect

You should see this:

dev-tools

dev-tools

Take a look in more detail:

inspector

inspector

To select the element you want, click in the cursor icon, at the top left of the web inspector.

click

click

Then, click on the element you want to select.

Understand basic HTML

HTML element

In a HTML element, the start and the ending tag determine the tag type.

A HTML element can has attributes. The most common and used attribute is the class attribute.

An attributes permits to differentiate an element from an other.

element

element

element-tc

element-tc

HTML tree

The HTML is composed of HTML elements.

Each element has a parent (except the first element). An element can has several children. Elements with the same immediate parent are siblings.

parent-child html-tree-simple

Understand basic CSS selectors

css-selector css-selector-2 css-selector-3

How to select an element

element-tc

element-tc

In the HTML element above, if I want to select it with CSS, I will follow this steps :

check if the element has a class attribute. If so, use a dot (.) and his class name to select it. ex: .bar  If the element don’t has a class Use its type to select it, and find a parent that has a class (refer to cascading chapter). To select a child into a parent, add a space between them. ex: .bar-container rect

select-element-css

select-element-depending-on-label

select-element-depending-on-label

⚠️ When you apply a style to an HTML element, it would style all the element with the same name! ⚠️

Where to write CSS in Toucan Toco apps?

To write css in Toucan Toco :

  1. Go to dashboard
  2. Go to staging mode
  3. Click on “edit” button
  4. Click on “color scheme” button in the panel at the top of the screen
  5. You can write your styles in the “specific stylesheet” panel (cf. screenshot below)
color-scheme

color-scheme

CSS properties

Now, we will see how to declare css properties !

How to declare CSS properties

CSS property are declared between braces `{ }

.title { color: red; }

CSS properties contains key and value. In the above example, color is the key and red is the value.

The ‘key’ is what I’m going to change, and the ‘value’ is how I’m changing it. In our example, I’m coloring in red my title

You can create or modify multiple properties on the same element, use semicolon (;) to separate them.

.title { color: red; font-size: 14px; font-weight: bold}

Some properties work only with SVG elements or HTML elements. See the going further chapter for more info on HTML vs SVG

How to know quickly if an element is HTML or SVG type ?

Visually, you can’t, except if you know the name of the tags.

Exhaustive list of SVG tags in Toucan Toco:

  • <circle>
  • <g>
  • <line>
  • <path>
  • <polyline>
  • <rect>
  • <svg>
  • <text>

All other tags are HTML tags.

CSS properties for HTML tags

Proper ty Description Values
backgr ound-c olor Specifies the background color of an element color | transparent
color Sets the color of text color | transparent
conten t Used with the :before and :after pseudo-elements, to insert generated content normal | none | string | url
cursor Specifies the mouse cursor to be displayed when pointing over an element auto | not-allowed | pointer | and 15 more…
displa y Specifies how a certain HTML element should be displayed block | flex | none | and more…
font-s ize Specifies the font size of text value in px, em, rem or %
font-s tyle Specifies the font style for text normal | italic | oblique
font-w eight Specifies the weight of a font normal | bold | bolder | lighter | number between 100 (lighter) and 900 (bolder)
height Sets the height of an element auto | value in px, em, rem or %
letter -spaci ng Increases or decreases the space between characters in a text normal | value in px, em, rem or %
margin Sets all the margin properties in one declaration. Order: top right bottom left auto | values in px, em, rem or %
max-he ight Sets the maximum height of an element none | value in px, em, rem or %
max-wi dth Sets the maximum width of an element none | value in px, em, rem or %
min-he ight Sets the minimum height of an element 0 | value in px, em, rem or %
min-wi dth Sets the minimum width of an element 0 | value in px, em, rem or %
opacit y Sets the opacity level for an element value between 0.0 (fully transparent) and 1.0 (fully opaque)
paddin g Sets all the padding properties in one declaration. Order: top right bottom left auto | values in px, em, rem or %
text-a lign Specifies the horizontal alignment of text left | right | center | justify
visibi lity Specifies whether or not an element is visible hidden | visible | collapse
width Sets the width of an element auto | value in px, em, rem or %
word-w rap Allows long, unbreakable words to be broken and wrap to the next line normal | break-word
z-inde x Sets the stack order of a positioned element value

For more css properties, go here → https://www.w3schools.com/cssref/default.asp

CSS properties for SVG tags

Propert y Description Values
display The display attribute lets you control the rendering block | flex | none | and more…
fill Equivalent to color property color
font-si ze Specifies the font size of text value in px, em, rem or %
stroke The stroke attribute defines the color of the outline color
stroke- dasharr ay The stroke-dasharray attribute controls the pattern of dashes and gaps used to stroke paths. value
stroke- width The stroke-width attribute specifies the width of the outline on the current object. value
visibil ity The visibility attribute lets you control the visibility hidden | visible | collapse

Override an existing property

To override an existing property, you can use !important just after the CSS property.

An !important declaration provides a way to give a CSS value with higher priority than it naturally has.

.bar { fill: red!important; }

⚠️ !important is stronger than the CSS written in the config file (ex: for the heatmap, when we define squareHeight, yLabelWidth …)

Color all the bars/lines/circles in the app, depending on a specific label,serie or group

You can use this code to color all the bars/lines/bubbles in the app, depending on a specific label,serie or group.

@include colorChartsElementsByName("categorie-1", #96c4b9);

The first argument correspond to your label/serie/group and the second argument is the color.

⚠️ This code will color all the bars/lines/bubbles in your app with this label/serie/group.

Responsive design

Let’s see how to apply specifics style for mobile and tablet devices in Toucan product.

Phone

ex:

@include respond-to(phone) {
    .title {
        font-size: 14px;
    }
}

Tablet

ex:

@include respond-to(tablet) {
    .title {
        font-size: 14px;
    }
}

@include respond-to(phone) and @include respond-to(tablet) are custom shortcut that work only in Toucan Toco!

Cascading and nesting

Cascading

Cascading is a way to apply levels of specificity to your CSS styles.

It’s like the descendant selector, you can specify that you want to select a specific child into a specific parent.

cascading

cascading

Imagine I want to select the <span> into <div class="right-pane-container> into <div class="horizontal-barchart-container">.

I will write this code:

.horizontal-barchart-container .right-pane-container span {
    /*code here*/
}

Nesting

Alternatively, if you want to select several children into the same parent, you can do that:

.horizontal-barchart-container {
    .right-pane-container {
        /*code here*/
    }
    .chart-container {
        /*code here*/
    }
}

Add styles just for a chart

In Toucan, it’s possible to add styles just for a chart, and not all the app.

In order to do this, go in your front_config.cson file.

Step 1: front_config

I have a single chart

In the config object of the story, in chartOptions, add : style: 'my_custom_class_name' ex:

{
    level: 3
    title: 'My barchart'
    parent_id: 407
    chartOptions:
        chartType: 'barchart'
        style: 'with-colored-labels'
        #more properties
    id: 40701
}
I have a double chart (crossfilter/master-slave)

In the config object of the story, at the same level as chartType, add : style: 'my_custom_class_name'. ex:

{
    level: 3
    title: 'My barchart'
    parent_id: 407
    charts: [
        {
            chartType: 'linechart'
            style: 'secondary'
            #more properties
            id: 0
        }
        {
            chartType: 'leaderboardCenteredAverage'
            style: 'primary'
            #more properties
            id: 1
        }
    ]
    id: 32205
}
I have a tile/widget

In the config object of the story, at the same level as type, add : style: 'my_custom_class_name' ex:

{
    name: "My widget"
    type: 'line'
    style: 'with-dashed-line'
}
How it works

The property style in your config will add a class in the HTML, on the element <div class="chart-wrapper">.

custom-class

custom-class

So, all the elements that are descendants of .chart-wrapper.with-dashed-line will can be styled.

Step 2: color scheme page

In the color scheme page, you have to make cascading/nesting (cf. previous chapter).

Suppose we want to style the line, but only in this chart, we will make this:

.with-dashed-line .line {
    stroke-dasharray: 10;
}

I cascaded/nested .line into .with-dashed-line, so only this .line will be dashed.

Rendering

dashed

dashed

Quick method to test some styles in the web inspector

The quick method to test css styles is to write it in the element.style panel:

element-style

element-style

We can change the text color for example, and we see the change immediately!

But if we reload the page, these styles will disappear. It’s just to test temporarily.

Going further

CSS selectors

In CSS, selectors are patterns used to select the element(s) you want to style.

It’s a combination of an element selector and a value which identifies the web element within a web page.

There are five different selectors in CSS:

  • Type selector
  • Class selector .
  • Id selector #
  • Attribute selector [ ]
  • Universal selector *

Type selector

A type selector permits to select an HTML or SVG tag, for example : <div><span>, <p>, <text>, <path>, etc…

You can find an exhaustive tag list here :

To select elements with a specific tag, write the name of the tag. ex: span

Class selector

The class selector is used to select elements with a specific class attribute. ex: <div class="header-title"</div>

To select elements with a specific class, write a dot . character, followed by the name of the class. ex: .header-title

If an element has several class, ex: <div class="header-title main-title"</div> You can style the element with only one class, ex: .header-title Or with its two classes, ex: .header-title.main-title It’s the same, but if you use its two classes, don’t separate it with space or other characters, stick it.

ID selector

The id selector is used to select elements with a specific id attribute. ex: <div id="logo-brand"</div>

To select elements with a specific id, write a hash key #, followed by the name of the id. ex: #logo-brand

Attribute selector

The attribute selector is used to select elements with a specified attribute. ex: <rect data-serie="category-1">

To select elements with a specific attribute, wrap it with brackets [ ] characters. ex: [data-serie="category-1"]

If you want to select a tag|class|id with a specific attribute, it’s necessary to stick the tag|class|id with the attribute ex: rect[data-serie="category-1"].bar[data-serie="category-1"]

Universal selector

The universal selector is used to select all elements.

To select all elements, write just an asterisk * character. ex: *

It can also select all elements inside another element. ex: .right-pane-container *

⚠️ a CSS selector modify all the elements with the same tag/name. So if I modify an element with .header-title, all elements with the class “header-title” will be modified.

CSS combinators

A CSS selector can contain more than one selector. ex: .header-content .header-title

Between the selectors, we can include a combinator. ex: .header-content > .header-title

There are four different combinators in CSS:

  • descendant selector (space)
  • child selector >
  • adjacent sibling selector +
  • general sibling selector ~

Descendant Selector

The descendant selector matches all elements that are descendants of a specified element.

ex: .horizontal-barchart text

This will select all text tags contain into the class horizontal-barchart.

Child Selector

The child selector > selects all elements that are the immediate children of a specified element.

ex: .horizontal-barchart > text

This will select only the text tags that are immediate children of the class horizontal-barchart.

It’s convenient when you don’t want to modify other descendant with the same tag.

Adjacent Sibling Selector

The adjacent sibling selector + selects all elements that are the adjacent siblings of a specified element.

Sibling elements must have the same parent element, and “adjacent” means “immediately following”.

ex: chart-container + right-pane-container

General Sibling Selector

The general sibling selector ~ selects all elements that are siblings of a specified element.

ex: horizontal-barchart-value ~ horizontal-bar-complement

Pseudo-classes

A pseudo-class is basically a phantom state or specific characteristic of an element that can be targeted with CSS.

For example, it can be used to:

  • Style the first-child or last-child of an element

pseudo-classes are always preceded by a colon :.

:first-child, :last-child, :nth-child

Permit to style the first-child a parent element.

ex:

.group-metric-wrapper:first-child {
    background-color: #a0d1c5;
}

In the following example, we can see there are several identical elements in the same parent. The solution to select only the first child of the parent is to use :first-child pseudo-class.

select-child

select-child

In the same way, It’s possible to select the last-child with :last-child

For the second, third, fourth, fifth, etc…, you can use :nth-child(2):nth-child(3):nth-child(4):nth-child(5), etc…

Understand HTML Structure

In our example :

  • BODY has three immediate children : HEADER, CONTENT and MENU, but a lot of descendants (or children, but not immediate).
  • BODY is the immediate parent of HEADER, CONTENT and MENU.
  • HEADER, CONTENT and MENU have the same parent : BODY.
  • HEADER, CONTENT and MENU are the the immediate children of BODY.
  • HEADER, CONTENT and MENU are siblings.
  • CHART has several parents: CONTENT is the immediate parent, and BODY is a higher parent.
  • CHART is a descendant (or child, but not immediate) of BODY, and the immediate child of CONTENT.
htmh-tree

htmh-tree

Definitions

HTML

HTML is an abbreviation for Hyper Text Markup Language.

It’s used to structure text and multimedia documents.

CSS

CSS stands for Cascading Style Sheets.

CSS is used to define styles for web pages, including the design, layout and variations in display for different devices.

Javascript

Javascript is a programming language commonly used to create interactive effects within web browsers.

We will not see how to use javascript in this tutorial.

HTML element

An HTML element is an individual component of an HTML document or web page, once this has been parsed.

SVG element

Short for Scalable Vector Graphics, a vector graphics file format that enables two-dimensional images to be displayed

In contrast to JPEG and GIF images on the Web, which are bitmapped and always remain a specified size, SVG images are scalable to the size of the viewing window and will adjust in size and resolution according to the window.