Introduction to Data Providers

Introduction to Data Providers

Purpose of Data Providers

Throughout the creation and development of Openous forms and controls, the concept of data providers is widely used. Data providers are essentially components that are used to interact with various data sources (static arrays, JavaScript code generated values, Web services, SharePoint lists, users) in order to finally deliver data to control properties such as “Lookup Values”, “Value” or “Default Value”.

Data Providers for Value

The most common property in Openous controls that accepts data provider as a class/data type is "Value". This property is applicable to <link:Data Controls>Data Controls and basically defines the information that is stored or displayed within the control. In order to understand their usage, we can assume the following simple scenario: We need to capture the first name of a user via an Openous form, and repeat it in a label. For this purpose, we will place:
  1. one label (named Label1) used for prompting the user, with a static value
  2. a Textbox control (named txt_Name) for the actual input
  3. a label underneath it (named Label2), for saluting the user with their first name in a simple "hello, {name}" fashion
The controls will be arranged in the following way:


Now the “Value” properties for the three controls would be:
  1. Label1: Since this is a static label (doesn’t change during the user’s interaction with our form), you will input the “Please input your name” message directly into the “Value” property within the label’s property panel: 

  1. txt_Name: No value here, it will be requested from the user at runtime
  2. Label2: If we want the value to be dynamic and depend on another control’s value, a common approach would be to use a <link:CodeDataProvider>Code Data Provider , which will evaluate a line of code during execution time and display a different message to the user according to their input. Therefore, at the “Value” property the “Edit” option should be pressed and the Data Provider selection dialog will be presented in order to choose one of the available Data Providers. We will choose New → “Code”:


This provider type expects a set of javascript commands followed by a “return” statement that will set the actual value to the control. Depending on the control type, the value returned by the last statement of our code can be of different type (for example, a Date Picker control expects a Data object, while a multiselect Combobox expects an array of objects). Given that our control is a Textbox, a simple string expression will be returned, therefore the code written within the Data Provider Properties is a single line of js code:



return "Hello, " + form.GetControl("txt_Name").GetValue();
If you test the above form, you will notice that once the name is written and you remove the focus from the textbox (click anywhere else), the Label2 control is updated with the correct salutation:

This happens because Openous tracks the dependency between the two controls from the “form.GetControl("txt_Name")” method, forcing the label’s value to be refreshed automatically once the value of the Textbox changes. 

Data Providers for Lookup Value

Data Providers can also be used in order to provide info to lookup controls, that is, Data Controls that prompt the user to select one or more options among a range of values like Combobox and Checkboxes.
For example, consider a Combobox where the end user will select a single option, among 5 static choices (similar to SharePoint’s choice column). In this case, a Static Data Provider, could be used, by selecting “New Provider” option in the Lookup Values property of the control:


By selecting “Static Data Provider”, you will be able to use a list editor for tabular info, and add/remove options to your Combobox:


As a result, your Combobox will display the specified set of values in your final form:


Some further common examples of data sources that are used via Openous Data Providers in lookup controls (such as the above Combobox) are:
  1. SharePoint data from another list (<link:SharePointMultiRecordProvider>SharePoint Multi Record Data Provider)
  2. SharePoint Users/People (<link:SharePointPeopleDataProvider> SharePoint People Data Provider)
  3. Data From Custom Code (Code Data Provider)
  4. Data From a File/URL Data Source (Url Data Provider)

Common Data Provider Properties

The following attributes are common throughout most data providers:
  1. Name: the identifier of the provider
  2. Cache: Applicable only to Async Code and Url Provider. After the first time of execution, the return values are cached in order to prevent delays in subsequent calls.
  3. Preload: Applicable only to Async Code and Url Provider. Executes the provider when the form loads. For example, when using an Async Code Provider for obtaining the lookup values in a Combobox control, the records are not loaded when the user expands the dropdown list, but when the form opens for the first time. 
  4. Condition: a javascript boolean expression that will be evaluated on runtime in order to determine whether this provider will be executed. For example, in a ListBox control, we may need to generate its rows only when the form opens in view mode. In this case the following expression will be used in the Value Provider of the Listbox: 
form.SP.IsViewMode
-or-
form.SP.IsViewMode == true
  1. OnDataLoaded: javascript code that handles the event that occurs after the data has been retrieved, and before providing them to the requestor (usually a Data Control). Can be used to set the alter the data before sending them to the control. To do that, change each item inside the args.Data array or just provide another value for the args.Data array. (i.e. args.Data = []). 
The following example appends an item to the rows of the data provider that is used to feed a Combobox lookup value:
//create an object programmatically
var extraItem = new Object();
extraItem.Title = "My new item";
extraItem.ID = 20;

//append the object at the end of the data source before it’s added to the control
if (args.Data) args.Data.push(extraItem);
  1. OnDataProvided: javascript code that handles the event that occurs after the data has been provided to the requestor (usually a data control). Can be used to set the initial value for the control receiving the data, for example:
form.GetControl("myCombobox").SetValue({ID:1, Title: "The default selection"});