loadDatasource

Definition:

NDLDS<datasource name>.loadDatasource(ndlParams)

 

Description:

Digitise Forms Datasources and Imported Datasources:

Downloads the specified records from a named Datasource, makes the first record the current record and automatically updates the value(s) displayed in any Elements which are input mapped to the specified Dataset.

Imported Stored Procedures which return a result set:

Executes the Stored Procedure, makes the first record in the returned result set the current record and automatically updates the value(s) displayed in any Elements which are input mapped to the specified Dataset.

 

Parameters:

loadDatasource requires the following properties to be added to the default ndlParams object:

ndlParams.tablename - Required

Name of the Dataset.

 

ndlParams.errorHandler - Optional

Name of an error handler function to be called if the loadDatasource call fails and an HTTP error response is received. The function must be a JavaScript function located within the custom JavaScript for the form. If you omit this property, the function specified in the Form's Default Error Handler property will be used, by default this will be the onDatasourceError function. For more information, see Display Datasource Error Messages.

Note that this function will only action error handling if Display Error Messages is selected under the form properties.

 

ndlParams.requestParams - Required

A string containing a series of 'name=value' pairs delimited by '&' specifying the SQL Query to use to determine which records to download. If the SQL Query includes parameters allowing you to specify the records to download by inputting values extracted from Elements on the form, the extracted values are included here.

The first pair must be ndlqueryid="<sql query GUID>", where <sql query GUID> represents the GUID identifying the SQL Query (see Notes).

Subsequent pairs specify the Query's parameters, if any, and provide values for each parameter. The name contains the name of the parameter minus the initial '@' and the first character of the name should be converted to lower case if it isn't already. For example a parameter @First_Name would have the name first_Name. The value contains the extracted value from the appropriate Element on the form. The Code sample section below provides an example of how to specify the parameters.

If your SQL Query doesn't have any parameters, requestParams will consist simply of the SQL Query GUID name/value pair.

 

ndlParams.onResponseReceived - Optional

Specifies the name of a JavaScript function to be run when loadDatasource has finished. This function will be run after loadDatasource has completed all its actions and hence, if the download has been successful, Element properties will have been updated with the data in the first record by the time this function runs. Note, however, that the screen may not update before the onResponseReceived function runs.

 

Returns:

nothing

 

Code Sample 1:

This example shows how to call loadDatasource for a Digitise Forms or Imported Datasource without using an onResponseReceived function.

It shows the JavaScript statements which might appear in the JavaScript function generated from an Element's Event property where LoadDatasource is assigned to the Event and the SQL query used to define the records to be selected requires a parameter, @AccountNumber.

//name the table

ndlParams.tablename = "MyDataset";

//name the error handler function - the name shouldn't be in quotes

ndlParams.errorHandler = functionname;

//set up a variable with the value from a named source element to pass into the SQL query used to define the records to be selected

//the variable name must match the parameter name in the defined SQL Query - the '@' is removed and the remaining string is camel-cased

var accountNumber = form1.page1.ndltextbox1.value;

//add the defined request parameters to ndlParams

ndlParams.requestParams = "ndlqueryid=ab1111ab-c22c-d33d-e44e-ff55555555ff" + "amp;" + "accountNo=" + encodeURIComponent(accountNumber);

//call loadDatasource : the response is asynchronous, and the elements are updated with the values of the first record once the response has been received

NDLDSMyDatasource.loadDatasource(ndlParams);

 

 

Code Sample 2:

This example shows you how to perform two loadDatasource calls for a Digitise Forms or Imported Datasource using an onResponseReceived function to nest the second download (see Notes below for additional information).

Note in the onResponseReceived function, because this function is not generated from an Element's event property, you need to create an ndlParams object to pass to loadDatasource, but loadDatasource doesn't need any of the four properties specified in the default ndlParams object and so these properties are not added here.

functionPage1_button1_clicked(ndlParams)

{

⁝

//name the table

ndlParams.tablename = "MyDataset";

//name the error handler function - the name shouldn't be in quotes

ndlParams.errorHandler = functionname;

//set up a variable with the value from a named source element

var accountNumber = form1.page1.ndltextbox1.text;

//add the defined request parameters to ndlParams

ndlParams.requestParams = "ndlqueryid=ab1111ab-c22c-d33d-e44e-ff55555555ff" + "amp;" + "accountNo=" + encodeURIComponent(accountNumber);

// specify an onResponseReceived function - the name shouldn't be in quotes

ndlParams.onResponseReceived = onResponseReceived;

//call loadDatasource : the response is asynchronous, and the elements are updated with the values of the first record once the response has been received

NDLDSMyDatasource.loadDatasource(ndlParams);

⁝

}

 

function onResponseReceived(response)

{

// define a second ndlParams object for the second loadDatasource call

var ndlParams2 = {};

//name the table

ndlParams2.tablename = "MyDataset2";

//name the error handler function - the name shouldn't be in quotes

ndlParams2.errorHandler = functionname2;

//add the defined request parameters to ndlParams - note each SQL Query defined in your Datasets has a different identifying GUID

ndlParams2.requestParams = "ndlqueryid=ff9999ff-e88e-d77d-c66c-bb55555555bb";

//call loadDatasource : the response is asynchronous, and the elements are updated with the values of the first record once the response has been received

NDLDSMyDatasource2.loadDatasource(ndlParams2);

}

 

 

Code Sample 3:

This example shows you how to perform two loadDatasource calls for an Imported Stored Procedure Datasource using an onResponseReceived function to nest the second download (see Notes below for additional information). In this example, the two Datasets correspond to two different result sets from the same Stored Procedure and hence the Datasource name and the parameters are the same for both calls to loadDatasource, but they could equally be from separate Stored Procedures in which case the Datasource names would be different in the two functions and the parameters may well be different too.

As with Code Sample 2 above, in the onResponseReceived function, you will need to create an ndlParams object to pass to loadDatasource, but loadDatasource doesn't need any of the four properties specified in the default ndlParams object and so these properties are not added here.

function Page1_button1_clicked(ndlParams)

{

// LoadDatasource

// Hint: You can change how the parameter values are set.

// The first parameter must be ndlqueryid to specify the identifier of the SQL Query to be used

// The remaining parameter names must match the parameter names in the defined SQL Query - the '@' is removed and the remaining string is camel-cased

// The parameters for the defined SQL query are:

// @Start_Date ; related parameter name: start_Date

// @End_Date ; related parameter name: end_Date

// @Postcode ; related parameter name: postcode

// Add your own code as appropriate

⁝

//name the table

ndlParams.tablename = "MyDataset";

//set up a variable with the value from the named source element

var start_Date= form1.page1.ndldatepicker1.value;

//set up a variable with the value from the named source element

var end_Date= form1.page1.ndldatepicker2.value;

//set up a variable with the value from the named source element

var postcode= form1.page1.ndltextbox1.value;

//name the error handler function - the name shouldn't be in quotes

ndlParams.errorHandler = functionname;

//add the defined request parameters to ndlParams

ndlParams.requestParams = "ndlqueryid=ab1111ab-c22c-d33d-e44e-ff55555555ff"+"&" + "start_Date=" + encodeURIComponent(start_Date)+"&" + "end_Date=" + encodeURIComponent(end_Date)+"&" + "postcode=" + encodeURIComponent(postcode);

// specify an onResponseReceived function - the name shouldn't be in quotes

ndlParams.onResponseReceived = onResponseReceived;

//call loadDatasource : the response is asynchronous, and the elements are updated with the values of the first record once the response has been received

NDLDSSP_dbo_MyStoredProcedure.loadDatasource(ndlParams);

⁝

}

 

function onResponseReceived(response)

{

// define a second ndlParams object for the second loadDatasource call

var ndlParams2 = {};

//name the table

ndlParams2.tablename = "MyDataset2";

//set up variables with the values from the named source elements

var start_Date= form1.page1.ndldatepicker1.value;

var end_Date= form1.page1.ndldatepicker2.value;

var postcode= form1.page1.ndltextbox1.value;

//name the error handler function - the name shouldn't be in quotes

ndlParams2.errorHandler = functionname2;

//add the defined request parameters to ndlParams - note each SQL Query defined in your Datasets has a different identifying GUID

ndlParams2.requestParams = "ndlqueryid=ff9999ff-e88e-d77d-c66c-bb55555555bb"+"&" + "start_Date=" + encodeURIComponent(start_Date)+"&" + "end_Date=" + encodeURIComponent(end_Date)+"&" + "postcode=" + encodeURIComponent(postcode);

//call loadDatasource : the response is asynchronous, and the elements are updated with the values of the first record once the response has been received

NDLDSSP_dbo_MyStoredProcedure.loadDatasource(ndlParams2);

}

 

 

Notes:

  • You cannot use loadDatasource with an Imported Stored Procedure which doesn't return a Result Set.

  • For each call to loadDatasource, you need to include the GUID identifying the SQL Query to be used to select the records to be downloaded in the requestParams parameter. Each of the queries in your Datasets is assigned its own GUID to identify it. You can obtain the GUID of a SQL Query, by generating a custom JavaScript function from the Event Builder which calls loadDatasource using the required query.

    To do this, select the Element you want to perform a data download and open its Events properties. Click on the relevant Event to load the Event Builder. Drop down the action list and select LoadDatasource from the list of predefined Datasource Operation actions. Specify the required Datasource, Dataset and SQL Query and then click Convert to Custom JavaScript. This will add a skeleton function to the custom JavaScript which you can use as a starting point or from which you can copy and paste the required code.

  • Remember, in order to download a Dataset, you must have enabled read access in the Dataset's properties by selecting the Allow Read Access property.

  • If you are updating Datasets which include one or more Foreign Keys, refer to the topic Handling Datasets with Foreign Keys for additional information. You don't need to call loadDatasource to download records for child Datasets in managed relationships with other Datasets. In these situations, you only need to download the parent Dataset and the appropriate related records in the child Dataset will be downloaded automatically.

  • If you have Datasource error reporting enabled (see ndlParams.errorHandler property above) and an error occurs, the error message will be displayed and any onResponseReceived function specified will also be run but there is no guarantee that the error will be displayed before the function runs. Therefore, you will need to ensure that your function is written to allow for this situation should it arise.

  • The data download is asynchronous, which means that the Script doesn't wait for the download to complete before continuing and any code following the loadDatasource will be executed whilst the data download is taking place.

    Any actions that require the data download to be completed before they are performed can be coded using the onResponseReceived property, which allows you to specify a second function to be run once the data download has finished.

    If you want to make more than one call to loadDatasource within the same function, you can either include multiple calls within the same function or use the onResponseReceived function to nest calls. Which you choose depends upon whether you need one data download to finish before performing a second. Where the logic requires one download to have finished before a second download starts, you will need to include the second loadDatasource within the onResponseReceived function for the first in order to be sure that the first completes before the second starts. Where it doesn't matter whether the first call has finished before a subsequent call starts, you can include both calls to loadDatasource in the same function.

    The parameter passed into the onResponseReceived function, will be an object containing the HTTP response from the download.

    If you are downloading data from the same Dataset using the same SQL Query as you have used elsewhere within your custom JavaScript, you can simply copy the lines of code from a previous example, you don't need to regenerate a custom function to obtain the SQL Query GUID - the GUID will be the same each time. If you want to download data from a different Dataset or use a different SQL Query to select the records, then you will need to obtain the relevant GUID for the SQL query by creating a new custom function. You can then copy the lines from that function or use the new function as the basis for an onResponseReceived function.

    In addition, if you want to perform multiple calls to loadDatasource, whether within a single function or nested using an onResponseReceived function, each call will need to have a separate version of the ndlParams object. Code Samples 2 and 3 above, provides examples of using nested loadDatasource calls and creating individual ndlParam objects. The principle is the same if you include both calls within a single function rather than nesting them.

    You can also include any additional custom parameters you might want to pass into your onResponseReceived function by adding them to the ndlParams object along with the other properties, e.g.:

    ndlParams.tablename = "MyDataset";

    ndlParams.errorHandler = functionname;

    ndlParams.requestParams = "ndlqueryid=ab1111ab-c22c-d33d-e44e-ff55555555ff";

    ndlParams.onResponseReceived = MyFunction;

    //pass through customer name

    ndlParams.custName = form1.page1.ndltextbox1.value;

    NDLDSMyDatasource.loadDatasource(ndlParams);

     

    When specifying custom parameters in this way, you must avoid using reserved words or parameter names which are already in use. For a list of typical reserved words see: https://www.w3schools.com/js/js_reserved.asp.

 

Using as Predefined
Action in Event:

When assigned to an Event as a predefined action, this function doesn’t require any editing.

If you want to load more than one Dataset within a single Event, you will need to configure the first LoadDatasource action and then convert it to a JavaScript function from the Event Builder pop-up and then add the second into the JavaScript function manually, using the code samples above as a guide. You can add the second call to loadDatasource into the same function or use the onResponseReceived parameter to run it in a separate function - see Notes above for more details.

 

 

See also:

refreshFormControlsFromDatasource

Reset Form

Event Properties

Customise Forms with JavaScript

Selecting Records Using SQL Queries

Display Datasource Error Messages

Writing Scripts