# Join Action

### Join-Action

I2D provides a unique way of performing a join between **data** and the **graphical** **Elements**. Using **Join-Actions** one can define **enter(New), exit(Obsolete), 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.**

Join API returns a set of [handle](https://github.com/I2Djs/I2Djs/wiki/Join-Action/_edit#join-handle)s to interact with the data/nodes. Using handle one can **push** the new data or **pop** or **remove** specific value from the data array, which internally triggers the respective actions. This mechanism boosts the 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]:** It's a function that defines an action for the new data. It receives an object as an input, with elementSelector property holding the corresponding new data array. New Data array has to be used with **createEls()** to create Elements, internally it binds the data object to the element. In the below example, the Enter action creates Circle and Text elements for the new Data.
* **Update \[optional]:** 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.
* **Exit \[optional]:** The Exit method defines action on the nodes corresponding to the obsolete dataset. Just like update action, exit action also receives an object with elementSelector property holding respective nodes collection.

#### 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. Using handle one can **push** the new data or **pop** data or **remove** specific data/Data array, which internally triggers the respective actions. This mechanism boosts the 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()
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nswamy14.gitbook.io/i2djs/api-reference/join-action.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.