API Preview tool | The Dojo Toolkit

dojo/NodeList-data.js

Provides:
- dojo.NodeList-data

dojo._nodeDataCache

type
```
Object
```

summary

An alias to the private dataCache for NodeList-data. NEVER USE THIS!
This private is only exposed for the benefit of unit testing, and is
removed during the build process.

dojo.NodeList.data
- type
```
Function
```
- parameters:
  - key: (typeof Object?|String)
```
If an object, act as a setter and iterate over said object setting data items as defined.
If a string, and `value` present, set the data for defined `key` to `value`
If a string, and `value` absent, act as a getter, returning the data associated with said `key`
```
  - value: (typeof Anything)
```
The value to set for said `key`, provided `key` is a string (and not an object)
```
- source: [view]
    // summary: stash or get some arbitrary data on/from these nodes.
    //
    // description:
    //  Stash or get some arbirtrary data on/from these nodes. This private _data function is
    //  exposed publicly on `dojo.NodeList`, eg: as the result of a `dojo.query` call.
    //  DIFFERS from jQuery.data in that when used as a getter, the entire list is ALWAYS
    //  returned. EVEN WHEN THE LIST IS length == 1.
    //
    //  A single-node version of this function is provided as `dojo._nodeData`, which follows
    //  the same signature, though expects a String ID or DomNode reference in the first
    //  position, before key/value arguments.
    //
    // node: String|DomNode
    //  The node to associate data with
    //
    // key: Object?|String?
    //  If an object, act as a setter and iterate over said object setting data items as defined.
    //  If a string, and `value` present, set the data for defined `key` to `value`
    //  If a string, and `value` absent, act as a getter, returning the data associated with said `key`
    //
    // value: Anything?
    //  The value to set for said `key`, provided `key` is a string (and not an object)
    //
    // example:
    //  Set a key `bar` to some data, then retrieve it.
    // | dojo.query(".foo").data("bar", "touched");
    // | var touched = dojo.query(".foo").data("bar");
    // | if(touched[0] == "touched"){ alert('win'); }
    //
    // example:
    //  Get all the data items for a given node.
    // | var list = dojo.query(".foo").data();
    // | var first = list[0];
    //
    // example:
    //  Set the data to a complex hash. Overwrites existing keys with new value
    // | dojo.query(".foo").data({ bar:"baz", foo:"bar" });
    //  Then get some random key:
    // | dojo.query(".foo").data("foo"); // returns [`bar`]
    //
    // returns: Object|Anything|Nothing
    //  When used as a setter via `dojo.NodeList`, a NodeList instance is returned
    //  for further chaning. When used as a getter via `dojo.NodeList` an ARRAY
    //  of items is returned. The items in the array correspond to the elements
    //  in the original list. This is true even when the list length is 1, eg:
    //  when looking up a node by ID (#foo)
- summary
```
stash or get some arbitrary data on/from these nodes.
```
- description
```
Stash or get some arbirtrary data on/from these nodes. This private _data function is
exposed publicly on `dojo.NodeList`, eg: as the result of a `dojo.query` call.
DIFFERS from jQuery.data in that when used as a getter, the entire list is ALWAYS
returned. EVEN WHEN THE LIST IS length == 1.

A single-node version of this function is provided as `dojo._nodeData`, which follows
the same signature, though expects a String ID or DomNode reference in the first
position, before key/value arguments.

node: String|DomNode
The node to associate data with
```
- return_summary
```
Object|Anything|Nothing
When used as a setter via `dojo.NodeList`, a NodeList instance is returned
for further chaning. When used as a getter via `dojo.NodeList` an ARRAY
of items is returned. The items in the array correspond to the elements
in the original list. This is true even when the list length is 1, eg:
when looking up a node by ID (#foo)
```
- example
```
Set a key `bar` to some data, then retrieve it.

	dojo.query(".foo").data("bar", "touched");
	var touched = dojo.query(".foo").data("bar");
	if(touched[0] == "touched"){ alert('win'); }
```
- example
```
Get all the data items for a given node.

	var list = dojo.query(".foo").data();
	var first = list[0];
```
- example
```
Set the data to a complex hash. Overwrites existing keys with new value

	dojo.query(".foo").data({ bar:"baz", foo:"bar" });
Then get some random key:

	dojo.query(".foo").data("foo"); // returns [`bar`]
```
dojo.NodeList.removeData
- type
```
Function
```
- parameters:
  - key: (typeof String)
```
If ommitted, clean all data for this node.
If passed, remove the data item found at `key`
```
- source: [view]
    // summary: Remove the data associated with these nodes.
    // key: String?
    //  If ommitted, clean all data for this node.
    //  If passed, remove the data item found at `key`
- summary
```
Remove the data associated with these nodes.
```
dopid
- type
```
Function
```
- parameters:
  - node: (typeof )
- source: [view]
     var pid = d.attr(node, dataattr);
     if(!pid){
      pid = "pid" + (x++);
      d.attr(node, dataattr, pid);
     }
     return pid;
- summary
```
Return a uniqueish ID for the passed node reference
```
dojo._nodeData
- type
```
Function
```
- parameters:
  - node: (typeof )
  - key: (typeof )
  - value: (typeof )
- source: [view]
    var pid = dopid(node), r;
    if(!dataCache[pid]){ dataCache[pid] = {}; }
  
    // API discrepency: calling with only a node returns the whole object. $.data throws
    if(arguments.length == 1){ r = dataCache[pid]; }
    if(typeof key == "string"){
     // either getter or setter, based on `value` presence
     if(arguments.length > 2){
      dataCache[pid][key] = value;
     }else{
      r = dataCache[pid][key];
     }
    }else{
     // must be a setter, mix `value` into data hash
     // API discrepency: using object as setter works here
     r = d._mixin(dataCache[pid], key);
    }
  
    return r; // Object|Anything|Nothing
- returns
```
Object|Anything|Nothing
```
- summary
dodata
- ?? aliases = dojo._nodeData (debug: string) ??
- summary
dojo._removeNodeData
- type
```
Function
```
- parameters:
  - node: (typeof String|DomNode)
```
The node reference to remove data from
```
  - key: (typeof String)
```
If omitted, remove all data in this dataset.
If passed, remove only the passed `key` in the associated dataset
```
- source: [view]
    var pid = dopid(node);
    if(dataCache[pid]){
     if(key){
      delete dataCache[pid][key];
     }else{
      delete dataCache[pid];
     }
    }
- summary
```
Remove some data from this node
```
removeData
- ?? aliases = dojo._removeNodeData (debug: string) ??
- summary

dojo._gcNodeData

type
```
Function
```
source: [view]
  var livePids = dojo.query("[" + dataattr + "]").map(dopid);
  for(var i in dataCache){
   if(dojo.indexOf(livePids, i) < 0){ delete dataCache[i]; }
  }

summary

super expensive: GC all data in the data for nodes that no longer exist in the dom.

description

super expensive: GC all data in the data for nodes that no longer exist in the dom.
MUCH safer to do this yourself, manually, on a per-node basis (via `NodeList.removeData()`)
provided as a stop-gap for exceptionally large/complex applications with constantly changing
content regions (eg: a dijit.layout.ContentPane with replacing data)
There is NO automatic GC going on. If you dojo.destroy() a node, you should _removeNodeData
prior to destruction.

dojo.NodeList-data
- type
```
Object
```
- summary
dojo
- type
```
Object
```
- summary

dojo/NodeList-data.js

Provides:

dojo._nodeDataCache

dojo.NodeList.data

dojo.NodeList.removeData

dopid

dojo._nodeData

dodata

dojo._removeNodeData

removeData

dojo._gcNodeData

dojo.NodeList-data

dojo