@backand/vanilla-sdk v1.2.15

vanilla-sdk

Backand SDK for JavaScript. This SDK enables you to communicate comfortably and quickly with your Backand app. It requires zero configurations, no installations and no requirements.

Overview

Backand's Vanilla SDK is designed for easy integration with plain JavaScript applications, as well as other applications that do not make use of any particular JavaScript framework. If you are working with Angular 1, Angular 2, or Redux, we provide the following wrapper SDKs:

If you are not working with the above platforms, you can simply use this SDK directly with any web application - simply include the SDK in your client-side code, then get started!

Installation

To install the Vanilla SDK, use the correct command for your dependency management platform:

Import

Next, import the SDK into your project. To import in a bundler-based system, use the following JavaScript:

import backand from '@backand/vanilla-sdk'
const backand = require('@backand/vanilla-sdk')

Otherwise, include the following tags in your index.html file:

<script src="node_modules/@backand/vanilla-sdk/dist/backand.min.js"></script>
<script src="backand.min.js"></script>

Browser Support

Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	10+ ✔

Quick Start

Getting started with the SDK is as simple as configuring access to a Back& application, then calling getList on a relevant object:

backand.init({
  appName: 'APP_NAME',
  anonymousToken: 'ANONYMOUS_TOKEN'
});

backand.object.getList('users')
  .then((response) => {
      console.log(response);
  })
  .catch(function(error){
      console.log(error);
  });

This connects your Back& application (with the app name of APP_NAME and an anonymous access token of ANONYMOUS TOKEN) to your current project. Once the connection is configured, the SDK uses this connection information to construct HTTP requests to your API. Result data is returned in the response object as the member variable data. In the case of getList, this will be a JSON array of objects pulled from the users table in your Back& application. You can easily change the table being manipulated by replacing users with the name of any object in your system.

API Reference

backand.init():

The init() method creates a new Back& SDK instance with the supplied configuration.

Sample Code

var config = {
   appName: 'APP_NAME',
   anonymousToken: 'ANONYMOUS_TOKEN'
             };
backand.init(config);

The available parameters for the config parameter are:

SDK Properties:

Below is a list of the properties offered by the SDK, a description of the functionality handled by that property, and the list of methods provided by that property:

Default Events:

By default, the Back& SDK emits the following events that your code can respond to:

SDK Methods:

NOTE:

• All Methods return a Promise -> you can work with the response using .then() and .catch()
• You can see the response schema here

Authentication:

Authentication methods are called directly on the SDK, without any properties: backand.signin(username, password)

Signin

Signin with username and password in order to get access_token to be used in all other calls. If you don't have users you should use anonymous token only.

Parameters

Sample Code

backand.signin(username, password)
  .then(res => {
    console.log('signin succeeded with user:' + res.data.username);
  })
  .catch(err => {
    console.log(err);
  });

Signup

Creates a new user in your app. in signup you must provide the basic details of username email, first name, last name and password

Parameters

Sample Code

backand.signup(firstName, lastName, email, password, confirmPassword, parameters = {})
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Change Password

Changes the password of the current user

Parameters

Sample Code

backand.changePassword(oldPassword, newPassword)
  .then(res => {
    console.log('Password changed');
  })
  .catch(err => {
    console.log(err);
  });

Social Media Authentication:

socialSignin (also for Signup)

Signs the user into a Back& application using a social media provider as the authentication method. This opens a dialog window supplied by the social media network provider. If the user does not have an account with the selected provider, they will be prompted to create one as a part of this process.

Parameters

Sample Code

backand.socialSignin(provider)
  .then(res => {
    console.log('signin succeeded with user:' + res.data.username);
  })
  .catch(err => {
    console.log(err);
  });

CRUD:

The following methods perform create, retrieve, update, and delete functionality on a Back& object.

GetList

Fetches a list of records from the specified object. Uses options to store filter data

Parameters

Sample Code

backand.object.getList(object, options)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Sample Code with filter options

let options = {
  sort: backand.helpers.sort.create('creationDate', backand.helpers.sort.orders.desc),
  exclude: backand.helpers.exclude.options.all,
  filter: backand.helpers.filter.create('user', backand.helpers.filter.operators.relation.in, userId),
  pageSize: 20,
  pageNumber: 1
};
backand.object.getList(object, options)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

GetOne

Retrieves a single record from the specified object.

Parameters

Sample Code

backand.object.getOne(object, id, options)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Create

Creates a record with the provided data in the specified object

Parameters

Sample Code

backand.object.create(object, data, options, parameters)
  .then(res => {
    console.log('object created');
  })
  .catch(err => {
    console.log(err);
  });

Sample Code with filter options and parameters

let options = {
  returnObject: true
};
let parameters = {
  inputParameter1: 'value1',
  inputParameter2: 'value2'
};
backand.object.create(object, data, options, parameters)
  .then(res => {
    console.log('object created');
  })
  .catch(err => {
    console.log(err);
  });

Update

Updates a record with the specified ID in the specified object with the provided data.

Parameters

Sample Code

backand.object.update(object, id, data, options, parameters)
  .then(res => {
    console.log('object updated');
  })
  .catch(err => {
    console.log(err);
  });

Remove

Deletes a record from the specified object with the specified ID

Parameters

Sample Code

backand.object.remove(object, id, parameters)
  .then(res => {
    console.log('object removed');
  })
  .catch(err => {
    console.log(err);
  });

Trigger object actions (GET)

Triggers custom actions that operate via HTTP GET requests

Parameters

Sample Code

backand.object.action.get(object, action, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Trigger object actions (POST)

Triggers custom actions that operate via HTTP POST requests

Parameters

Sample Code

backand.object.action.post(object, action, data, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Socket Communications

You can easily integrate with our Socket functionality using the on method. Socket signin and signout are handled automatically by the SDK.

On

Event handler for broadcast Socket events.

Parameters

Sample Code

  //Wait for server updates on 'items' object
  Backand.on('items_updated', function (data) {
    //Get the 'items' object that have changed
    console.log(data);
  });

File

This property allows you to work with server-side actions, interacting with the related files directly. You can use this after you have finished creating a server-side action in the Back& dashboard, in the Actions tab of an object (object -> actions tab -> Backand Files icon -> name: 'files')

Upload

Uploads a file for a server-side action

Parameters

Sample Code

backand.file.upload(object, 'files', filename, filedata)
  .then(res => {
    console.log('file uploaded. url: ' + res.data.url);
  })
  .catch(err => {
    console.log(err);
  });

Remove

Removes a file from a server-side action file set.

Parameters

Sample Code

backand.file.remove(object, 'files', filename)
  .then(res => {
    console.log('file deleted');
  })
  .catch(err => {
    console.log(err);
  });

User:

The user property returns data about the connected user (getUserDetails, getUsername, getUserRole, getToken, getRefreshToken).

GetUserDetails

Gets the connected user's details.

Parameters

Sample Code

backand.user.getUserDetails(force)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Query:

The query property lets you initiate a custom Back& query using either HTTP GET or HTTP POST.

get

Calls a custom query using a HTTP GET NOTE: this method will be deprecated soon. please use backand.query.post instead

Parameters

Sample Code

backand.query.get(name, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

post

Calls a custom query using a HTTP POST

Parameters

Sample Code

backand.query.post(name, parameters)
  .then(res => {
    console.log(res.data);
  })
  .catch(err => {
    console.log(err);
  });

Offline:

The offline property allows you to control the SDK's offline mode. When the SDK detects that it has lost internet connection, it will queue requests internally. Based on the configuration provided to the init() function, this can result in either a delay prior to call execution or an error response to any update or delete calls. Once internet connection is restored, the queued commands are sent to the server, and the responses should be handled asynchronously through standard promise resolution

setOfflineMode

This function is used to enable and disable offline mode for debugging purposes. When true, the SDK will operate in offline mode. When false, the SDK will communicate over the web.

Parameters

Sample Code

// Enter offline mode
backand.offline.setOfflineMode(true);
// Exit offline mode
backand.offline.setOfflineMode(false);

cache

An object in which the cached data is stored

Sample Code

backand.offline.cache;

queue

All requests queued during offline mode are stored here. These operations will be dispatched when offline mode ends.

Sample Code

backand.offline.queue;

Examples and further reading

To view the demo web page, just run npm start - example page.

License

MIT