Building a Data Connector

WireBootstrap client-side Data Connectors use service providers to connect to web services.

A WireBootstrap service provider is a JavaScript function or class that implements the methods and properties expected by the data source based on the functionality of the service provider.

This section documents a sample service provider created to query the public JSON Placeholder web service at https://jsonplaceholder.typicode.com. The sample is available in a sub-project inside any edition of the WireBootstrap for Gentelella download. Once downloaded, go to the\docs\building-a-data-connector directory to open the project containing the examples in this section. Double-click the index.html file to run the sample.

Create the Provider

The service provider is a simple JavaScript class or function that takes one configuration parameter. If needed, use the dataSource property on the configuration parameter to get a reference to the configuration passed into the calling data source.

const JsonPlaceHolderServiceProvider = function (config) {

  const datasource = config.dataSource;
  ...
  
}

Provider Configuration

Any service provider specific information for the data connector can be passed in using the Provider attribute when configuring the data source.

The example below passes in an API key that will be used by the service provider to authenticate calls to the web service. This key is not needed for the JSON Placeholder web service. Its used here only for demonstration.

  const source = new wire.data.DataSource("jsonplaceholder", {
    ...
    Provider: {
      apiKey: "my-test-key"
    }
  });

This configuration can then be read in and used by the service provider.

const JsonPlaceHolderServiceProvider = function (config) {

  const datasource = config.dataSource;
  const provider = datasource.Provider;
  const apiKey = provider.apiKey;  
  ...
  
}

For more information on data source configuration, visit DataSource.

Register the Provider

Register the service provider with the WireBootstrap framework by calling the wire.data.provider.register method.

wire.data.provider.register({
    id: "jsonplaceholder",
    provider: JsonPlaceHolderServiceProvider
});

Allow

The service provider in this example is able to transform WireBootstrap table queries into requests to the data service for data. The service provider tells the data source about this feature by setting the allow.tableQuery property to true.

...

this.allow = {
    tableQuery: true
}

Execute Queries

The execAsync method on the service provider will be called by a data source to execute queries against the data service. This method takes a TableQuery parameter with the inputs to the query.

In the example below, the getUrl method in the project will return the transformed query as a string URL that can be used to call the web service.

The wire.get method will make an asynchronous call to the web service to retrieve the data for the query.

this.execAsync = function (query) {

    const url = getUrl(query);

    return wire.get(url);            

}

DataTable Transform

After calling the asynchronous execAsync method on a service provider, the data source passes the data returned from the call to the getResponseTable method on the service provider. This method is responsible for handling any data service specific formatting and returning the data in a standard DataTable.

The data returned from calls to the JSON Placeholder web service is a simple array of objects so the data table is easily created by passing the data into the data table's constructor.

this.getResponseTable = function (data) {

    return new wire.data.DataTable(data);

}

Visit the ExecAsync documentation for more details on this method.

Putting It All Together

Consumers can now make calls to the data service using the service provider with a data source.

The first parameter to the DataSource constructor below is the id jsonplaceholder used when the service provider was registered with WireBootstrap above. The entity on the query is todos which is filtered touserId equal to1.

const source = new wire.data.DataSource("jsonplaceholder");

const query = wire.data.select().from("todos").where().eq("userId", 1);

const result = await source.execAsync(query);

The code above will result in the following call to the web service.

GET: https://jsonplaceholder.typicode.com/todos?userId=1