Data Sources

Alpaca supports lazy loading of data from remote locations via data sources. Data sources are supported by a limited number of field types - including select, radio and checkbox fields.

To use a data source, specify the dataSource option for your field.

The dataSource option can be any of the following:

• a set of datasource array elements directly supplied or a list of text items that will be converted to a data source array.
• an object consisting of key/value pairs to be used to generate the data source array
• the text URL for a remote GET endpoint where the datasource array will be loaded from.
• a function to call to acquire the datasource array. The function has the signature f(callback) and the this reference is set to the field instance. You can use this field instance to get at the field's current value and any other values from other members in the form. You may opt to call out to your own backend and acquire data. Fire the callback to pass the datasource array results back to Alpaca.
• a connector configuration (object) configuring data source array loading from a connector endpoint

The datasource array that is expected should be in the following format:

[{
  "value": "key 1", 
  "text: "display text 1"
}, {
  "value": "key 2", 
  "text: "display text 2"
}, {
  "value": "key 3", 
  "text: "display text 3"
}]

Using a Data Source Array

The easiest way to configure a data source is just to specify the data source array directly. There is nothing magical here. Nothing is dynamic and nothing is lazy loaded. Via this method, we can specify the text and value for each data source element.

Using a Data Source Array (text)

Another stripped down option is to only specify text in the area. In this case, Alpaca will assume the text for both the text and value for the data source array that is generates. Note that while this approach is simpler, it isn't equivalent to the previous approach in that you lose the display text.

Using an Object

If an object is passed to the data source, the key/value pairs of the object will be interpreted to be string/string pairs supplying the value and text respectively.

Here is how we can achieve the same example using an object.

Using a Remote URL

If the data source is text, it is assumed to specify a remote URL where the data source array can be acquired from If the URL starts with "/" as shown here, Alpaca automatically loads from the base path to the origin server.

The URL connection is assumed to be a GET and unauthenticated. If you need to control headers or access the underlying XHR object, consider using a custom function.

Using a Custom Function

We can plug in a custom function if we want to take full control over how we load the data. The function should create the data source array and pass it to the callback.

Using a Connector

Alpaca has the notion of connectors to integrate with common backends. Connectors understand how to load data sources based on a configuration supplied.

For an example of connector usage within a data source, check out Connectors.