Using Datasources

Your applications use Datasource objects to work with data from different sources.  A datasource has a name, and provides access to a specific type of data, e.g. an SQL prepared statement, or a SOAP web service operation.

Create a Datasource

To create a new datasource, select the Datasource item in the Data menu. a datasource form appears, which lists the existing datasources.  Click on Create Datasource to open the Create Datasource form.

In the Create Datasource form, you can select the type of datasource.  Four types of data sources are currently supported:

• SQL Datasource
• SOAP Web Service datasource
• Server-side Jython datasource
  
• Server-side Javascript datasource

Please see the documentation on each datasource for instructions on how to setup each type of datasource.

Datasource Parameters

For a datasource, you may choose to make some of the input values parameters.  This gives you the most flexibility in using a datasource for a range of inputs.

In some cases, you may need to hide specifc input values from appearng on the client.  You can do this by adding server parameters.

Datasource Usage

Once you have created a datasource, you can use it in your Javascript functions, or directly attach it to some of the widgets.  For example, the table widget accepts a datasource name and allows you to set parameters for the data source.  When the table widget loads on a page, it will display the result data obtained from the data source.

Using Datasources in Javascript

From your Javascript functions, you can access the Datasource by name and perform operations using the datasource API.

A datasource works using an asynchronoous callback function that you provide.  The datasource performs a request and returns data via the callbak, passing in the DataWrapper instance which contains the results.

The following is a function example, where a select list is populated with values from the first column value of an SQL prepared statement query response.  In this case, the data is known to be returned as a tabular resultSet object.

var datasource = getDataSource("mydatasource");
if(datasource == null) { alert("DataSource is not available."); return; }

var params = null; // can use a Javascript array of parameters

datasource.getData(params, populateSelectList);

function populateSelectList(datawrapper) {
    if(datawrapper.hasError()) { alert("DATAWRAPPER ERR: " +datawrapper.error().message); }

    else {
       var selectElem = getWidgetByName('myselectlist');
       var resultSet = datawrapper.data();
       while(resultSet.next()) {
           var opt = document.createElement("OPTION");
           opt.text = resultSet.getValue(1);
           opt.value = resultSet.getValue(1); 
           opt.appendChild(document.createTextNode(resultSet.getValue(1)));  
           selectElem.appendChild(opt);
       }
    }
}

Render the result table

Getting Parameters back in callback function

The map should have the keys: callfunction (function to call) and params (parameter which should be sent along with datawrapper).

var myparams = { "message" : "More parameters of mine" };
var callbackMap = { "callfunction" : callbackFunction, "params" : myparams };

var dsparams = null;
datasource.getData(dsparams, callbackMap);

function callbackFunction(datawrapper, params) {
    alert("Message: " + params.message)
    datawrapper.renderResultTable();
}

Data Source API's

• getDataSource(datasourceName) -- Global function, available on the published page (displaypage.js), will initialize the datasource available for the application and returns the request DataSource instance (Applibase.db.DataSource) or null.

• DataSource.getType() -- Type of DataSource. Gives the type on which the DataSource is wrapped on. Returns ("" or !"SQLQUERY" or !"NAMEDQUERY").

• DataSource.getName() -- Returns the named of the DataSource.

• DataSource.getQuery() -- Returns the query associated with the DataSource.

• DataSource.getData(params, callback, async) -- Executes the DataSource with given parameters (params) and sends the result to the callback function as (DataWrapper), default is asynchronous, set async to false for doing synchronous fetch.

Data Wrapper API's

• DataWrapper.hasError() -- Did execution of DataSource resulted in error?

• DataWrapper.error() -- Get the error instance if hasEror returned true. (it returns Error instance, Error.message gives the error message).

• DataWrapper.data() -- Gives the data (result of DataSource execution), it will be generally a result set wrapper.
  • DataWrapper.data().type() -- Returns ("SQL" or "WEBSVC" or "JYTHON" or "JAVASCRIPT")
  • DataWrapper.data() return the data for non-tabluar data
    
  • DataWrapper.data().resultSet() -- Returns the result set for tabular data.