---
description: Perform join between Data and Graphical elements
---

# Data Join-Action

Data Join functionality helps in rendering the elements dynamically with respect to **data**. It builds a relationship between the data and the graphical elements. **I2Djs** provides a simple and unique way to define the join.

{% embed url="https://codepen.io/nswamy14/pen/LYVeEVz" %}



To begin let's create a data array with 3 items uniquely identified by the **id** field.

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

Let's define the join actions for the above data array. The join method takes **data**, **element selector,** and **action** **object** as an argument. **Actions object** comprises of **joinOn (**&#x6A;oin key) and **actions - enter, update, and exit.**

```
var joinRef = renderer.join(data,'circle',{
                         joinOn:function(d){
                             return d.id;
                         },
                         action:{
                             enter: function(newData){ },
                             exit: function(nodes){ },
                             update: function(nodes) { }
                     }
                });
```

### **Enter Action:**

Enter method defines an action for the new data. It receives a data object, with elementSelector property holding the corresponding new data array. Since we are performing join with a circle, **newData.circle** will have the new data array with respect to circle join.

&#x20;**createEls** API creates a circle for each data object. In the below example every new circle will be set with **attr** attributes and **style** properties. All new circles will be filled with red color.

![](https://content.gitbook.com/content/j4uz3UmYRheI1Pe6xix8/blobs/knMqGouOF7L69jxkaQfD/join1.png)

```

var joinRef = renderer.join(data,'circle',{
                         joinOn:function(d){
                             return d.id;
                         },
                         action:{
                             enter: function(newData){
                                 this.createEls(newData.circle,{
                                          el:'circle',
                                          attr:{
                                                 x:function(d){return d.id*10},
                                                 y:function(d){return d.id*10},
                                                 r:5
                                          },
                                          style:{
                                                 fill:'#ff0000'
                                          }
                                });
                             },
                             exit: function(nodes){
                             },
                             update: function(nodes) {
                             }
                     }
                })
```

### **Update Action:**

The Update method defines an action on the nodes of the retained dataset. Update action receives an object with elementSelector property holding respective nodes collection. In the below example, we set the circle color to '#00ff00' as part of the update action.&#x20;

```
update: function(nodes) {
    nodes.circle.setAttr('fill', '#00ff00');
}
```

Now let's append a new data object **{id: 4, label: 'four}** with the existing data array.

```
data.push({id:4, label:'four'});

joinRef.join(data);
```

On join execution, the **update action** will be triggered with 3 previously rendered nodes, which will be set to '#00ff00'. And **enter action** will receive the newly added object, which appears in red in color.

![](https://content.gitbook.com/content/j4uz3UmYRheI1Pe6xix8/blobs/5Aj2gWjVnRSqrW2kTmuN/join3.png)

### Exit Action:

The exit method defines action on the nodes of the obsolete dataset. Just like the update action, the exit action also receives an object with elementSelector property holding respective nodes collection. In the below example, we remove the circle nodes as part of the exit action.

```
exit: function(nodes) {
    nodes.circle.remove();
}
```

now let's remove the 2nd object from the existing data array.

```
data = [{id:1, label: 'First'}, {id:3, label:'third'}, {id:4, label:'four'}];
```

On join execution, exit action will be triggered with the nodes associated with the obsolete data. The same will be removed and the remaining nodes will be passed to update action.

![](https://content.gitbook.com/content/j4uz3UmYRheI1Pe6xix8/blobs/uBXExecFKAdqht3yJvUq/join4.png)

### Join with multi Elements - circle, text

Join with multi-elements can be performed by passing multi elementSelector string. In the below example, the data join is performed simultaneously between data and **circle, text** elements.

```
var joinRef = renderer.join(data,'circle,text',{
                         joinOn:function(d){
                             return d.id;
                         },
                         action:{
                             enter: function(newData){
                                 this.createEls(newData.circle,{
                                          el:'circle',
                                          attr:{
                                                 x:function(d){return d.id*10},
                                                 y:function(d){return d.id*10},
                                                 r:5
                                          },
                                          style:{
                                                 fill:'#ff0000'
                                          }
                                });
                                this.createEls(newData.text,{
                                          el:'text',
                                          attr:{
                                                 x:function(d){return d.id*10},
                                                 y:function(d){return d.id*10 + 20},
                                                 text: function(d) { return d.id }
                                          },
                                          style:{
                                                 fill: 'black',
                                                 text-anchor: 'middle'
                                          }
                                });
                             },
                             exit: function(nodes){
                                    nodes.circle.remove();
                                    nodes.text.remove();
                             },
                             update: function(nodes) {
                                    nodes.circle.setAttr('fill', '#00ff00');
                                    nodes.text.text('fill', function(d){
                                           return d.id;
                                        });
                             }
                     }
                })
```

![](https://content.gitbook.com/content/j4uz3UmYRheI1Pe6xix8/blobs/HwnBNpBqlXZ8qQROH0Ey/join4.png)
