1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
<?xml version="1.0" encoding="UTF-8" ?>
<dt-api group="utility">
<name>map()</name>
<summary>Create a new API instance with the result set defined by the values returned from the callback function.</summary>
<since>1.10</since>
<type type="function">
<signature>map( fn )</signature>
<description>Iterate over the result set of an API instance, creating a new API instance from the values returned by the callback.</description>
<parameter type="function" name="fn">
Callback function which is called for each item in the API instance result set. The callback is called with three parameters:
* The element value
* The element index in the result set
* The API instance being traversed
The value returned by the callback will be added to the new API instance's result set, or `dt-type undefined` if no value is returned.
</parameter>
<returns type="DataTables.Api">New API instance with the values in the result set as those returned by the callback.</returns>
</type>
<description>
The `dt-api map()` method is useful for traversing a result set and creating a new instance, whose result set is defined by the values returned. As such any logic condition can be applied to the values of the original result set, transforming the data as required.
This method makes use of the fact that DataTables API objects are "array like", in that they inherent a lot of the abilities and methods of the Javascript `Array` type.
**Important compatibility note**: This method is implemented in the same way as the ECMA-262 5th edition `Array.prototype.map` method is and is not identical to [jQuery's `$.map` method](http://api.jquery.com/jquery.map/). The key difference is in how the returned value is handled. The ECMAScript standard requires that the resulting array (DataTables API instance in this case) is of identical length as the input array, while that is not true in `$.map`. When using jQuery's `$.map` method `null` or `undefined` can be returned to remove an item from the resulting array. In ECMAScript, and this DataTables method, those values are used in the new instance.
If you wish to remove items from the result set, use the `dt-api filter()` method.
This method is a proxy for the Javascript `Array.prototype.map` method and is provided as a utility method for the DataTables API. For more information about the original method, please refer to the [Mozilla MDN documentation for `map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map). In browsers which do not support `map` natively, a polyfill is provided to allow this DataTables method to operate as expected.
</description>
<example title="Square the values from a column"><![CDATA[
var table = $('#example').DataTable();
var squared = table
.column( 0 )
.data()
.map( function ( value, index ) {
return value * value;
} );
]]></example>
</dt-api>
|
