# wire.data.DataEvent

Event providers create and raise new data events to let components and other consumers know about interactions users make on a page.

```javascript
let event = new wire.data.DataEvent("myEvent");

...

event.raise();
```

Data events allow data, actions, and other context to be shared by providers with consumers.  Use the methods on the `DataEvent` class to build and broadcast data events.

## Methods

| Name                 | Description                                                                                                                                                 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cell(column, value)  | Adds the data for a particular cell from a source data table into the data event.  This includes the `column` name of the table as well as the row `value`. |
| column(column)       | Adds the source data table `column` object to the data event.                                                                                               |
| data(data)           | Adds custom `data` into the data event.  Note, this will overwrite any other data added to the data event.                                                  |
| dataselect           | Sets the event name for the data event to `dataselect`.                                                                                                     |
| element(id)          | Specifies that the data event is to be dispatched at the specific DOM element target by `id`.                                                               |
| event(eventName)     | Set the data event name to `eventName`.                                                                                                                     |
| getData              | Gets the data for the event.                                                                                                                                |
| label(column, value) | Sets a descriptive label for the data event using column and value.  Example:  `Product = SKU001`.                                                          |
| raise                | Broadcast the data event to consumers.                                                                                                                      |
| row                  | Adds the source data table `row` object to the data event.                                                                                                  |
| source               | For use with components, specifies the source object that created the event.                                                                                |
| table                | Adds the source data table to the data event.                                                                                                               |

The following example creates a new data event and adds some custom data to it.

```javascript
let event = new wire.data.DataEvent("myEvent")
    .data( { message: "Hello there" } );

event.raise();
```

## Action Methods

Actions allow providers to tell consumers the intent of a data event.  This intent is usually as it relates to changes to a query.

| Name    | Description                                                                                                                                                                        |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| add     | Event is intended to add new values to a field filter in a query.  This is often the case for use with a multi-select drop down.                                                   |
| clear   | Event is intended to clear all values for a field filter in a query.                                                                                                               |
| remove  | Event is intended to remove values from a field filter in query.                                                                                                                   |
| replace | Default action.  Event is intended to replace the values currently in a field filer with the ones specified in the data event.  This is often used with a single select drop down. |

The following broadcasts a change to data made in a component bound to a data table that `SKU001` in the `product` field was selected and based on the functionality of the component, this value should be replaced in all queries containing the `product` field.

```javascript
let event = new wire.data.DataEvent()
    .dataselect()
    .cell("product", "SKU001")
    .action().replace();

event.raise();
```