Data Events

A dataset listens for changes to elements of their queries using data events. For example, if a data set finds a change to a query field with the same name sent out in a data event, its able to change its query, re-execute it in the data service, and update its data promises so UI components and other consumers can react to the change.

Select Field List

In the following example, any data event sent out for the field UserName by dsFilter will be picked up by dsTable as a change. This is because the UserName field is in both select field lists. A change to UserName will result in dsTable re-executing its query based on the change. dsTable will then update its promises with new data.

...

const dsFilter = new wire.data.DataSet({
    Events: false,
    Source: source1,
    Query: wire.data.select("UserName")
        .from("Users")
});

const dsTable = new wire.data.DataSet({
    Source: source2
    Query: wire.data.select("UserName", "FullName")
        .from("Employees")      
});

Note, dsFilter.Events is set to false as most filters don't need to listen for changes.

Also, each dataset uses a different data source. They don't have to be the same.

Filter Field List

In the example below, a data event for UserName will also be picked up. However, in this instance, its because UserName is part of a filter rather than the selected field list.

...

const dsFilter = new wire.data.DataSet({
    Events: false,
    Source: source1,
    Query: wire.data.select("UserName")
        .from("Users")        
});

const dsTable = new wire.data.DataSet({
    Source: source2
    Query: wire.data.select()
        .from("Employees")  
        .where().eq("UserName","asmith");    
});

Event Names

Consider the following two datasets on the same page bound to two different UI components. Both the entity and field names are not the same however the intent is that data in dsFilter be used to change the query in dsTable.

However, sometimes its not possible to set up two queries inside datasets to share field changes by name because their names are different in the respective data services.

Fields from different database tables or entirely different data services can be mapped to be recognized as the same by the data event manager using the field or parameter alias EventName.

In the following example, the field method is used to select the UserName field in dsTable in order that meta data like eventName be set on the field. An event name UserName is set on the User field in the dsTable query in order for it to be mapped to the field UserName in dsFilter for the purposes of picking up changes via data events.

...

const dsFilter = new wire.data.DataSet({
    Events: false,
    Source: source1,
    Query: wire.data.select("UserName")
        .from("Users")
});

const dsTable = new wire.data.DataSet({
    Source: source2
    Query: wire.data.select("FullName")
        .field("User").eventName("UserName")
        .from("Employees")      
});

Event Fields

Sometimes it is required that a dataset listen for changes to a field that does not participate in the query. Here, data events for the field should update the query but should not be part of what gets executed against the data source or returned in the results.

In the example below, a data event for the UserName field from dsFilter will change the query in dsTable becaue dsTable specified UserName as an event field. UserName however is not part of the query in dsTable.

...

const dsFilter = new wire.data.DataSet({
    Events: false,
    Source: source1,
    Query: wire.data.select("UserName")
        .from("Users")
});

const dsTable = new wire.data.DataSet({
    Source: source2
    Query: wire.data.select("FullName")
        .eventField("UserName")
        .from("Employees")      
});