# DataSets

The code for the following examples are available in the [building-a-component](https://docs.wirebootstrap.com/wirebootstrap/working-with-components/building-a-component) project inside the `\datasets` folder.

[Datasets](https://docs.wirebootstrap.com/wirebootstrap/working-with-components/building-a-component/datasets) encapsulate much of the plumbing for executing queries and responding to data changes on behalf of components.  Datasets react to  [standard data events](https://docs.wirebootstrap.com/wirebootstrap/dataevents) and send updates to components as standard [datatables](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.data/wire.data.datatable) .  As a result, most components that need to handle data changes will leverage datasets for data binding.

## Component

In order to leverage datasets for data binding, a component starts by extending the base [`wire.ui.Component`](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.ui/wire.ui.component) class via the syntax below in JavaScript.

```javascript
var myComponent = function () {

    const self = this;
    
    wire.ui.Component.call(this);

    ...    
}
```

## Initialize

Next, initialize the base `wire.ui.Component` class by calling the `init` method which takes the following parameters.

| Name     | Description                                                                                            |
| -------- | ------------------------------------------------------------------------------------------------------ |
| element  | The element passed into the `render` method.                                                           |
| config   | See [Config](#config) section below.                                                                   |
| dataBind | The function to call when data bound to the component has changed.  This includes the initial binding. |

### Config

The default configuration settings for the component will be merged with the ones passed in as part of the component binding.  See [Component - Config](https://docs.wirebootstrap.com/wirebootstrap/working-with-components/component#config) for more information.

| Name    | Description                                                                                |
| ------- | ------------------------------------------------------------------------------------------ |
| default | The default settings for the component's configuration.                                    |
| user    | The settings passed into the `render` method.  These will override the `default` settings. |

### Example

The following is a full example of the `initialize` method being called in a component.

```javascript
this.render = function (el, userConfig) {

    self.init({
        // Root element passed in
        element: el,
        // Merge user and default configs with user overriding the default
        config: {
            // This component looks for a person field in the data
            // The name of the field defaults to 'person'
            default: { datamap: { person: "person" } },
            // User override for any configuration
            user: userConfig,
        },
        // Function to be called when there is new data for the component
        // This includes the first time during initialization
        dataBind: _bind
});
```

## DataBind

The `_bind` method set in the `dataBind` configuration above is detailed below in comments.

```javascript
function _bind() {

    // Merged user and default configs with user overriding the default
    const cfg = self.config();

    // New data as a datatable
    const table = self.table();

    // Grab the first row
    const row = table.first();

    // Get a reference to the root DOM element
    // Use self.$element() to get a jQuery reference
    const el = self.element();

    // Add the data to the root element
    // Use the 'datamap' config property to reference the data in case the field name is different in the source data
    el.innerHTML = row ? row[cfg.datamap.person] : "";

    // Tell everyone the component is ready
    // Calls the 'ready' event if set in the configuration
    self.ready();

}
```