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.

layout.awaitFonts(callback, duration, font_weights)

Starts loading fonts and executes a function callback when all fonts have loaded (using the document.fonts.ready event listener). If an optional array of font_weights is provided invisible sample text will be appended for each font weight and then removed when a loading event which incudes that weight occurs. This stops the callback being triggered unnessecarily for each weight of a font. For example, a popup which includes a bold version of a font would trigger a font loading event if a template only contained fonts with a normal weight otherwise. font_weights defaults to ["normal", "bold"] (numeric values are also accepted). If all fonts are not loaded by the given duration (ms, which defaults to 500) then the callback is executed early. The callback is executed again when the fonts finally finish loading. Once the document.fonts.ready event has been triggered, a new event listener is setup to listen for further font loading events i.e. a new font is selected in the editor. This was introduced in v5.4. To update templates using previous versions of the module (with @flourish/font-watcher) to v5.4 and above follow the v5.4 migration guide.

layout.prepareScreenshotSVG()

Creates a temporary SVG containing header and footer text that will be included in the SVG export. Make sure to call this function in the template's screenshot function.

layout.clearScreenshotSVG()

Removes the temporary SVG created by layout.prepareScreenshotSVG()