Flourish layout

Adds a wrapper and sections to a Flourish template with a host of settings and functions.

How to install

npm install -s @flourish/layout

Add a layout object to your template state:

export var state = {
    layout: {},
    ...
}

Import @flourish/layout into your template.yml settings.

How to use

Initialise the layout (only once) outside any function with a layout settings object:

import initLayout from "@flourish/layout";
var layout = initLayout(state.layout);

This adds a main wrapper to the page with 5 named sections: header, controls, legend, primary and footer. The primary section is a a flexible container that adjusts in height to fill the available space after the contents of the other sections has been taken into account. The initLayout call also adds a hidden overlay div to the primary that can be used to display a message if, for example, a template won't work in an old browser.

The layout object has a number of methods:

layout.getDefaultPrimaryHeight()

Returns the height the primary would be if using the standard Flourish breakpoints (unless in fixed_height mode, in which case it returns the actual available height). This can be useful in templates that switch between using standard Flourish breakpoints and using the setHeight method (see below).

layout.getOuterHeight([el])

Returns the height of the named section, including padding. If el is missing, the function returns the height of the wrapper node, including padding.

layout.getOuterWidth([el])

Returns the width of the named section, including padding. If el is missing, the function returns the width of the wrapper node, including padding.

layout.getOverlay()

Returns the (hidden-by-default) overlay div node.

layout.getInnerHeight([el])

Returns the height of the named section, excluding padding. If el is missing, the function returns the height of the wrapper node, excluding padding.

layout.getInnerWidth([el])

Returns the width of the named section, excluding padding. If el is missing, the function returns the width of the wrapper node, excluding padding.

layout.getPrimaryHeight()

Returns the height available for content in the primary container.

layout.getPrimaryWidth()

Returns the width available for content in the primary container.

layout.getSection(el)

Returns the container node inside section el. This is useful, for example, for adding a legend block to the legend section in the Flourish draw method. (Adding directly to the section should be avoided as this can make a mess of padding.)

layout.getSidebar()

Returns the sidebar node.

layout.getWrapper()

Returns the main wrapper node.

layout.remToPx(rem)

Returns the pixels for a rem value. This is useful when you need to add rem values in SVG for example.

layout.setHeight(primary_height)

If primary_height is a number then calculates the total_height required to fit the primary at that height and all the other sections at their current height into the page without scrollbars and calls Flourish.setHeight(total_height). If primary_height equals null then calls Flourish.setHeight(null).

layout.setLegendPosition(pos)

Sets the legend position to be below or above the primary based on whether the string pos matches the string "below", ignoring leading and trailing whitsepace and case.

layout.showOverlay(show_overlay)

If show_overlay is truthy this will show the overlay container, if it is falsy it will hide it. If show_overlay is a (non-empty) string then it will be used as the content of the paragraph element contained within the overlay. If show_overlay is a truthy value that is not a string then default text advising the user to upgrade their browser will be displayed.

layout.update()

Updates fonts, section order, titles and the footer based on the current values of the layout settings object.