DataSources JS APIs

The fliplet-datasources package contains the following namespaces:


Data Sources

Get the list of data sources for the current organization

Fliplet.DataSources.get().then(function (dataSources) {});

Create a new data source

Fliplet.DataSources.create({
  name: 'foo',
  organizationId: 1 // optional
}).then(function (dataSource) {
  // created
});

Connect to a data source, given its ID

// All options are optional
var options = {
  offline: true // By default on native platform it connects to offline DB. Set this option to false to connect to api's
}

Fliplet.DataSources.connect(dataSourceId, options).then(function (connection) {
  // check below for usages of the connection
});

Once you get a connection, you can use the following methods to find, insert, update and delete data.

Fetch all records from a data source

// use "find" with no options to get all entries
connection.find().then(function (records) {
  // records is an array
});
// use limit and offset for pagination
connection.find({ limit: 50, offset: 10 }).then(function (records) {
  // records is an array
});

Full example:

Fliplet.DataSources.connect(1).then(function (connection) {
  return connection.find({ limit: 1000 });
}).then(function (records) {
  records.forEach(function (row) {
    // do something for each row, e.g. append it to a html tag
    $('.foo').append(row.data.bar)
  });
});

Find specific records

connection.find({
  where: { name: 'John' },
  limit: 1
}).then(function (records) {
  // records is an array
});

Querying options are based on the Sift.js operators, which mimic MongoDB querying operators. Here’s the supported operators:

A few examples to get you started:

// Find records where column "sum" is greater than 10 and column "name"
// is either "Nick" or "Tony"
connection.find({
  where: {
    sum: { $gt: 10 },
    name: { $in: ['Nick', 'Tony'] }
  }
});

// Find records where column "email" matches the domain "example.org"
connection.find({
  where: {
    email: { $regex: /example\.org$/i }
  }
});

// Nested queries using the $or operator: find records where either "name" is "Nick"
// or "address" is "UK" and "name" is "Tony"
connection.find({
  where: {
    $or: [
      { name: 'Nick' },
      { address: 'UK', name: 'Tony' }
    ]
  }
});

// Find records where the column "country" is not "Germany" or "France"
// and "createdAt" is on or after a specific date
connection.find({
  where: {
    country: { $nin: ['Germany', 'France'] },
    createdAt: { $gte: '2018-03-20' }
  }
});

Find a record by its ID

connection.findById(1).then(function (record) {
  // records is the found object
});

Replace the contents of the data source with new records

connection.replaceWith([
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob', email: 'bob@example.org' }
]).then(function onComplete() {

});

Insert an array of new records into a data source

connection.append([
  { id: 3, name: 'Nick' },
  { id: 4, name: 'Ian', email: 'ian@example.org' }
]).then(function onComplete() {

});

Using connection.append(entriesArray) also triggers “insert “hooks for each created entry. This can be turned off (it defaults to true via the options second parameter) as follows:

connection.append([{ name: 'Nick' }], { runHooks: false })

Insert a single record into the data source

To insert a record into a data source, use the connection.insert method by passing the data to be inserted as a JSON object or a FormData object.

// Using a JSON object
connection.insert({
  id: 3,
  name: 'Bill'
});

// Using a FormData object
connection.insert(FormData);

Note: the dataSourceId and dataSourceEntryId are reserved keys and should not be used in the input JSON.

The second parameter of the connection.insert function accepts various options as described below:

Options: folderId

When FormData is used as first parameter, your record gets uploaded using a multipart request. If your FormData contains files, you can specify the MediaFolder where files should be stored to using the folderId parameter:

connection.insert(FormData, {
  folderId: 123
});

Options: ack

If you want to make sure the local (offline) database on the device also gets updated as soon as the server receives your record you can use the ack (which abbreviates the word acknowledge) parameter:

connection.insert({ foo: 'bar' }, {
  // this ensure the local database gets updated straight away, without
  // waiting for silent updates (which can take up to 30 seconds to be received).
  ack: true
});

Update a record (entry)

Updating a data source entry is done via the connection.insert method by providing its ID and the date to be updated.

connection.update(123, {
  name: 'Bill'
});

You can also pass a FormData object to upload files using a multipart request. When uploading files, you can also specify the MediaFolder where files should be stored to:

connection.update(123, FormData, {
  mediaFolderId: 456
});

Import a file into the data sources

connection.import(FormData).then(function onSuccess() {});

Remove a record by its ID

connection.removeById(1).then(function onRemove() {});

Configurable operations

Automatically generate a unique ID for your entries

You can instruct the system to automatically generate a GUID (also known as UUID) to all entries you insert by simply defining the guid key for a data source definition in Fliplet Studio (under the “App Data” section) and specifying the target column:

{ "guid": "myPrimaryGuidColumn" }

When this is set, all entries will automatically get a random 36-characters GUID once they get saved in the data source.


Back to API documentation