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:

| Platform | SDK link | | -------- | -------- | | Angular 1 | https://github.com/backand/angular1-sdk | | Angular 2 | https://github.com/backand/angular2-sdk | | Redux | https://github.com/backand/redux-sdk |

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:

| Provider | Command | | -------- | ------- | | npm | $ npm i -S @backand/vanilla-sdk | | yarn | $ yarn add @backand/vanilla-sdk | | bower | $ bower install backand-vanilla-sdk | | clone/download via Git | $ git clone https://github.com/backand/vanilla-sdk.git |

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:

| Param Name | Data Type | Usage | Required? | Default Value | | ---------- | --------- | ----- | --------- | ------------- | | appName | string | Sets the name of your backand app | required | | | anonymousToken | string | Sets the anonymous token of your backand app | required | | | useAnonymousTokenByDefault | boolean | Determines whether the sdk should use the anonymousToken when there is no other token | optional | true | | signUpToken | string | Sets the signup token of your backand app | optional | | | apiUrl | string | Sets the API url of backand servers | optional | https://api.backand.com | | storage | object | Sets the storage type to use (local/session/implementation of StorageAbstract) | optional | localStorage | | storagePrefix | string | Sets prefix to use in the storage structure | optional | BACKAND_ | | manageRefreshToken | boolean | Determines whether the sdk should manage refresh tokens internally | optional | true | | runSigninAfterSignup | boolean | Determines whether the sdk should run signin after signup automatically | optional | true | | runSocket | boolean | Determines whether the sdk should run socket automatically | optional | false | | socketUrl | string | Sets the socket url of backand servers | optional | https://socket.backand.com | | isMobile | boolean | Determines whether the sdk is part of a mobile application | optional | false | | mobilePlatform | string | sets the platform used to build the mobile application ('ionic'/'react-native') | optional | 'ionic' | | runOffline | boolean | Determines whether the sdk should run pending offline actions. (cached data and queued requests) | optional | false | | allowUpdatesinOfflineMode | boolean | Determines whether the sdk will allow object updates or deletion while in offline mode. When set to "true", all objects must contain a field, "updatedAt", that needs to be before the SDK entered offline mode. Any update/delete operations on fields with an "updatedAt" that occurs after the SDK entered offline mode will fail. | optional | false | | beforeExecuteOfflineItem | function | Sets the function to be called before each cached request. In order to determines whether to dispatch the next request or drop it, you must call return with a valid boolean. | optional | (request) => { return true } | | afterExecuteOfflineItem | function | Sets the function to be called after each cached request. | optional | (response, request) => { } |

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:

| Name | Methods | Description | | ---- | ----------- | ------- | | constants | EVENTS, URLS, SOCIALS | Provides access to constants in the SDK | | helpers | filter, sort, exclude, StorageAbstract | Provides helper methods for working with the SDK | | direct properties | useAnonymousAuth, useBasicAuth, signin, signup, socialSignin, socialSigninWithToken, socialSignup, requestResetPassword, resetPassword, changePassword, signout, getSocialProviders | These are properties available directly on the Backand SDK object, mostly focused on Authentication | | defaults | none | This stores the current app's configuration in the SDK | | object | getList, create, getOne, update, remove, get (action), post (action) | This encapsulates all methods used to manipulate objects | | file | upload, remove | Provides helper methods for working with files | | query | get, post | Allows you to work with custom query objects | | user | getUserDetails, getUsername, getUserRole, getToken, getRefreshToken | Provides information on the current authenticated user | | on | none | This is the event handler for socket.io functions, replacing socket.on | | offline | cache, queue, setOfflineMode | provides management for offline execution capabilities |

Default Events:

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

| Name | Description | Syntax | |---------|-----------------------|----------------------------------------------------------------------------| | SIGNIN | dispatched on signin | window.addEventListener(backand.constants.EVENTS.SIGNIN, (e)=>{}, false); | | SIGNOUT | dispatched on signout | window.addEventListener(backand.constants.EVENTS.SIGNOUT, (e)=>{}, false); | | SIGNUP | dispatched on signup | window.addEventListener(backand.constants.EVENTS.SIGNUP, (e)=>{}, false); | | START_OFFLINE_MODE | dispatched on start offline mode | window.addEventListener(backand.constants.EVENTS.START_OFFLINE_MODE, (e)=>{}, false); | | END_OFFLINE_MODE | dispatched on end offline mode | window.addEventListener(backand.constants.EVENTS.END_OFFLINE_MODE, (e)=>{}, false); |

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

| name | type | description | | ---- | ---- | ----------- | | username | string | the username to authenticate | | password | string | the user's password |

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

| name | type | description | | ---- | ---- | ----------- | | firstName | string | the user's first name | | lastName | string | the user's last name | | email | string | the user's email | | password | string | the user's password | | confirmPassword | string | the value entered by the user when asked to confirm the password during registration | | parameters | object | An object containing information for any paremeters to the signup call. This allows you to set additional info on the user object at registration time |

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

| name | type | description | | ---- | ---- | ----------- | | oldPassword | string | the user's old password | | newPassword | string | the user's desired new password |

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

| name | type | description | | ---- | ---- | ----------- | | provider | string | Name of the provider to authenticate with. The full list can be obtained by calling backand.getSocialProviders(scb) |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | options | object | A hash of filter options. Allowed options are: pageSize, pageNumber, filter, sort, search, exclude, deep, relatedObjects |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | id | integer | ID of the record to retrieve, subject to the filter specified in options | | options | object | A hash of filter options. Allowed options are: deep, exclude, level |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | data | object | Data to use in the creation of the new record | | options | object | A hash of filter options. Allowed options are: returnObject, deep | | parameters | object | Parameters for the action to operate upon |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | id | integer | ID of the object to update | | data | object | Data to update the record with | | options | object | A hash of filter options. Allowed options are: returnObject, deep | | parameters | object | Parameters for the action to operate upon |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | id | integer | ID of the object to update | | parameters | object | Parameters for the action to operate upon |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | action | string | Name of the action to trigger | | parameters | object | Parameters for the action to operate upon |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the Back& object to work with | | action | string | Name of the action to trigger | | data | object | Object data to send as the body of the POST request | | parameters | object | Parameters for the action to operate upon |

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

| name | type | description | | ---- | ---- | ----------- | | eventName | string | Name of the socket event to subsccribe to | | callback | function | Callback triggered when eventName is received |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the object controlling the desired server-side action | | fileAction | string | The name of the file action to work with | | filename | string | The name of the file to upload | | filedata | string | The file's data |

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

| name | type | description | | ---- | ---- | ----------- | | object | string | Name of the object controlling the desired server-side action | | fileAction | string | The name of the file action to work with | | filename | string | The name of the file to remove |

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

| name | type | description | | ---- | ---- | ----------- | | force | boolean | Forces the SDK to refresh its data from the server. Default: FALSE |

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

| name | type | description | | ---- | ---- | ----------- | | name | string | The name of the query to work with | | parameters | object | Parameters to be passed to the query |

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

| name | type | description | | ---- | ---- | ----------- | | name | string | The name of the query to work with | | parameters | object | Parameters to be passed to the query |

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

| name | type | description | | ---- | ---- | ----------- | | force | boolean | Sets the SDK to operate in - or exit from - offline mode.. Default: TRUE |

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