Basic Use #

Double-click in a cell to start editing. Press Enter to save your changes, or Escape to cancel and undo your changes.

While editing a string property, click the "edit" icon next to the field to open up a multiline editor.

Click the trash can icon in any row to delete it.

Edit the bottom-most row to create a new object. Press Enter when editing a property to save the row, or click the checkmark in the margin.

Useful Shortcuts #

• Use the arrow keys to move your selection without using the mouse.
• Press "Enter" when a cell is selected to start editing.
• Start typing when a cell is selected to overwrite its existing value.
• If you accidentally save a change, press Ctrl/Cmd-Z to reverse it.
• Press Ctrl-Delete to remove a row. Press Ctrl/Cmd-Z to add it back. (heads up: it will have a different id)
• Press Ctrl-Enter to open up the multiline editor for a string property; this lets you write long text values.
• Press Ctrl-Enter while in the multiline editor to save it (pressing Enter will just create a new line)
• Press Tab to save the current property and edit the next one.

Basics #

All we need to create a collection client is a constructor and a single method for making requests.

var request = require('request');

function Collection(url) {
  this.url = url
}

Collection.prototype.request = function (options, fn) {
  var url = this.url;
  options.url = url + (options.url || '');  
  request(options, function (err, res, body) {
    if(res.statusCode >= 400) {
      err = body || {message: 'an unknown error occurred'};
      return fn(err);
    }

    fn(null, body);
  });
}

Now we can construct new collections by passing the URL as the only argument to our constructor.

var c = new Collection('http://foo.deploydapp.com/todos');

c.request({url: '?done=false'}, function(err, todos) {
  console.log(todos); // [...]
});

We can add an object to our collection by passing an object as the json body and setting the method to "POST".

var todo = {
  title: 'wash the car'
};

c.request({json: todo, method: 'POST'}, function(err, todo) {
  console.log(todo); // {id: '...', ...}
});

To update an object we just need to set the method to "PUT".

var todo = {
  id: '06a5254f11ff7853',
  done: true
};

c.request({json: todo, method: 'PUT'}, function(err, todo) {
  console.log(todo); // {id: '...', ...}
});

Deleting an object requires an ID and the method must be set to "DELETE".

var id = '06a5254f11ff7853';

c.request({url: '/' + id, method: 'DELETE'}, function(err, todo) {
  console.log(err); // null - if no error occurred
});

Listening to Events #

The simplest way to listen events is to use a Socket.IO client. You can find a list of clients here.

Using the node.js Socket.IO client, we can create a socket by connecting to our deployed app. Then calling the socket's on() method to listen to a custom event emitted by a collection.

var io = require('socket.io-client');
var socket = io.connect('http://foo.deploydapp.com');

socket.on('my event', function (data) {
  console.log(data); // emit()ed from the server
});

Embedding Data #

Deployd allows your collection to store complex structures such as nested objects or arrays. This is useful if you want to embed data inside your collection's objects. Keep in mind this is only recommended when the embedded data is not likely to change. For example, a blog-posts collection could have an author property with a type set to Object.

{
  "title": "Foo Bar Bat Baz?",
  "author": {
    "name": "Joe Bob",
    "id": "5ef0f7d515764998"
  }
}

This style of relationship allows users of the collection to display the name of the author without running any other queries. The downside is an update event is required to keep the author name in sync if it ever changes. If your data changes often, this may not be the best approach.

Contains Many or One-to-Many #

Similarly to storing nested objects in your collection, you can also store arrays of arbitrary JSON. This is useful when you want to setup a contains relationship. For example, in a gradebook application, your classes collection objects could contain students.

{
  "title": "Language Arts",
  "students": ["5ef0f7d515764998", "5ef0f7d515764531", ...] 
}

By storing an array of student ids you can easily query classes by student.

dpd.classes.get({students: '5ef0f7d515764998'}, function(classes) {
  console.log(classes); // [...] - all the classes the student is in.
});

Many-to-Many #

There are several ways to handle many-to-many relationships. The most common way is to include an Array property that stores the ids of the related objects on both collections.

Continuing with the gradebook example, a student may have many classes, and a class may have many students. The classes collection would have a students Array property containing the student ids and the students collection would have a classes Array property containing class ids.

This lets you query each collection to get the students in a class or the classes a student is taking by providing the id of the class or student.

dpd.students.get({id: {$in: class.students}}, function(students) {
  console.log(students);
}); 

// or

dpd.classes.get({id: {$in: student.classes}}, function(classes) {
  console.log(classes);
});

If you wanted to include the full objects when querying the API you could implement a simple GET event.

// on GET /students

if(query.include === 'classes') {
  dpd.classes.get({id: {$in: student.classes}}, function(classes) {
    this.classes = classes;
  });
}

Then if you added the include param when querying from the browser, a student would come back with all of its classes.

dpd.students.get({id: '2ef0f7d515764991', include: 'classes'}, fn);

would output

{
  "id": "2ef0f7d515764991",
  "name": "Joe Bob",
  "classes": [{
    "id": "...",
    "title": "Language Arts"
  }, ...]
}

Parent-Child #

Some collections contain objects related to other objects in the same collection. A simple example of this is threaded comments. Where a comment can be in reply to another comment, creating a tree-like structure when rendered.

To accomplish this, all you need is a parent property containing the id of a parent object if one exists. Since Deployd supports recursive queries in a collection's GET event, the following works as you would expect.

// on GET /comments
var comment = this;

dpd.comments.get({parent: comment.id}, function(comments) {
  if(comments && comments.length) comment.children = comments;
});

Running the following query from the browser would result in a nested structure of all possible comments:

// from the browser
dpd.comments.get({id: '2ef0f7d515764991'}, console.log);

would output

{
  "id": "2ef0f7d515764991"
  "text": "Hello, World!",
  "children": [
    {
      "id": "tef0f7d515761234",
      "text": "Foo bar...",
      "children": [
        {
          "id": "ff00f7d515764642",
          "text": "I agree!"
        },
        {
          "id": "2200f7d51576123",
          "text": "I do not agree!"
        },
      ]
    }
  ]
}

If you expect that a query could become an infinite loop (or if it already is an infinite loop; a good sign of this is requests that time out before returning a result), put a $limitRecursion property on your query with the maximum number of levels to iterate:

// on GET /comments
var comment = this;

dpd.comments.get({parent: comment.id, $limitRecursion: 10}, function(comments) {
  if(comments && comments.length) comments.children = comments;
});

Realtime API #

Deployd uses Socket.io for its realtime functionality. If you are not using dpd.js, you can use the Socket.io client library.

var socket = io.connect('/');
socket.on('todos:create', function(todo) {
  // Do something
});

The Socket.io community has created client libraries for other languages and platforms as well.

Root Requests #

You can elevate your session to root access by adding the header dpd-ssh-key. It must have the value of your app's key (you can find this by typing dpd showkey into the command line); although in the development environment, the dpd-ssh-key header can have any value.

Sending a request as root has several effects. Most notably, you can use the {$skipEvents: true} property in either the query string or request body. This will cause events not to run. This is useful for bypassing authentication or validation.

Your front-end app should never gain root access, and you should never store the app's key in a place where it can be accessed by users, even if they understand the system. This is primarily useful for writing data management utilities for yourself, other developers, and system administrators.

Examples #

The examples below show how to use various JavaScript front-end libraries to access a Collection called /todos.

$.ajax('/todos', {
  type: "GET",
  success: function(todos) {
    // Do something
  },
  error: function(xhr) {
    alert(xhr.responseText);
  }
});

$.ajax('/todos', {
  type: "POST",
  contentType: "application/json",
  data: JSON.stringify({
    title: "Walk the dog"
  }),
  success: function(todo) {
    // Do something
  }, 
  error: function(xhr) {
    alert(xhr.responseText);
  }
});

var Todo = Backbone.Model.extend({});
var Todos = Backbone.Collection.extend({
  model: Todo,
  url: "/todos"
});

var todos = new Todos();  

todos.fetch({
  success: function(collection, response) {
    // Do something
  }, error: function(collection, response) {
    alert(response);
  }
});

todos.create({
  title: "Walk the dog"
}, {
  success: function(collection, response) {
    // Do something
  }, error: function(collection, response) {
    alert(response);
  }
});

function Controller($scope, $http) {
  $http.get('/todos')
    .success(function(todos) {
      $scope.todos = todos;
    })
    .error(function(err) {
      alert(err);
    });

  $http.post('/todos', {
      title: "Walk the dog"
    })
    .success(function(todo) {
      // Do something
    })
    .error(function(err) {
      alert(err);
    });
}

var myApp = angular.module('myApp', ['ngResource']);

myApp.factory('Todos', function($resource) {
  return $resource('/todos/:todoId', {todoId: '@id'});
});

function Controller($scope, Todos) {
  $scope.todos = Todos.query(function(response) {
    // Do something
  }, function(error) {
    alert(error);
  });

  Todos.save({
    title: "Walk the dog"
  }, function(todo) {
    // Do something
  }, function(error) {
    alert(error);
  });
}

myApp.controller('Controller', Controller);

Origin, Accept, Accept-Language, Content-Language, Content-Type, Last-Event-ID

// Logging a user in.
$.ajax({
  url: 'http://<domain>:<port>/users/login',
  type: "POST",
  data: {username:"un", password:"pw"},
  cache: false,
  xhrFields:{
    withCredentials: true
  },
  success: function(data) {
    console.log(data);
  },
  error: function(xhr) {
    console.log(xhr.responseText);
  }
});

// On subsequent requests or in the success callback above.  (After having logged in) 
$.ajax({
  url: 'http://<domain>:<port>/<collection>',
  type: "GET",
  cache: false,
  xhrFields:{
    withCredentials: true
  },
  success: function(data) {
    console.log(data);
  },
  error: function(xhr) {
    console.log(xhr.responseText);
  }
});

URL       : ?_method=METHOD_NAME or
JSON body : { _method: 'METHOD_NAME' }

$.ajax({
  type : "POST",
  url  : "/todos/OBJECT_ID"
  data : { _method:"DELETE" },
  success: function(todo) {
    // Object was deleted. response body empty.
  }, 
  error: function(xhr) {}
});

or

$.ajax({
  type : "POST",
  url  : "/todos/OBJECT_ID?_method=DELETE",
  success: function(todo) {
    // Object was deleted. response body empty.
  }, 
  error: function(xhr) {}
});

Query commands #

Query commands apply to the entire query, not just a single property.

    // Exclude the "email" property
    {
        $fields: {email: 0}
    }

    // Only include the "title" property
    {
        $fields: {title: 1}
    }

// Get all public posts and all posts by a specified user (even if those are private)
{
    $or: [{
      isPublic: true
    }, {
      creator: "Bob"
    }]
}

// Sort posts by likes, descending
{
    $sort: {likes: -1}
}

// Return the top 10 scores
{
    $sort: {score: -1},
    $limit: 10
}

// Return the third page of posts, with 10 posts per page
{
    $skip: 20,
    $limit: 10
}

Callbacks #

Every function in the Collection API takes a callback function (represented by fn in the docs) with the signature function(result, error).

The callback will be executed asynchronously when the API has received a response from the server.

The result argument differs depending on the function. If the result failed, it will be null and the error argument will contain the error message.

The error argument, if there was an error, is an object:

• status (number): The HTTP status code of the request. Common codes include:
  • 400 - Bad Request: The request contained invalid data and could not be completed
  • 401 - Unauthorized: The current session is not authorized to perform that action
  • 500 - Internal Server Error: Something went wrong on the server
• message (string): A message describing the error. Not always present.
• errors (object): A hash of error messages corresponding to the properties of the object that were sent - usually indicates validation errors. Not always present.

Examples of errors:

{
  "status": 401,
  "message": "You are not allowed to access that collection!"
}

{
  "status": 400,
  "errors": {
      "title": "Title must be less than 100 characters",
      "category": "Not a valid category"
  }
}

Promises #

Every function in the collection API returns a promise. We use the ayepromise library (which follows the Promises/A+ 1.1 specs). To learn how to use promises, please, refer to this article.

The first callback contains the same result same with the classic callbacks. The second callback contains the error object as described above. Here's an example to use promises within dpd.js:

dpd.todos.post({message: "Hello world"}).then(function(todo) {
  // do something with todo
  console.log(todo); // display {id: "###", message: 'Hello world'}
}, function(err) {
  // do something with the error
  console.log(err); // display an error if the request failed
});

dpd.todos.get('1234324324').then(function(todo) {
  // do something with todo
  console.log(todo); // display {id: "###", message: 'Hello world'}
}, function(err) {
  // do something with the error
  console.log(err.errors.message); // display the error message
});