this #

The current object is represented as this. You can always read its properties. Modifying its properties in an On Get request will change the result that the client receives, while modifying its properties in an On Post, On Put, or On Validate will change the value in the database.

// Example: On Validate
// If a property is too long, truncate it
if (this.message.length > 140) {
  this.message = this.message.substring(0, 137) + '...';
}

Note: In some cases, the meaning of this will change to something less useful inside of a function. If you are using functions such as Array.forEach(), you may need to bind another variable to this:

// Won't work - sum remains at 0
this.sum = 0;
this.targets.forEach(function(t) {
  this.sum += t.points;
});

//Works as expected
var self = this;

this.sum = 0;
this.targets.forEach(function(t) {
  self.sum += t.points;
});

me #

The currently logged in User from a User Collection. undefined if no user is logged in.

// Example: On Post
// Save the creator's information
if (me) {
    this.creatorId = me.id;
    this.creatorName = me.name;
}

isMe() #

isMe(id)

Checks whether the current user matches the provided id.

// Example: On Get /users
// Hide properties unless this is the current user
if (!isMe(this.id)) {
    hide('privateVariable');
}

// Example: On Put
// Make sure that only the creator can edit a post
cancelUnless(isMe(this.id), "You are not authorized to edit that post", 401);

query #

The query string object. On a specific query (such as /posts/a59551a90be9abd8), this includes an id property.

// Example: On Get
// Don't show the body of a post in a general query
if (!query.id) {
  hide(this.body);
}

cancel() #

cancel(message, [statusCode])

Stops the current request with the provided error message and HTTP status code. Status code defaults to 400. Commonly used for security and authorization.

It is strongly recommended that you cancel() any events that are not accessible to your front-end, because your API is open to anyone.

// Example: On Post
// Don't allow non-admins to create items
if (!me.admin) {
  cancel("You are not authorized to do that", 401);
}

Note: In a GET event where multiple values are queried (such as on /posts), the cancel() function will remove the current item from the results without an error message.

cancelIf(), cancelUnless() #

cancelIf(condition, message, [statusCode])
cancelUnless(condition, message, [statusCode])

Calls cancel(message, statusCode) if the provided condition is truthy (for cancelIf()) or falsy (for cancelUnless()).

Example: On Post
// Prevent banned users from posting
cancelUnless(me, "You are not logged in", 401);
cancelIf(me.isBanned, "You are banned", 401);

error() #

error(key, message)

Adds an error message to an errors object in the response. Cancels the request, but continues running the event so it can collect multiple errors to display to the user. Commonly used for validation.

// Example: On Validate
// Don't allow certain words
// Returns response {"errors": {"name": "Contains forbidden words"}}
if (!this.name.match(/(foo|bar)/)) {
  error('name', "Contains forbidden words");
}

errorIf(), errorUnless() #

errorIf(condition, key, message)
errorUnless(condition, key, message)

Calls error(key, message) if the provided condition is truthy (for errorIf()) or falsy (for errorUnless()).

// Example: On Validate
// Require message to be a certain length
errorUnless(this.message && this.message.length > 2, 'message', "Must be at least 2 characters");

hide() #

hide(property)

Hides a property from the response.

// Example: On Get
// Don't show private information
if (!me || me.id !== this.creatorId) {
  hide('secret');
}

protect() #

protect(property)

Prevents a property from being updated. It is strongly recommended you protect() any properties that should not be modified after an object is created.

// Example: On Put
// Protect a property
protect('createdDate');

// Example: On Put
// Only the creator can change the title
if (!(me && me.id === this.creatorId)) {
  protect('title');
}

changed() #

changed(property)

Returns whether a property has been updated.

// Example: On Put
// Validate the title when it changes
if(changed('title') && this.title.length < 5) {
  error('title', 'must be over 5 characters');
}

previous #

An Object containing the previous values of the item to be updated.

// Example: On Put
if(this.votes < previous.votes) {
  emit('votes have decreased');
}

emit() #

emit([userCollection, query], message, [data])

Emits a realtime message to the client.

// Example: On Post
// Alert clients that a new post has been created
emit('postCreated', this);

In the front end:

// Listen for new posts
dpd.on('postCreated', function(post) {
    //do something...
});

You can use userCollection and query parameters to limit the message broadcast to specific users.

// Example: On Put
// Alert the owner that their post has been modified
if (me.id !== this.creatorId) {
  emit(dpd.users, {id: this.creatorId}, 'postModified', this);
}

See Notifying Clients of Changes with Sockets for an overview on realtime functionality.

internal #

Equal to true if this request has been sent by another script.

// Example: On GET /posts
// Posts with a parent are invisible, but are counted by their parent
if (this.parentId && !internal) cancel();

dpd.posts.get({parentId: this.id}, function(posts) {
    this.childPosts = posts.length;
});

isRoot #

Equal to true if this request has been authenticated as root (has the dpd-ssh-key header with the appropriate key; such as from the dashboard)

// Example: On PUT /users
// Protect reputation property - should only be calculated by a custom script.

if (!isRoot) protect('reputation');

console.log() #

console.log([arguments]...)

Logs the values provided to the command line. Useful for debugging.

$inc #

The $inc command increments the value of a given Number property.

// Give a player 5 points
{
  score: {$inc: 5}
}

$push #

The $push command adds a value to an Array property.

// Add a follower to a user by storing their id.
{
  followers: {$push: 'a59551a90be9abd8'}
}

$pushAll #

The $pushAll command adds multiple values to an Array property.

// Add mentions of users
{
  mentions: {
    $pushAll: ['a59551a90be9abd8', 'd0be45d1445d3809']
  }
}

$pull #

The $pull command removes a value from an Array property.

// Remove a user from followers
{
  followers: {$pull: 'a59551a90be9abd8'}
}

Note: If there is more than one matching value in the Array, this will remove all of them

$pullAll #

The $pullAll command removes multiple values from an Array property.

// Remove multiple users
{
  followers: {$pullAll: ['a59551a90be9abd8', 'd0be45d1445d3809']}
}

Note: This will remove all of the matching values from the Array

dpd.on(message, fn) #

The dpd.on(message, fn) function listens for realtime messages emitted from the server. See Notifying the Client of Changes for information on sending realtime messages with the emit() function.

• message - The name of the message to listen for
• fn - Callback function(messageData). Called every time the message is received. There is no error argument.

// Listen for a new todo
dpd.on('todos:create', function(post) {
  // Do something
});

In your Collection Event:

// On Post
emit('todos:create', this);

Calling .on() on the collection itself will namespace the message by the collection name:

// Same as dpd.on('todos:create', fn)
dpd.todos.on('create', function(post) {
  // Do something
});

dpd.off(message, [fn]) #

The dpd.off(message) function stops listening for the specified message.

dpd.off('todos:create');

You can also provide a function that was originally set as a listener to remove only that function.

function onTodoCreated(post) {
  // Do something
}

dpd.on('todos:create', onTodoCreated);

dpd.off('todos:create', onTodoCreated);

Calling .off() on the collection itself will namespace the message by the collection name:

// Same as dpd.off('todos:create');
dpd.todos.off('create');

dpd.once(message, fn) #

The dpd.once(message, fn) function listens for a realtime message emitted by the server and runs the fn callback exactly once.

dpd.once('todos:create', function(post) {
  // Do something
});

Calling .once() on the collection itself will namespace the message by the collection name:

// Same as dpd.once('todos:create');
dpd.todos.once('create', function(post) {
  // Do something
});

dpd.socketReady(fn) #

The dpd.socketReady(fn) function waits for a connection to be established to the server and executes the fn callback with no arguments. If a connection has already been established, it will execute the fn callback immediately.

It can sometimes take a second or more to establish a connection, and messages sent during this time will not be received by your front end. This function is useful for ensuring that you will receive an message when it is broadcast.

dpd.socketReady(function() {
  // Do something
});

dpd.socket #

The dpd.socket object is a socket.io object. This is useful if you want to finely control how messages are received.