Join Action

A way to define the relation ship between data and the graphical elements.

Join-Action

Node-i2djs offers a distinctive method for linking data with graphical elements through Join-Actions. This feature allows for the definition of Enter (New), Exit (Obsolete), and Update actions on DOM elements.

It is a new way to define the relationship between data and the elements.

let joinHandle = renderer.join([], el, {
                         joinOn: function(d){ },
                         action:{
                            enter: function (newDataArr) {},
                            exit: function (nodes) {},
                            update: function (nodes) {}
                         }
                      }
             );

The join method takes data array, element selector, and action object as arguments. Action object comprises of joinOn (join key) and actions - enter, update, and exit.

The Join API in Node-i2djs provides a group of handles that can be used to manipulate the data/nodes. With these handles, you can add new data, remove specific values from the data array, or pop data. These actions trigger the corresponding Join-Actions, which can improve application performance by avoiding unnecessary Join executions.

#.join(dataArray, selector, Actions);

#dataArray

Data is specified as an array of values.

let data = [{id:1, label: 'First'},{id:2, label: 'Second'},{id:3, label:'third'}]

#Selector

A selector is a valid CSS selector string - (.)Class, (#)Id, NodeName . It supports multiple selectors, comma separated, to perform join across DataArray and the individual selector elements. In the below example join takes place between DataArray - 'circle' Elements and DataArray - 'text' elements.

This approach helps in keeping the logic compact by eliminating redundant Join code.

#Actions Object

ActionsObject is comprised of actions (Enter, Exit, update) and the Join key specifier clause (joinOn).

JoinOn [optional] :

It's an access function to specify the join Key. If not specified, default behavior join-by-index will be considered.

Actions :

• Enter [optional]: A function that specifies an action for new data. It takes an object as input, which includes an elementSelector property that contains the corresponding new data array. The new data array must be used in conjunction with the createEls() function to create elements, and the function binds the data object to the element internally. In the following example, the Enter action generates Circle and Text elements for the new data.

• Update [optional]: The Update method specifies an action for the nodes in the retained dataset. The Update action gets an object as argument, which includes an elementSelector property that holds the corresponding collection of nodes.

• Exit [optional]: The Exit method specifies an action for the nodes that correspond to the obsolete dataset. Similar to the Update action, the Exit action gets an object as argument, which includes an elementSelector property that contains the corresponding collection of nodes.

Example

let data = [{id:1, label: 'First'},{id:2, label: 'Second'},{id:3, label:'third'}]


let joinRef = renderer.join(data,'circle,text',{
                         joinOn:function(d){
                             return d.id;
                         },
                         action:{
                             enter: function(data){
                                 this.createEls(data.circle,{
                                          el:'circle',
                                          attr:{
                                                 x:function(d){return d.id*10},
                                                 y:function(d){return d.id*10},
                                                 r:5
                                          },
                                          style:{
                                                 fill:'green'
                                          }
                                });
                                this.createEls(data.text,{
                                          el:'text',
                                          attr:{
                                                 x:function(d){return d.id*10},
                                                 y:function(d){return d.id*10 + 20},
                                                 text: function(d) { return d.label }
                                          },
                                          style:{
                                                 fill: 'black',
                                                 text-anchor: 'middle'
                                          }
                                });
                             },
                             exit: function(nodes){
                                 nodes.circle.remove();
                                 nodes.text.remove();
                             },
                             update: function(nodes) {
                                 nodes.circle.setStyle('fill', 'red');
                                 nodes.text.text('fill', function(d){
                                    return d.label;
                                 });

                             }
                     }
                })

Join Handles:

Join API returns handles to interact with the Data. These handles can be used to add new data, remove specific data or data arrays, or pop data. These actions trigger the corresponding actions and can improve application performance by avoiding unnecessary Join executions.

joinRef.join([Data]): It's useful in re-executing the complete actions for the new data set. Accepts Data Array and Performs complete join-actions executions.

joinRef.join(data)

#.push(data): If you push one or more new data elements, Enter action will be triggered for the new data elements.

joinRef.push({id:100}) // triggers enter action

#.pop(): Pop removes the last element from the data array and triggers Exit action.

joinRef.pop() // triggers Exit action for the Popped object 

#.remove(data): Accepts Data Value or array of values. Respective data will be removed from the Data array and triggers the Exit action.

joinRef.remove([{id:50},{id:20}]) // removes 2 data elements from array, triggers exit action

#.update(): To manually trigger the update action.

joinRef.update()