a set of shared methods that can be used throughout Datawrapper

Import single functions:

import purifyHtml from '@datawrapper/shared/purifyHtml';

Import entire package:

import shared from '@datawrapper/shared';
shared.purifyHtml();
shared.httpReq();

• __(key, scope) ⇒ string
• area(vertices) ⇒ number
• arrayToObject(o) ⇒ object
• autoTickFormat(column) ⇒ string
• autoTickFormatDate(range, precision) ⇒ string
• autoTickFormatNumber(range) ⇒ string
• clone(object) ⇒ *
• colorLightness(hexColor) ⇒ number
• columnFormatter(column, metadata, axis) ⇒ function
• columnNameToVariable(name) ⇒ string
• combinations(input) ⇒ Array.<array>
• dateColumnFormatter(column) ⇒ function
• defaultColors(theme) ⇒ *
• deleteJSON(url, callback) ⇒ Promise
• drawPattern(parameters)
• equalish(a, b) ⇒ boolean
• escapeHtml(unsafe) ⇒ string
• estimateTextWidth(text, fontSize) ⇒ number
• fetchJSON(url, method, credentials, body, callback) ⇒ Promise
• findConfigPath() ⇒ String
• formatNumber(value, options) ⇒ string
• get(object, key, _default) ⇒
• getJSON(url, credentials, callback) ⇒ Promise
• highlightTimer(action, delay) ⇒ object
• httpReq(path, options) ⇒ Promise
  • .delete()
  • .get()
  • .head()
  • .patch()
  • .post()
  • .put()
• initNumeralLocale(locale)
• isValidUrl(input) ⇒ boolean
• kMeans(values, numCluster) ⇒ array.<Array.<number>>
• loadScript(src, callback)
• loadStylesheet(src, callback)
• numberColumnFormatter(config) ⇒ function
• observeFonts(fontsJSON, typographyJSON) ⇒ Promise
• opts : object
• patchJSON(url, body, callback) ⇒ Promise
• postEvent(chartId) ⇒ function
• postJSON(url, body, callback) ⇒ Promise
• purifyHTML(input, allowed) ⇒ string
• putJSON(url, body, callback) ⇒ Promise
• requireConfig() ⇒ Object
• round(value, decimals) ⇒ number
• set(object, key, value) ⇒
• significantDimension(values, tolerance) ⇒ number
• smartRound(values, addPrecision, tolerance) ⇒
• tailLength(value) ⇒ number
• toFixed(value) ⇒ string
• trackEvent(category, category, category, category)
• trackPageView(loadTime)
• truncate(str, start, end) ⇒ string

translates a message key. translations are originally stored in a Google spreadsheet that we're pulling into Datawrapper using the scripts/update-translations script, which stores them as :locale.json files in the /locale folders (both in core as well as inside plugin folders)

for the client-side translation to work we are also storing the translations in the global window.dw.backend.__messages object. plugins that need client-side translations must set "svelte": true in their plugin.json

Returns: string - -- the translated text

Computes the area of a polygon

Returns: number - -- polygon area, might be negative

This function fixes an uglyness when working with PHP backends. in PHP, there is no distiction between arrays and objects, so PHP converts an empty object {} to a empty array []. When this empty array then ends up in client-side JS functions which might start to assign values to the array using arr.foo = "bar" which results in a data structure like this:

Example

console.log(arr);
[]
  foo: "bar"
  length: 0
  <prototype>: Array []

console.log(arrayToObject(arr));
Object { foo: "bar" }

Convenient wrapper around autoTickFormatNumber and autoTickFormatDate. Returns either a numeral.js or day.js format, depending on the column type.

Returns: string - -- a numeral|dayjs format string

auto-detects a nice default axis tick format for date columns based on the input range and precision

Returns: string - - day.js compatible format string

Example

import {autoTickFormatDate} from '@datawrapper/shared/autoTickFormat';
autoTickFormatDate([new Date(2000,0,1), new Date(2002,0,1)], 'quarter'); // 'YYYY|[Q]Q'

auto-detects a nice default axis tick format for numeric columns based on the input range

Returns: string - - numeral.js compatible format string

Example

import {autoTickFormatNumber} from '@datawrapper/shared/autoTickFormat';
autoTickFormatNumber([0,100]); // '0,0.[00]'
autoTickFormatNumber([0.2,0.7]); // '0,0.00[00]'

Clones an object

Returns: * - - the cloned thing

Returns the Lab lightness value of a given hexidecimal RGB color. Uses chroma-js to convert from Hex to Lab, but only adds a few hundreds bytes to your build.

To use this function, you have to manually install chroma-js using npm install chroma-js.

Returns: number - - the Lab lightness, between 0 (black) and 100 (white)

Example

import colorLightness from '@datawrapper/shared/colorLightness';
colorLightness('#ff3399') // 57.9

This function returns a formatting function based, given a column object, a metadata object and the axis column name.

converts a column name to a variable name that can be used in the custom column editor. variable names can't contain spaces and special characters and are also converted to lowercase.

Returns: string - -- variable name

Example

import columnNameToVariable from '@datawrapper/shared/columnNameToVariable';

columnNameToVariable('GDP (per cap.)') // gdp_per_cap

computes all combinations of input elements

Returns: Array.<array> - -- array of combinations

Example

// returns [['a','b'], ['a'], ['b']]
combinations(['a', 'b']);

Example

// returns [[1,2,3], [1,2], [1,3], [1], [2,3], [2], [3]]
combinations([1,2,3])

This function returns a date formatting function based on a dw column object. The implementation is backwards-compatible with our old Globalize-based date formatting, but uses dayjs under the hood.

defines colors for the various chart elements like axis text, gridlines, bar background etc. based on the theme background color, and some other optional theme parameters

Returns: * - -- object with color definitions

Example

// returns {"tickText":{"secondary":"#9d9d9d","primary":"#d9d9d9"},"series":"#f1f1f1","value":"#d9d9d9","axis":"#f1f1f1","gridline":"#707070","fallbackBaseColor":"#f1f1f1"}
defaultColors({"colors": {"background": "#333333"}});

Example

// returns {"tickText":{"secondary":"#ffffff","primary":"#ffffff"},"series":"#ffffff","value":"#fef2e4","axis":"#ffffff","gridline":"#fedeb5","fallbackBaseColor":"#ffffff"}
defaultColors({"colors": {"bgBlendRatios": {"gridline": 0.5,"tickText": {"primary": 0,"secondary": 0}},"chartContentBaseColor": "#ffffff","background": "#FCB716"}});

Deprecated

Download and parse a remote JSON endpoint via DELETE. credentials are included automatically Use httpReq or delete instead.

Example

import { deleteJSON } from '@datawrapper/shared/fetch';

deleteJSON('http://api.example.org/chart/123').then(() => {
    console.log('deleted!')
});

draws a configurable pattern into an svg pattern def, so that it can be used as a fill

returns true if two numeric values are close enough

Example

// returns true
equalish(0.333333, 1/3)

Example

// returns false
equalish(0.333, 1/3)

returns escaped HTML that can be used to display untrusted content

returns the estimated width of a given text in Roboto. this method has proven to be a good compromise between pixel-perfect but expensive text measuring methods using canvas or getClientBoundingRect and just multiplying the number of characters with a fixed width.

be warned that this is just a rough estimate of the text width. the character widths will vary from typeface to typeface and may be off quite a bit for some fonts (like monospace fonts).

Example

import estimateTextWidth from '@datawrapper/shared/estimateTextWidth';
// or import {estimateTextWidth} from '@datawrapper/shared';
const width = estimateTextWidth('my text', 12);

Deprecated

Download and parse a remote JSON document. Use httpReq instead

Example

import { fetchJSON } from '@datawrapper/shared/fetch';
fetchJSON('http://api.example.org', 'GET', 'include');

Function to find a Datawrapper config file (config.js). It looks in the current working directory and in /etc/datawrapper/. If no config is found, the process will exit with a non zero exit code.

It is possible to overwrite the config path with the env variable DW_CONFIG_PATH. Useful for tests!

This is a Node module, that will probably not work in a browser environment.

Example

const { findConfigPath } = require('@datawrapper/shared/node/findConfig')

const path = findConfigPath()
// -> /etc/datawrapper/config.js

special number formatting that can deal with microtypography and "prepend currencies" (e.g., −$1234.57)

Use initNumeralLocale to set a custom locale.

Returns: string - - the formatted number

Example

// returns '1234.57'
formatNumber(1234.567)

Example

// returns '−$1234.57'
formatNumber(-1234.567, { prepend: '$' })

Safely access object properties without throwing nasty cannot access X of undefined errors if a property along the way doesn't exist.

Returns: the value

Example

import get from '@datawrapper/shared/get';
const someObject = { key: { list: ['a', 'b', 'c']}};
get(someObject, 'key.list[2]') // returns 'c'
get(someObject, 'missing.key') // returns undefined
get(someObject, 'missing.key', false) // returns false

Deprecated

Download and parse a JSON document via GET. Use httpReq or get instead.

Example

import { getJSON } from '@datawrapper/shared/fetch';
// use it callback style
getJSON('http://api.example.org', 'include', function(data) {
    console.log(data);
});
// or promise-style
getJSON('http://api.example.org')
  .then(data => {
     console.log(data);
  });

A delayed highlight setter

Example

import {highlightTimer} from '@datawrapper/shared';
const myTimer = highlightTimer(value => {
    if (value) {
        selection.style('opacity', d => d === value ? 1 : 0.3);
    } else {
        selection.style('opacity', 1);
    }
});

lines.on('mouseenter', d => myTimer.set(d));
chart.on('mouseleave', myTimer.clear);

The response body is automatically parsed according to the response content type.

Returns: Promise - promise of parsed response body or raw response

Example

import httpReq from '@datawrapper/shared/httpReq';
 let res = await httpReq('/v3/charts', {
     method: 'post',
     payload: {
         title: 'My new chart'
     }
 });
 import { post } from '@datawrapper/shared/httpReq';
 res = await post('/v3/charts', {
     payload: {
         title: 'My new chart'
     }
 });
 // send raw csv
 await httpReq.put(`/v3/charts/${chartId}/data`, {
      body: csvData,
      headers: {
          'Content-Type': 'text/csv'
      }
  });

• httpReq(path, options) ⇒ Promise
  • .get()
  • .patch()
  • .put()
  • .post()
  • .head()
  • .delete()

Like httpReq but with fixed http method DELETE

See: httpReq

Like httpReq but with fixed http method GET

See: httpReq

Like httpReq but with fixed http method HEAD

See: httpReq

Like httpReq but with fixed http method PATCH

See: httpReq

Like httpReq but with fixed http method POST

See: httpReq

Like httpReq but with fixed http method PUT

See: httpReq

in order to use formatValue with custom locales and to avoid version conflicts with numeral, this method allows setting a locale.

checks if a given string is a valid URL

Performs one-dimensional k-means clustering on an array of numbers. Useful for finding n groups of "similar values".

Returns: array.<Array.<number>> - - array of clusters

Example

import kMeans from '@datawrapper/shared/kMeans';

const values = [1, 1.1, 1.2, 2.1, 3, 3.1, 3.2, 3.3, 7, 7.1, 10];
// returns [[1, 1.1, 1.2, 2.1], [3, 3.1, 3.2, 3.3], [7, 7.1, 10]]
kMeans(values, 3)

injects a <script> element to the page to load a new JS script

Example

import { loadScript } from '@datawrapper/shared/fetch';

loadScript('/static/js/library.js', () => {
    console.log('library is loaded');
})

injects a <link> element to the page to load a new stylesheet

Example

import { loadStylesheet } from '@datawrapper/shared/fetch';

loadStylesheet('/static/css/library.css', () => {
    console.log('library styles are loaded');
})

This function returns a number formatting function based on a column configuration object stored in metadata.data.column-format. The implementation is backwards-compatible with our old Globalize-based number formatting, but uses numeral under the hood.

Function that returns a promise, that resolves when all fonts, specified in fontsJSON and typographyJSON have been loaded.

Properties

Deprecated

Example

import { patchJSON } from '@datawrapper/shared/fetch';

patchJSON('http://api.example.org', JSON.stringify({
   query: 'foo',
   page: 12
}));

Use this function to post event messages out of Datawrapper iframe embeds to the parent website.

Example

import genPostEvent from '@datawrapper/shared/postEvent';
const postEvent = genPostEvent(chart.get('id'));
postEvent('bar:hover', {value: 123});

Deprecated

Download and parse a remote JSON endpoint via POST. credentials are included automatically. Use httpReq or post instead.

Example

import { postJSON } from '@datawrapper/shared/fetch';

postJSON('http://api.example.org', JSON.stringify({
   query: 'foo',
   page: 12
}));

Remove all non-whitelisted html tags from the given string

Returns: string - - the cleaned html output

Deprecated

Download and parse a remote JSON endpoint via PUT. credentials are included automatically Use httpReq or put instead.

Example

import { putJSON } from '@datawrapper/shared/fetch';

putJSON('http://api.example.org', JSON.stringify({
   query: 'foo',
   page: 12
}));

Tiny wrapper around findConfigPath that directly requires the found config.

Example

const { requireConfig } = require('@datawrapper/shared/node/findConfig')

const config = requireConfig()

rounds a value to a certain number of decimals

Returns: number - - rounded value

Example

import round from '@datawrapper/shared/round';
round(1.2345); // 1
round(1.2345, 2); // 1.23
round(12345, -2); // 12300

safely set object properties without throwing nasty cannot access X of undefined errors if a property along the way doesn't exist.

Returns: the value

computes the significant dimension for a list of numbers That's the number of decimals to which we can round the numbers without loosing information

Returns: number - - number of significant dimensions (= the number of decimals)

Example

import {significantDimension} from '@datawrapper/shared/significantDimension';
significantDimension([0,10,20,30]); // -1

rounds an array of numbers to the least number of decimals without loosing any information due to the rounding

Returns: the rounded values

Example

import {smartRound} from '@datawrapper/shared/smartRound';
smartRound([9, 10.5714, 12.1428, 13.7142]); // [9, 11, 12, 14]
smartRound([9, 10.5714, 12.1428, 12.4142]); // [9, 10.6, 12.1, 12.4]

returns the length of the "tail" of a number, meaning the number of meaningful decimal places

Example

// returns 3
tailLength(3.123)

Example

// returns 2
tailLength(3.12999999)

Automatically converts a numeric value to a string. this is better than the default number to string conversion in JS which sometimes produces ugly strings like "3.999999998"

Example

import toFixed from '@datawrapper/shared/toFixed';
// returns '3.1'
toFixed(3.100001)

tracks a custom event in Matomo

tracks a custom page view in Matomo. Useful for single page apps in Datawrapper, such as the locator maps UI. The page title and URL are automatically detected using the window object.

Shorten a string by removing characters from the middle

Example

import truncate from '@datawrapper/shared/truncate';
// returns 'This is a…tring'
truncate('This is a very very long string')