UNPKG

13.4 kB Markdown View Raw
1# d3plus-common
2
3[![NPM Release](http://img.shields.io/npm/v/d3plus-common.svg?style=flat)](https://www.npmjs.org/package/d3plus-common) [![Build Status](https://travis-ci.org/d3plus/d3plus-common.svg?branch=master)](https://travis-ci.org/d3plus/d3plus-common) [![Dependency Status](http://img.shields.io/david/d3plus/d3plus-common.svg?style=flat)](https://david-dm.org/d3plus/d3plus-common) [![Gitter](https://img.shields.io/badge/-chat_on_gitter-brightgreen.svg?style=flat&logo=gitter-white)](https://gitter.im/d3plus/) [![1.0 progress](https://img.shields.io/badge/1.0_progress-100%25-brightgreen.svg?style=flat)](https://github.com/d3plus/d3plus-common/projects/1)
4
5Common functions and methods used across D3plus modules.
6
7## Installing
8
9If you use NPM, run `npm install d3plus-common --save`. Otherwise, download the [latest release](https://github.com/d3plus/d3plus-common/releases/latest). The released bundle supports AMD, CommonJS, and vanilla environments. You can also load directly from [d3plus.org](https://d3plus.org):
10
11```html
12<script src="https://d3plus.org/js/d3plus-common.v0.6.full.min.js"></script>
13```
14
15
16## API Reference
17
18#####
19* [BaseClass](#BaseClass) - An abstract class that contains some global methods and functionality.
20
21#####
22* [accessor](#accessor) - Wraps an object key in a simple accessor function.
23* [assign](#assign) - A deeply recursive version of `Object.assign`.
24* [attrize](#attrize) - Applies each key/value in an object as an attr.
25* [closest](#closest) - Finds the closest numeric value in an array.
26* [configPrep](#configPrep) - Preps a config object for d3plus data, and optionally bubbles up a specific nested type. When using this function, you must bind a d3plus class' `this` context.
27* [constant](#constant) - Wraps non-function variables in a simple return function.
28* [elem](#elem) - Manages the enter/update/exit pattern for a single DOM element.
29* [isObject](#isObject) - Detects if a variable is a javascript Object.
30* [merge](#merge) - Combines an Array of Objects together and returns a new Object.
31* [parseSides](#parseSides) - Converts a string of directional CSS shorthand values into an object with the values expanded.
32* [prefix](#prefix) - Returns the appropriate CSS vendor prefix, given the current browser.
33* [stylize](#stylize) - Applies each key/value in an object as a style.
34* [unique](#unique) - ES5 implementation to reduce an Array of values to unique instances.
35* [uuid](#uuid) - Returns a unique identifier.
36
37#####
38* [RESET](#RESET) - String constant used to reset an individual config property.
39
40---
41
42<a name="BaseClass"></a>
43#### **BaseClass** [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L46)
44
45
46This is a global class.
47
48
49* [BaseClass](#BaseClass)
50 * [.config([*value*])](#BaseClass.config) ↩︎
51 * [.locale([*value*])](#BaseClass.locale) ↩︎
52 * [.on([*typenames*], [*listener*])](#BaseClass.on) ↩︎
53 * [.translate([*value*])](#BaseClass.translate) ↩︎
54
55
56<a name="BaseClass.config" href="#BaseClass.config">#</a> BaseClass.**config**([*value*]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L73)
57
58If *value* is specified, sets the methods that correspond to the key/value pairs and returns this class. If *value* is not specified, returns the current configuration.
59
60
61This is a static method of [<code>BaseClass</code>](#BaseClass), and is chainable with other methods of this Class.
62
63
64<a name="BaseClass.locale" href="#BaseClass.locale">#</a> BaseClass.**locale**([*value*]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L128)
65
66Sets the locale used for all text and number formatting. This method supports the locales defined in [d3plus-format](https://github.com/d3plus/d3plus-format/blob/master/src/locale.js). The locale can be defined as a complex Object (like in d3plus-format), a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale from d3plus-format.
67
68
69This is a static method of [<code>BaseClass</code>](#BaseClass), and is chainable with other methods of this Class.
70
71
72```js
73{
74 separator: "",
75 suffixes: ["y", "z", "a", "f", "p", "n", "µ", "m", "", "k", "M", "B", "t", "q", "Q", "Z", "Y"],
76 grouping: [3],
77 delimiters: {
78 thousands: ",",
79 decimal: "."
80 },
81 currency: ["$", ""]
82 }
83```
84
85
86<a name="BaseClass.on" href="#BaseClass.on">#</a> BaseClass.**on**([*typenames*], [*listener*]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L147)
87
88Adds or removes a *listener* to each object for the specified event *typenames*. If a *listener* is not specified, returns the currently assigned listener for the specified event *typename*. Mirrors the core [d3-selection](https://github.com/d3/d3-selection#selection_on) behavior.
89
90
91This is a static method of [<code>BaseClass</code>](#BaseClass), and is chainable with other methods of this Class.
92
93| Param | Type |
94| --- | --- |
95| [*typenames*] | <code>String</code> |
96| [*listener*] | <code>function</code> |
97
98By default, listeners apply globally to all objects, however, passing a namespace with the class name gives control over specific elements:
99
100```js
101new Plot
102 .on("click.Shape", function(d) {
103 console.log("data for shape clicked:", d);
104 })
105 .on("click.Legend", function(d) {
106 console.log("data for legend clicked:", d);
107 })
108```
109
110
111<a name="BaseClass.translate" href="#BaseClass.translate">#</a> BaseClass.**translate**([*value*]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L161)
112
113Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.
114
115
116This is a static method of [<code>BaseClass</code>](#BaseClass), and is chainable with other methods of this Class.
117For example, if we wanted to only change the string &quot;Back&quot; and allow all other string to return in English:
118
119```js
120.translate(function(d) {
121 return d === "Back" ? "Get outta here" : d;
122})
123```
124
125---
126
127<a name="accessor"></a>
128#### d3plus.**accessor**(key, [def]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/accessor.js#L1)
129
130Wraps an object key in a simple accessor function.
131
132
133This is a global function.
134
135| Param | Type | Description |
136| --- | --- | --- |
137| key | <code>String</code> | The key to be returned from each Object passed to the function. |
138| [def] | <code>\*</code> | A default value to be returned if the key is not present. |
139
140this
141
142```js
143accessor("id");
144
145```
146returns this
147
148```js
149function(d) {
150 return d["id"];
151}
152```
153
154---
155
156<a name="assign"></a>
157#### d3plus.**assign**(...objects) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/assign.js#L14)
158
159A deeply recursive version of `Object.assign`.
160
161
162This is a global function.
163this
164
165```js
166assign({id: "foo", deep: {group: "A"}}, {id: "bar", deep: {value: 20}}));
167
168```
169returns this
170
171```js
172{id: "bar", deep: {group: "A", value: 20}}
173```
174
175---
176
177<a name="attrize"></a>
178#### d3plus.**attrize**(elem, attrs) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/attrize.js#L1)
179
180Applies each key/value in an object as an attr.
181
182
183This is a global function.
184
185| Param | Type | Description |
186| --- | --- | --- |
187| elem | <code>D3selection</code> | The D3 element to apply the styles to. |
188| attrs | <code>Object</code> | An object of key/value attr pairs. |
189
190
191---
192
193<a name="closest"></a>
194#### d3plus.**closest**(n, arr) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/closest.js#L1)
195
196Finds the closest numeric value in an array.
197
198
199This is a global function.
200
201| Param | Type | Description |
202| --- | --- | --- |
203| n | <code>Number</code> | The number value to use when searching the array. |
204| arr | <code>Array</code> | The array of values to test against. |
205
206
207---
208
209<a name="configPrep"></a>
210#### d3plus.**configPrep**([config], [type], [nest]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/configPrep.js#L1)
211
212Preps a config object for d3plus data, and optionally bubbles up a specific nested type. When using this function, you must bind a d3plus class' `this` context.
213
214
215This is a global function.
216
217| Param | Type | Default | Description |
218| --- | --- | --- | --- |
219| [config] | <code>Object</code> | <code>this._shapeConfig</code> | The configuration object to parse. |
220| [type] | <code>String</code> | <code>&quot;shape&quot;</code> | The event classifier to user for "on" events. For example, the default event type of "shape" will apply all events in the "on" config object with that key, like "click.shape" and "mouseleave.shape", in addition to any gloval events like "click" and "mouseleave". |
221| [nest] | <code>String</code> | | An optional nested key to bubble up to the parent config level. |
222
223
224---
225
226<a name="constant"></a>
227#### d3plus.**constant**(value) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/constant.js#L1)
228
229Wraps non-function variables in a simple return function.
230
231
232This is a global function.
233this
234
235```js
236constant(42);
237
238```
239returns this
240
241```js
242function() {
243 return 42;
244}
245```
246
247---
248
249<a name="elem"></a>
250#### d3plus.**elem**(selector, params) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/elem.js#L6)
251
252Manages the enter/update/exit pattern for a single DOM element.
253
254
255This is a global function.
256
257| Param | Type | Default | Description |
258| --- | --- | --- | --- |
259| selector | <code>String</code> | | A D3 selector, which must include the tagname and a class and/or ID. |
260| params | <code>Object</code> | | Additional parameters. |
261| [params.condition] | <code>Boolean</code> | <code>true</code> | Whether or not the element should be rendered (or removed). |
262| [params.enter] | <code>Object</code> | <code>{}</code> | A collection of key/value pairs that map to attributes to be given on enter. |
263| [params.exit] | <code>Object</code> | <code>{}</code> | A collection of key/value pairs that map to attributes to be given on exit. |
264| [params.parent] | <code>D3Selection</code> | <code>d3.select(&quot;body&quot;)</code> | The parent element for this new element to be appended to. |
265| [params.transition] | <code>D3Transition</code> | <code>d3.transition().duration(0)</code> | The transition to use when animated the different life cycle stages. |
266| [params.update] | <code>Object</code> | <code>{}</code> | A collection of key/value pairs that map to attributes to be given on update. |
267
268
269---
270
271<a name="isObject"></a>
272#### d3plus.**isObject**(item) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/isObject.js#L1)
273
274Detects if a variable is a javascript Object.
275
276
277This is a global function.
278
279---
280
281<a name="merge"></a>
282#### d3plus.**merge**(objects, aggs) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/merge.js#L5)
283
284Combines an Array of Objects together and returns a new Object.
285
286
287This is a global function.
288
289| Param | Type | Description |
290| --- | --- | --- |
291| objects | <code>Array</code> | The Array of objects to be merged together. |
292| aggs | <code>Object</code> | An object containing specific aggregation methods (functions) for each key type. By default, numbers are summed and strings are returned as an array of unique values. |
293
294this
295
296```js
297merge([
298 {id: "foo", group: "A", value: 10, links: [1, 2]},
299 {id: "bar", group: "A", value: 20, links: [1, 3]}
300]);
301
302```
303returns this
304
305```js
306{id: ["bar", "foo"], group: "A", value: 30, links: [1, 2, 3]}
307```
308
309---
310
311<a name="parseSides"></a>
312#### d3plus.**parseSides**(sides) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/parseSides.js#L1)
313
314Converts a string of directional CSS shorthand values into an object with the values expanded.
315
316
317This is a global function.
318
319---
320
321<a name="prefix"></a>
322#### d3plus.**prefix**() [<>](https://github.com/d3plus/d3plus-common/blob/master/src/prefix.js#L1)
323
324Returns the appropriate CSS vendor prefix, given the current browser.
325
326
327This is a global function.
328
329---
330
331<a name="stylize"></a>
332#### d3plus.**stylize**(elem, styles) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/stylize.js#L1)
333
334Applies each key/value in an object as a style.
335
336
337This is a global function.
338
339| Param | Type | Description |
340| --- | --- | --- |
341| elem | <code>D3selection</code> | The D3 element to apply the styles to. |
342| styles | <code>Object</code> | An object of key/value style pairs. |
343
344
345---
346
347<a name="unique"></a>
348#### d3plus.**unique**(objects) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/unique.js#L1)
349
350ES5 implementation to reduce an Array of values to unique instances.
351
352
353This is a global function.
354this
355
356```js
357unique(["apple", "banana", "apple"]);
358
359```
360returns this
361
362```js
363["apple", "banana"]
364```
365
366---
367
368<a name="uuid"></a>
369#### d3plus.**uuid**() [<>](https://github.com/d3plus/d3plus-common/blob/master/src/uuid.js#L10)
370
371
372This is a global function.
373
374---
375
376<a name="RESET"></a>
377#### **RESET** [<>](https://github.com/d3plus/d3plus-common/blob/master/src/RESET.js#L1)
378
379String constant used to reset an individual config property.
380
381
382This is a global constant.
383
384---
385
386
387
388###### <sub>Documentation generated on Thu, 07 Nov 2019 18:01:36 GMT</sub>