Fuse Guide

Create cross platform mobile apps with AppStax and Fuse

Introduction

Fuse is a great tool for designing and building cross platform mobile apps for iOS and Android. This guide describes how to use the AppStax services to handle users and data within your Fuse app.

Our support for Fuse in the AppStax platform and SDK's is experimental. Fuse itself is in beta and their tools and API's may change in the future.

Note that you can use AppStax to create native apps for iOS and Android without using Fuse. If this is is what you want, take a look our iOS Guide and Android Guide.

QuickStart

If you just want to take a peek at what you can do with AppStax and Fuse, take a look at one of our QuickStart projects. You don't need to sign up to use them:

Before you start

You need a few things to work with Fuse and AppStax:

If you are new to Fuse, you may also want to look at their Guide and Examples.

Starting a new project

If you are creating a new project from scratch you can use the files in starterproject/basic as the starting point. Remember to insert your app key in the call to appstax.init() in MainView.ux.

Using AppStax in an existing project

You will find all the neccesary files in the starterproject/basic folder. Here's how you use them:

Files to add

  • Copy the WebSocket folder to the root of your project structure
  • Copy the appstax.js file to the root of your project

Update the .unoproj file

Add these to your Includes array:

"WebSocket/*",
"WebSocket/ios/*.h:ObjCHeader:iOS",
"WebSocket/ios/*.m:ObjCSource:iOS",
"WebSocket/android/*.java:Java:Android"

There is an example of a working .unoproj file here.

Import appstax.js and initialize it

Add these two lines in your main .ux file, after the opening <App> tag:

<JavaScript File="WebSocket/WebSocket.js" />
<JavaScript File="appstax.js" ux:Global="appstax" />

Add an empty <JavaScript> tag (if you don't already have one), and add these two lines inside it:

var appstax = require("appstax");
appstax.init("<<appstax-app-key>>");

Replace <<appstax-app-key>> with your own app key from the AppStax Admin UI. You can find a complete example of a .ux file with AppStax here.

Working with objects

Create & save objects

Say we want to crate a public message board. To send a message we just write the following code:

var message = appstax.object("messages");
message.text = "Hello World!";
message.save();

In line 1, we create an object that will be stored to the messages collection. Line 2 sets the `text property of our new object. And in line 3 we save the object to the Appstax server.

Before you can create objects from code you must define your collection using the Admin UI. So, to start saving message objects to Appstax you must first log on to the Admin UI and create a collection named "messages" and add a column "text" with type string.

Remember that collection names are case sensitive, so a collection named Messages won't match appstax.object("messages")

Asynchronous communication & promises

The message.save() call in the previous example kicks off an asynchronous HTTP call to the server and immediately returns control to your next line of code in order to avoid blocking your UI.

If you want to know when the save has completed, you can use the returned promise with a call to .then():

message.save()
       .then(function() {
           // ... object has been saved
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

Load all objects in a collection

If you want to load all the objects of a collection you just:

appstax.findAll("messages")
       .then(function(objects) {
           // ... objects is an array of all the messages
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

Using the returned objects

The returned array of objects is not further managed by appstax, and you can use it in any way you like. You could loop through and access its properties:

appstax.findAll("messages")
       .then(function(objects) {
           for(var i = 0; i < objects.length; i++) {
               var text  = objects[i].text;
               // ... and do something interesting with the text
           }
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

Often you will want to update an Observable with the results in then().

var Observable = require('FuseJS/Observable');
var messages = Observable();

appstax.findAll("messages")
       .then(function(objects) {
           // update the Observable:
           messages.replaceAll(objects);
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

// export the observable to use in the UI
module.exports = {
    messages: messages
}

You can read more about Observable in the Fuse docs.

Object id

The id of an object is accessible in a read-only property object.id:

var object = appstax.object("messages");
console.log(object.id); // object.id is null before it has been saved

object.save()
      .then(function(object) {
          console.log(object.id); // object.id matches the sysObjectId
                                  // column in the databrowser.
      })
      .fail(function(error) {
          // Request failed. error.message contains 
           // explanation of what went wrong
      });

Load a single object

For loading a single object the following lines will do:

appstax.find("messages", "1234")
       .then(function(object) {
           // ... object with id "1234"
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

Remove an object

Just call remove and it will be deleted from your datastore:

message.remove()
       .then(function() {
           // ... object has been removed
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

Refresh an object

If you already have an object but the data may have changed on the server, you can refresh it:

message.refresh()
       .then(function() {
           // ... the message object has been updated
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

This works the same way for find(), findAll() and remove() too.

Querying Objects

There are several ways to find a selection of objects in a collection. We provide a generic find() that can be used for any request, and more specific methods for the most common use cases.

Matching property values

You can specify the properties and values to match:

appstax.find("friends", {gender:"male", hometown:"Oslo"})
       .then(function(objects){
           // objects contain all male friends from Oslo
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

... or you can use the generic query function:

appstax.find("friends", function(query) {
    query.string("gender").equals("male");
    query.string("hometown").equals("Oslo");
}).then(function(objects) {
    // objects contain all male friends from Oslo
}).fail(function(error) {
    // Request failed. error.message contains 
    // explanation of what went wrong
});

Searching string values

If you want your users to search your data you can use search() and provide the string values to search for:

appstax.search("friends", {description:"music"})
       .then(function(objects){
           // objects contain friends with 
           // 'music' in their description
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });

... or you can use the generic query function:

appstax.find("friends", function(query) {
    query.string("description").contains("music");
}).then(function(objects) {
    // objects contain friends with 'music' in their description
}).fail(function(error) {
    // Request failed. error.message contains 
    // explanation of what went wrong
});

You can also easily search for the same value in many properties at once:

appstax.search("articles", "music", ["title", "content", "tags"])
       .then(function(objects){
           // objects contain articles with 'music' 
           // in title, content or tags
       })
       .fail(function(error) {
           // Request failed. error.message contains 
           // explanation of what went wrong
       });