JavaScript API Reference

appstax

appstax.init(appKey)

  • appKey (string): The app key

appstax.init(options)

Initializes appstax with your app key, identifiying your app in calls to the REST Backend.

  • options.appKey (string): The app key
  • options.baseUrl (string): Optional base url for the backend. Defaults to https://appstax.com/api/latest

appstax.object(collectionName [, properties])

Creates a new object. See also: working with objects

  • collectionName (string): Name of the collection the object will belong to
  • properties (object): Object with initial values for the objects properties
  • returns: An appstax object

appstax.file(file)

Creates a new file to be used an object property.

appstax.channel(identifier, [users | filter])

Connects to a realtime channel

  • identifier (string): The channel or pattern to connect to, e.g. "public/chat", "private/devices/*", object/notes"
  • users (array): Usernames to give read/write access to. Only applicable for private channels.
  • filter (string): Filter string to reduce the set of objects to receive events from. Only applicable for object channels.
  • returns: An appstax channel

appstax.model()

Creates a realtime model

appstax.findAll(collectionName [, options])

Loads all objects from a collection.

  • collectionName (string): Name of the collection.
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.find(collectionName, id [, options])

Loads a single object from a collection

  • collectionName (string): Name of the collection.
  • id (string): Id of the object to load
  • options (object): Query options
  • returns: A promise that resolves with the loaded object.

appstax.find(collectionName, queryFunction [, options])

Queries for objects from a collection. See also querying objects

  • collectionName (string): Name of the collection.
  • queryFunction (function): A function that takes a query parameter
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.find(collectionName, queryObject [, options])

Queries for objects from a collection. See also querying objects

  • collectionName (string): Name of the collection.
  • queryObject: A query object
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.find(collectionName, queryString [, options])

Queries for objects from a collection. See also querying objects

  • collectionName (string) Name of the collection.
  • queryString (string) A query string as described in the REST API Guide
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.find(collectionName, propertyValues [, options])

Queries for objects with specific property values. The returned objects have property values that match exactly to the propertyValues parameter. See also querying objects

  • collectionName (string): Name of the collection.
  • propertyValues (object): An object with keys and values to match
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.search(collectionName, propertyValues [, options])

Searches for objects with some property values. In the returned objects at least one of the properties contain the value given for that property in the propertyValues parameter. See also querying objects

  • collectionName (string): Name of the collection.
  • propertyValues (object): An object with keys and values to match
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.search(collectionName, properyValue, propertyNames [, options])

Searches for objects with some property values. In the returned objects at least one of the properties contain the value given for that property in the propertyValues parameter. See also querying objects

  • collectionName (string) Name of the collection.
  • propertyValue (string) A value to search for
  • propertyNames (array) Names of properties to search
  • options (object): Query options
  • returns: A promise that resolves with the loaded objects.

appstax.signup(username, password [, login] [, properties])

Signup a new user with given username and password. See also handling users

  • username (string): Username for new user
  • password (string): Password for new user
  • login (boolean): The user should also be logged in. Default true.
  • properties (object): Properties to store on the user object
  • returns: A promise that resolves when the signup request is completed.

appstax.login(username, password)

Log in a registered user with given username and password. See also handling users

  • username (string): Username for login
  • password (string): Password for login
  • returns: A promise that resolves with a user when the login request is completed.

appstax.login(options)

Log in using an identity provider. See also Social Login Guide

  • options.provider (string): Name of identity provider
  • returns: A promise that resolves with a user when the login request is completed.

appstax.currentUser()

Get the currently logged in user. Returns null if the user is not logged in. See also handling users

  • returns: A user object.

appstax.logout()

Log out. See also handling users

appstax.requestPasswordReset(email)

Start password reset flow by sending an email to the user. See also handling users

  • email (string): The email address to receive a password reset code.
  • returns: A promise that resolves when the request is completed.

appstax.changePassword(options)

Start password reset flow by sending an email to the user. See also handling users

  • options.username (string): Username to change password for
  • options.password (string): New password
  • options.code (string): The password reset code received by email
  • options.login (boolean): Automatically log in with new password (default is false)
  • returns: A promise that resolves with the logged in user when the request is completed.

file

Properties and methods available on file properties. See also working with files.

  • file.url: The url to the file. Use this in <img src=""> and download links.
  • file.filename: The name of the file

file.preview()

Creates a data url in the file's .url property.

  • returns: A promise that resolves with the file object.

file.imageUrl(operation, options)

Returns an URL to a resized/cropped version of the image file. Provide options for desired width and/or height.

  • operation (string) resize or crop
  • options.width (number) The width of the resulting image
  • options.height (number) The height of the resulting image

  • returns: An URL string to load transformed image

user

  • user.username: The username of the user. (Read-only)
  • user.id: The id of the user object in the users collection.

user.save()

Saves the user data to the datastore.

  • returns: A promise that resolves with the saved user object.

user.refresh()

Refreshes the user object with latest data from server. Any local changes will be overwritten.

  • returns: A promise that resolves when the user has been refreshed.

object

Properties and methods available on objects stored in your datastore. See also working with objects.

  • object.id: The id of the object (read-only)
  • object.collectionName: Name of the collection this object is stored in (read-only)
  • object.permissions: Array of permissions the current user has for this object (read-only)
  • object.created: A Date object with the first time this object was saved (read-only)
  • object.updated: A Date object with the last time this object was saved (read-only)

object.save()

Saves the object

  • returns: A promise that resolves with saved object.

object.saveAll()

Saves the object and all related objects.

  • returns: A promise that resolves when all related objects have completed saving.

object.remove()

Removes the object from the datastore.

  • returns: A promise that resolves when the object has been removed.

object.refresh()

Refreshes the object with latest data from server. Any local changes will be overwritten.

  • returns: A promise that resolves when the object has been refreshed.

object.grant(username, permissions)

Grants permissions for this object to specified user. The permission change is persisted with the next call to .save(). See also controlling access to objects.

  • username (string): Username of user to grant to.
  • permissions (array): Array of permissions to grant.

object.revoke(username, permissions)

Revokes permissions for this object to specified user. The permission change is persisted with the next call to .save(). See also controlling access to objects.

  • username (string): Username of user to revoke from.
  • permissions (array): Array of permissions to revoke.

object.grantPublic(permissions)

Grants permissions for this object to anonymous users. The permission change is persisted with the next call to .save(). See also controlling access to objects.

  • permissions (array): Array of permissions to grant.

object.revokePublic(username, permissions)

Revokes permissions for this object from anonymous users. The permission change is persisted with the next call to .save(). See also controlling access to objects.

  • permissions (array): Array of permissions to revoke.

object.hasPermission(permission)

Tells wether the current user has the given permission for this object.

  • permission (string): Name of the permission to check.
  • returns: true or false

channel

Use channels to send and receive realtime events and data.

channel.send(message)

  • message (string | object): The message string or object data to send

channel.on(event, handler)

  • event (string): Name of event to listen to. See channel event.
  • handler (function): Event handler function. Takes a single event object parameter.

channel event

The channel event handler can receive the following event types: "message", "error", "object.created", "object.updated", "object.deleted"

The channel event object has these properties:

  • message (string | object): The received message data in a "message" event.
  • object (object): The received appstax object in a "object.*" event
  • error (string): The received error message in a "error" event

realtime model

model.watch(name [, options])

Adds a live property to the model.

  • name (string): Name of the thing to watch. Can be the name of a collection or one of the "special" names listed below.
  • options.order: The sort order of an added collection array. Can be the name of any sortable object property. Default ordering is ascending; prepend name with - to sort descending. Default value is "-created".

Special watch names:

  • "currentUser" - Watches the currently logged in user. The property is set while a user is logged in, and undefined otherwise.
  • "status" - Watches the realtime connection status. Adds a string property that will change between values disconnected, connecting and connected.

promise

All appstax functions that perform asyncroneous actions return a promise. Use .then() and .fail() to handle the results when they come back.

promise.then(onSuccess)

Specify a success handler (and optionally a fail handler) for a promise.

  • onSuccess (function): Success handler

promise.then(onSuccess, onFail)

Specify a success handler (and optionally a fail handler) for a promise.

  • onSuccess (function): Success handler
  • onFail (function): Fail handler

promise.fail(onFail)

Specify fail handler for a promise. Equivalent to promise.then(undefined, onFail).

  • onFail (function): Fail handler

promise.progress(onProgress)

Specify progress handler for a promise. The progress handler will be called with a progress object that has a progress.percent property. See working with files for an example.

query

A query object to use in calls to object.find()

query.string(property).equals(value)

Include objects if a string property matches the given value.

  • property (string): Name of property
  • value (string): Value to match

query.string(property).contains(value)

Include objects if a string property contains the given value. Case insensitive.

  • property (string): Name of property
  • value (string): Value to search for

query options

Options available to calls like .find(), .findAll() and .search():

options.expand (int)

Depth of expansion. Expand all related objects for all relations the given number of levels deep.

options.expand (boolean)

Set to true to expand all related objects one level. Same as expand: 1. If false, no relation expansion will occur (default value.)

options.order (string)

Sort the resulting objects by this property. Prefix with - to sort objects in descending order (AngularJS style).

Example: -sysUpdated sorts the resulting objects by the property sysUpdated in descending order.

options.page (int)

Page the results, and return only the page number indicated by options.page. Value is zero-based, ie. {page: 0} indicates first page of result set.

Example: {page: 2} returns the page number 2 of the result set (ie. the third page). The default value for options.pageSize of 200 is used.

options.pageSize (int)

Page the results, and return each page with options.pageSize number of objects.

Example: {pageSize: 300} returns the first page and with a page size of 300 objects.

Example: {page: 2, pageSize: 300} returns the third page and with a page size of 300 objects.