DataSets

The code for the following examples are available in the building-a-component project inside the \datasets folder.

Datasets encapsulate much of the plumbing for executing queries and responding to data changes on behalf of components. Datasets react to standard data events and send updates to components as standard datatables . 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 class via the syntax below in 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 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 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.

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.

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();

}