❤
npm
Sign UpSign In

@datawrapper/shared

1.13.0-1 • Public • Published

@datawrapper/shared

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();

API reference

__(key, scope) ⇒ 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

Param Type Default Description
key string - the key to be translated, e.g. "signup / hed"
scope string "core" - the translation scope, e.g. "core" or a plugin name

area(vertices) ⇒ number

Computes the area of a polygon

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

Param Type Description
vertices Array.<array> - polygon vertices as [[x,y], [x,y], ...] array

arrayToObject(o) ⇒ object

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:

Param Type Description
o array the input

Example

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

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

autoTickFormat(column) ⇒ string

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

Param Type Description
column object - dw.column instance that is displayed on the axis

autoTickFormatDate(range, precision) ⇒ 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

| Param | Type | Description | | --------- | ------------------- | ------------------------------ | ------- | ----- | ---- | --- | ---- | | range | array | [min, max] of the data | | precision | string | the input data precision (year | quarter | month | week | day | ...) |

Example

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

autoTickFormatNumber(range) ⇒ string

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

Returns: string - - numeral.js compatible format string

Param Type Description
range array [min, max] of the data

Example

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

clone(object) ⇒ *

Clones an object

Returns: * - - the cloned thing

Param Type Description
object * the thing that should be cloned

colorLightness(hexColor) ⇒ number

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)

Param Type Description
hexColor string the RGB color as hexadecimal string, e.g. "#330066"

Example

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

columnFormatter(numeral, column, metadata, axis) ⇒ function

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

Param Type Description
numeral object Numeral.js instance
column object the date column object
metadata object the full metadata object
axis string the column name of the axis

columnNameToVariable(name) ⇒ string

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

Param Type Description
name string - name of the column

Example

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

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

combinations(input) ⇒ Array.<array>

computes all combinations of input elements

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

Param Type Description
input Array.<array> - array of input objects, could be numbers, strings, etc

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]);

dateColumnFormatter(column) ⇒ function

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.

Param Type Description
column object the date column object

decodeHtml(input) ⇒ string

Removes all html tags and decodes html entities like  

Param Type
input string

defaultColors(theme) ⇒ *

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 and blendColor function

Param Type Description
theme * - theme data for a chart

Example

// returns {"tickText":{"secondary":"#9d9d9d","primary":"#d9d9d9"},"series":"#f1f1f1","value":"#d9d9d9","axis":"#f1f1f1","gridline":"#707070","fallbackBaseColor":"#f1f1f1", blendColor: function}
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'
    }
});

defaultOverlayTitle(vis, colName) ⇒ string

returns the overlays column title

Param Type
vis object
colName string

deleteJSON(url, callback) ⇒ Promise

Deprecated

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

Param Type
url string
callback function

Example

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

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

drawPattern(parameters)

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

Param Type Description
parameters * - style parameters for the pattern

equalish(a, b) ⇒ boolean

returns true if two numeric values are close enough

Param Type
a number
b number

Example

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

Example

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

escapeHtml(unsafe) ⇒ string

returns escaped HTML that can be used to display untrusted content

Param Type
unsafe string

estimateTextWidth(text, fontSize) ⇒ number

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).

Param Type Description
text string the text to measure
fontSize number the output font size (optional, default is 14)

Example

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

fetchJSON(url, method, credentials, body, callback) ⇒ Promise

Deprecated

Download and parse a remote JSON document. Use httpReq instead

Param Type Description
url string
method string HTTP method, either GET, POST or PUT
credentials string | undefined set to "include" if cookies should be passed along CORS requests
body string
callback function

Example

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

formatNumber(numeral, value, options) ⇒ string

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

Returns: string - - the formatted number

Param Type Description
numeral object Numeral.js instance
value number the number to format
options object options, see below
options.format string numeral.js compatible number format
options.prepend string string to prepend to number
options.append string string to append to number
options.minusChar string custom character to use for minus
options.multiply number multiply number before applying format

Example

// returns '1234.57'
formatNumber(numeral, 1234.567);

Example

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

get(object, key, _default) ⇒

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

Param Type Description
object the object which properties you want to acccess
key String | Array.<String> path to the property as a dot-separated string or array of strings
_default * the fallback value to be returned if key doesn't exist

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

getJSON(url, credentials, callback) ⇒ Promise

Deprecated

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

Param Type Description
url string
credentials string | undefined optional, set to undefined to disable credentials
callback function

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);
});

highlightTimer(action, delay) ⇒ object

A delayed highlight setter

Param Type Description
action function the highlight action callback
delay int how long something needs to be highlighted before the highlight triggers (in milliseconds)

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);

httpReq(path, options) ⇒ Promise

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

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

Param Type Description
path string the url path that gets appended to baseUrl
options.body object raw body to be send with req
options.payload object raw JSON payload to be send with req (will overwrite options.body)
options.raw boolean disable parsing of response body, returns raw response
options.baseUrl string base for url, defaults to dw api domain
options * see documentation for window.fetch for additional options

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.delete()

Like httpReq but with fixed http method DELETE

See: httpReq

httpReq.get()

Like httpReq but with fixed http method GET

See: httpReq

httpReq.head()

Like httpReq but with fixed http method HEAD

See: httpReq

httpReq.patch()

Like httpReq but with fixed http method PATCH

See: httpReq

httpReq.post()

Like httpReq but with fixed http method POST

See: httpReq

httpReq.put()

Like httpReq but with fixed http method PUT

See: httpReq

isValidUrl(input) ⇒ boolean

checks if a given string is a valid URL

Param Type
input string

kMeans(values, numCluster) ⇒ array.<Array.<number>>

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

Param Type Description
values Array.<number> sorted array of numbers
numCluster number the desired cluster count

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);

loadScript(src, callback)

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

Param Type
src string
callback function

Example

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

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

loadStylesheet(src, callback)

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

Param Type
src string | opts
callback function

Example

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

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

normalizeAlphaNumKey(key) ⇒ string

normalize an alphanumerical key for less-strict matching (e.g. in maps)

Returns: string - - normalized key

Param Type Description
key string alphanumerical key

normalizeNumKey(key) ⇒ number

normalize a numerical key for less-strict matching (e.g. in maps)

Returns: number - - normalized key

Param Type Description
key string | number numerical key

numberColumnFormatter(numeral, config) ⇒ function

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.

Param Type Description
numeral object Numeral.js instance
config object the column configuration from metadata

observeFonts(fontsJSON, typographyJSON) ⇒ Promise

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

Param Type
fontsJSON Object | Array
typographyJSON Object

opts : object

Properties

Name Type Description
src string stylesheet URL to load
parentElement DOMElement DOM element to append style tag to

patchJSON(url, body, callback) ⇒ Promise

Deprecated

Param Type
url string
body string
callback function

Example

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

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

postEvent(chartId) ⇒ function

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

Param Type Description
chartId string the chart id each message should be signed with

Example

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

postJSON(url, body, callback) ⇒ Promise

Deprecated

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

Param Type
url string
body string
callback function

Example

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

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

purifyHtml(input, allowed) ⇒ string

Remove all non-whitelisted html tags from the given string

Returns: string - - the cleaned html output

Param Type Description
input string dirty html input
allowed string list of allowed tags, defaults to <a><b><br><br/><i><strong><sup><sub><strike><u><em><tt>

putJSON(url, body, callback) ⇒ Promise

Deprecated

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

Param Type
url string
body string
callback function

Example

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

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

round(value, decimals) ⇒ number

rounds a value to a certain number of decimals

Returns: number - - rounded value

Param Type Description
value number the value to be rounded
decimals number the number of decimals

Example

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

set(object, key, value) ⇒

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

Param Type Description
object the object which properties you want to acccess
key String | Array.<String> path to the property as a dot-separated string or array of strings
value * the value to be set

significantDimension(values, tolerance) ⇒ number

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)

Param Type Description
values Array.<number> list of input numbers
tolerance number percent of input values that we allow to "collide"

Example

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

smartRound(values, addPrecision, tolerance) ⇒

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

Returns: the rounded values

Param Type Description
values array the numbers to be rounded
addPrecision number force more precision (=numbers of decimals) to the rounding
tolerance number the percent of uniq input values that we can tolerate to lose after rounding

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]

tailLength(value) ⇒ number

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

Param Type
value number

Example

// returns 3
tailLength(3.123);

Example

// returns 2
tailLength(3.12999999);

toFixed(value) ⇒ string

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"

Param Type
value number

Example

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

trackEvent(category, category, category, category)

tracks a custom event in Matomo

Param Type Description
category string the event category
category string the event action
category string the event name
category string | number the event value, optional

trackPageView(loadTime)

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.

Param Type Description
loadTime number optional page load time, has to be measured manually

truncate(str, start, end) ⇒ string

Shorten a string by removing characters from the middle

Param Type Description
str string
start number characters to keep at start of string
end number characters to keep at end off string

Example

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

Dependents (11)

Package Sidebar

Install

npm i @datawrapper/shared

Repository

github.com/datawrapper/shared

Homepage

github.com/datawrapper/shared#readme

Weekly Downloads

6

Version

1.13.0-1

License

MIT

Unpacked Size

389 kB

Total Files

258

Last publish

Collaborators

  • gustavkneustadt
  • linusaarnio
  • julian_freyberg
  • alex.datawrapper
  • lucguillemot
  • sarcevic
  • jack_g
  • elliot_b
  • pabueco
  • msigwart
  • gka
  • ilokhov
  • davidkokkelink
  • dw-deploy-bot
  • elanals
  • lisacrost
  • exo_dw
  • anna-dw
  • davidw-dw
  • danieladw
  • margauxbourdon
Try on RunKit
Report malware