UNPKG

10.4 kBMarkdownView 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/gitter/room/nwjs/nw.js.svg?style=flat)](https://gitter.im/d3plus/)
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* [prefix](#prefix) - Returns the appropriate CSS vendor prefix, given the current browser.
32* [stylize](#stylize) - Applies each key/value in an object as a style.
33* [uuid](#uuid) - Returns a unique identifier.
34
35#####
36* [RESET](#RESET) - String constant used to reset an individual config property.
37
38---
39
40<a name="BaseClass"></a>
41#### **BaseClass** [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L27)
42
43
44This is a global class.
45
46
47* [BaseClass](#BaseClass)
48 * [.config([*value*])](#BaseClass.config) ↩︎
49 * [.on([*typenames*], [*listener*])](#BaseClass.on) ↩︎
50
51
52<a name="BaseClass.config" href="#BaseClass.config">#</a> BaseClass.**config**([*value*]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L49)
53
54If *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.
55
56
57This is a static method of [<code>BaseClass</code>](#BaseClass), and is chainable with other methods of this Class.
58
59
60<a name="BaseClass.on" href="#BaseClass.on">#</a> BaseClass.**on**([*typenames*], [*listener*]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/BaseClass.js#L98)
61
62Adds 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.
63
64
65This is a static method of [<code>BaseClass</code>](#BaseClass), and is chainable with other methods of this Class.
66
67| Param | Type |
68| --- | --- |
69| [*typenames*] | <code>String</code> |
70| [*listener*] | <code>function</code> |
71
72By default, listeners apply globally to all objects, however, passing a namespace with the class name gives control over specific elements:
73
74```js
75new Plot
76 .on("click.Shape", function(d) {
77 console.log("data for shape clicked:", d);
78 })
79 .on("click.Legend", function(d) {
80 console.log("data for legend clicked:", d);
81 })
82```
83
84---
85
86<a name="accessor"></a>
87#### d3plus.**accessor**(key, [def]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/accessor.js#L1)
88
89Wraps an object key in a simple accessor function.
90
91
92This is a global function.
93
94| Param | Type | Description |
95| --- | --- | --- |
96| key | <code>String</code> | The key to be returned from each Object passed to the function. |
97| [def] | <code>\*</code> | A default value to be returned if the key is not present. |
98
99this
100
101```js
102accessor("id");
103
104```
105returns this
106
107```js
108function(d) {
109 return d["id"];
110}
111```
112
113---
114
115<a name="assign"></a>
116#### d3plus.**assign**(...objects) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/assign.js#L3)
117
118A deeply recursive version of `Object.assign`.
119
120
121This is a global function.
122this
123
124```js
125assign({id: "foo", deep: {group: "A"}}, {id: "bar", deep: {value: 20}}));
126
127```
128returns this
129
130```js
131{id: "bar", deep: {group: "A", value: 20}}
132```
133
134---
135
136<a name="attrize"></a>
137#### d3plus.**attrize**(elem, attrs) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/attrize.js#L1)
138
139Applies each key/value in an object as an attr.
140
141
142This is a global function.
143
144| Param | Type | Description |
145| --- | --- | --- |
146| elem | <code>D3selection</code> | The D3 element to apply the styles to. |
147| attrs | <code>Object</code> | An object of key/value attr pairs. |
148
149
150---
151
152<a name="closest"></a>
153#### d3plus.**closest**(n, arr) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/closest.js#L1)
154
155Finds the closest numeric value in an array.
156
157
158This is a global function.
159
160| Param | Type | Description |
161| --- | --- | --- |
162| n | <code>Number</code> | The number value to use when searching the array. |
163| arr | <code>Array</code> | The array of values to test against. |
164
165
166---
167
168<a name="configPrep"></a>
169#### d3plus.**configPrep**([config], [type], [nest]) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/configPrep.js#L1)
170
171Preps 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.
172
173
174This is a global function.
175
176| Param | Type | Default | Description |
177| --- | --- | --- | --- |
178| [config] | <code>Object</code> | <code>this._shapeConfig</code> | The configuration object to parse. |
179| [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". |
180| [nest] | <code>String</code> | | An optional nested key to bubble up to the parent config level. |
181
182
183---
184
185<a name="constant"></a>
186#### d3plus.**constant**(value) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/constant.js#L1)
187
188Wraps non-function variables in a simple return function.
189
190
191This is a global function.
192this
193
194```js
195constant(42);
196
197```
198returns this
199
200```js
201function() {
202 return 42;
203}
204```
205
206---
207
208<a name="elem"></a>
209#### d3plus.**elem**(selector, params) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/elem.js#L6)
210
211Manages the enter/update/exit pattern for a single DOM element.
212
213
214This is a global function.
215
216| Param | Type | Default | Description |
217| --- | --- | --- | --- |
218| selector | <code>String</code> | | A D3 selector, which must include the tagname and a class and/or ID. |
219| params | <code>Object</code> | | Additional parameters. |
220| [params.condition] | <code>Boolean</code> | <code>true</code> | Whether or not the element should be rendered (or removed). |
221| [params.enter] | <code>Object</code> | <code>{}</code> | A collection of key/value pairs that map to attributes to be given on enter. |
222| [params.exit] | <code>Object</code> | <code>{}</code> | A collection of key/value pairs that map to attributes to be given on exit. |
223| [params.parent] | <code>D3Selection</code> | <code>d3.select(&quot;body&quot;)</code> | The parent element for this new element to be appended to. |
224| [params.transition] | <code>D3Transition</code> | <code>d3.transition().duration(0)</code> | The transition to use when animated the different life cycle stages. |
225| [params.update] | <code>Object</code> | <code>{}</code> | A collection of key/value pairs that map to attributes to be given on update. |
226
227
228---
229
230<a name="isObject"></a>
231#### d3plus.**isObject**(item) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/isObject.js#L1)
232
233Detects if a variable is a javascript Object.
234
235
236This is a global function.
237
238---
239
240<a name="merge"></a>
241#### d3plus.**merge**(objects, aggs) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/merge.js#L4)
242
243Combines an Array of Objects together and returns a new Object.
244
245
246This is a global function.
247
248| Param | Type | Description |
249| --- | --- | --- |
250| objects | <code>Array</code> | The Array of objects to be merged together. |
251| 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. |
252
253this
254
255```js
256merge([
257 {id: "foo", group: "A", value: 10, links: [1, 2]},
258 {id: "bar", group: "A", value: 20, links: [1, 3]}
259]);
260
261```
262returns this
263
264```js
265{id: ["bar", "foo"], group: "A", value: 30, links: [1, 2, 3]}
266```
267
268---
269
270<a name="prefix"></a>
271#### d3plus.**prefix**() [<>](https://github.com/d3plus/d3plus-common/blob/master/src/prefix.js#L1)
272
273Returns the appropriate CSS vendor prefix, given the current browser.
274
275
276This is a global function.
277
278---
279
280<a name="stylize"></a>
281#### d3plus.**stylize**(elem, styles) [<>](https://github.com/d3plus/d3plus-common/blob/master/src/stylize.js#L1)
282
283Applies each key/value in an object as a style.
284
285
286This is a global function.
287
288| Param | Type | Description |
289| --- | --- | --- |
290| elem | <code>D3selection</code> | The D3 element to apply the styles to. |
291| styles | <code>Object</code> | An object of key/value style pairs. |
292
293
294---
295
296<a name="uuid"></a>
297#### d3plus.**uuid**() [<>](https://github.com/d3plus/d3plus-common/blob/master/src/uuid.js#L10)
298
299
300This is a global function.
301
302---
303
304<a name="RESET"></a>
305#### **RESET** [<>](https://github.com/d3plus/d3plus-common/blob/master/src/RESET.js#L1)
306
307String constant used to reset an individual config property.
308
309
310This is a global constant.
311
312---
313
314
315
316###### <sub>Documentation generated on Thu, 21 Dec 2017 20:37:45 GMT</sub>