Setting up Baqend is really simple. Just include the Baqend SDK in your HTML with

<script src="http://www.baqend.com/js-sdk/latest/baqend.min.js">
</script>

then call DB.connect("toodle") to connect to the tutorial's Baqend app. If you want to connect the tutorial app to your own Baqend app, start a free cloud-hosted Baqend app and use "<your app name>" in the connect method. Once connected, DB.ready is called and you can start loading and saving data. The Baqend JS SDK works in all major browsers, HTML5/hybrid apps as well as Node.js servers.

In this tutorial, we are going to build a sharable todo list, that can track the time spent on each todo. Below you can try, modify and extend each tutorial step against a real Baqend instance. The code is written in ES6, the new JavaScript standard and pre-compiled by Babel below. Baqend is of course compatible with older JavaScript versions, too.

When developing with Baqend you create the major part of the application logic in JavaScript code that uses the Baqend SDK to load and save data, authenticate users, etc. Your application assets (HTML, CSS, JS, images, etc.) can be hosted on Baqend, too. This pattern of fetching HTML, CSS and JS resources once and then rendering data on the client is called Single-page application.

This tutorial uses a shared Baqend application (toodle) focusing on the API. When you create a Baqend account you get your own instance with a web dashboard, where you can specify data models, upload files and server-side business logic, etc.

Before starting to implement, let's create the data model of our sharable Todo list with time-tracking. This schema is quickly created using the dashboard — we've already done that for this tutorial:

The explicit schema has the advantage that all data is automatically validated to prevent corrupt data. Also this gives us clever DB.Todo objects to program against. Schemas, i.e. the data models, are flexible and can be changed at any time. Let's instantiate a Todo to see its properties.

To save a Todo we simply call save() on the instance. If no id was defined, it gets assigned a random one.

Baqend objects are Active Records, i.e. they expose methods to save, update and delete the respective object. save() and the other methods return ES6 Promises. The application can easily react to success and failure:

myTodo.save().then((object) => {
   //This function is called on success
}, (error) => {
   //This one on error
});

Besides then(myFunction) you can also use catch(myFunction) (error). All Baqend methods returning Promises also allow callback parameters. Let's persist a todo and show the id it gets assigned.

Loading data is really easy. If we know the id of an object, we can load it with:

DB.Todo.load(id)
  .then((todo) => {
    //Do something with the todo
});

The great thing when working with objects in Baqend is that whenever you load objects that are already used somewhere in your application, you will get the same references. This means that you do not have to deal with different states of objects — it's always the same object.

When an object does not exist or we do not have the permission to read it, load will return null. To manually refresh an object, we can call myTodo.load({refresh: true}) which updates our local copy with the newest version from the server.

If we do not know the ids, we use queries to specify which objects we are looking for. The following query for instance gets us all the Todos in a specific list that are not marked as done:

DB.Todo.find()
    .equal("listId", "myList")
    .notEqual("done", true)
    .resultList().then(myCallback); //Returns a list of matching objects 

resultList returns all matching objects, whereas singleResult only returns the first match.

Baqend supports many query operators, which allow very sophisticated lookups, including ordering, geospatial queries, text search and boolean combinations of query predicates.

Updates and inserts are performed via save ("upsert") or explicitly via update and insert.

If at the time of the update the local copy was outdated, the operation will result in an error. Baqend automatically versions all objects to detect concurrent changes and stale data. In the error callback of save we can refresh the object with myTodo.load() and retry the update or decide to overwrite the newer version at the server with our older version using the force parameter.

myTodo.save({
  force : true //Overwrite even if our copy is outdated
});

When objects reference each other, we can control, up to which depth referenced objects should also be persisted using the depth parameter (persistence-by-reachability).

If we want to get rid of an object, we do a myTodo.delete(). delete has the same options as save and behaves similarly. Let's add saving and deleting to the app.

Let's add a final improvements to our Todo app: a decent view. Baqend objects are perfectly compatible with frameworks such as Angular.js, Backbone.js, Knockout and React.js. For the sake of simplicity we use Handlebars in this tutorial.

To keep track of each working period, we maintain a list of DB.Activity objects. Activity is an embedded object, i.e. it only exists in the context of its outer DB.Todo object and has no own id. Adding activities to a list is simple:

var activity = new DB.Activity({start: new Date()});
todo.activities.unshift(activity);  //Start work
todo.activities.get(0).end = new Date(); //Stop work

Collections, i.e. Lists, Sets and Maps are first-level citizens in Baqend and a powerful way to model complex data and relationships between objects.

Finally, to implement the sharing of Todo lists, we track the list Id in the hashtag of the URL and generate a random list id for first-time visitors. To fork the complete Todo App and start hacking click here. It is also on Github.

The tutorial demonstrated the central concepts of working with Baqend. Of course Baqend can do much more:

  • Data Modelling: There are many types, e.g. GeoPoints and references.
  • Advanced Queries: sort and filter using complex predicates.
  • User Authentication: Login and register users with email and OAuth.
  • Push Notifications: Send mobile push notifications to Android and iOS.
  • Business Logic: Execute server-side Node.js code.
  • Handlers: Create, Read, Update, Delete methods can be intercepted and enhanced at server-side, e.g. to perform validation.
  • Authorization: Baqend has a fine-grained Access Control List (ACL) system for classes and individual objects.
  • Logging: Custom logging allows you to track down bugs an perform analytics.
  • Files: You can host files on Baqend and also upload and download via an API.

Start your own free Baqend instance using the Baqend cloud-service now. The final tutorial app is on a Github repo with instructions how to set it up.

Resources:

Quickstart

5 min walk-through of setting up a Baqend-connected web project.

Starter Kits

No need to build everything from scratch. Use the Baqend + Angular starter project.

Development Guide

The guide covers the Baqend JavaScript SDK in depth.

View Tutorial Step on CodePen