RABJ Library - Documentation

Introduction

The RABJ Library wraps up a lot of functionality needed for implementing simple data-entry games such as typewriter and genderizer. This library includes both server-side code (that interfaces with the RABJ web service) and client-side code (that handles interactions and carries out AJAX operations).

RABJ in a Nutshell

RABJ is a service that stores and manages collections of tasks and users' responses to those tasks. In RABJ lingo, collections are `queues`, tasks are `questions` and user responses are `judgments`. RABJ exposes a REST API for creating and interacting with each of these structures. RABJ is provided by Metaweb for, among other purposes, implementing data games. For more information, including detailed technical documentation, see XXXXX.

As a developer of a data game, here's what you need to know about RABJ:

• A RABJ queue can be created and loaded with questions using the API
• Queues may define the number of votes required per question
• Queues are persistent, while the questions on it are ephemeral
• Once answered by a particular user, a question will never be see by that user again.
• Once answered by enough users to be considered complete, a question will never be seen by a user again.

The two basic API entrypoints to RABJ are:

• /question: Fetch a question from a particular queue and a particular user
• /answer: Register a judgment by a particular user

Data Flow

The library comes in two parts: a client-side Javascript library that sits in your browser and controls the UI, and a server-side ACRE library that acts as an interface to RABJ. The diagram below shows the important paths data flows along.

A data-game ACRE app must provide two parallel entrypoints to the client-side library:

• /task: Fetches a question for this user through the server-side library and renders it using task-template.
• /vote: Answers a question for this user through the server-side library.

/task is called asynchronously by the client-side library every time a new question needs to be displayed (or prefetched). Likewise, /vote is called every time a question is answered through the UI. The client-side library does not communicate directly with the server-side library to give application developers greater control over the data. The ability to "intercept" data passing between and act in application-specific ways may be important in some apps.

Features

More specifically, the library implements the following functionalities:

Server-Side

1. Retrieving a RABJ queue given a set of tags describing it.
2. Retrieving tasks from a RABJ queue, optionally extending the task with more data given an eMQL query, and optionally rendering the task into an HTML blob given a template file. See sample usage.
3. Submitting user judgments to the RABJ service. When a vote is submitted successfully, an optional callback is invoked (ex. to do MQL writes specific to your application). See sample usage.
4. Retrieving and rendering leaderboards, both all-time and weekly. (IN PROGRESS) See sample usage.
5. Rendering the logged-in user information, useful in the application's header. See sample usage.
6. Miscellaneous: determining whether the user is using an iPhone.

Client-Side

Client-side functionalities are wrapped into a single class called TaskQueue. There are also supporting CSS and image files.

1. AJAX operations involving fetching tasks and submitting votes.
2. Handling keyboard shortcuts.
3. Animating tasks that just get voted and other visual cues.
4. Buffering voted tasks before submitting them in order to support undo.
5. Recording input methods (mouse, key, touch) and timing information per task.(IN PROGRESS)

Structuring A Simple Application

To create an application using this library, it is best to clone the deTypewriter app and change it.

Template Files

In deTypewriter, there are 4 template files (IN PROGRESS) (plus their mobile counterparts):

1. header: renders the header pane for all pages in the app.
2. index: renders the home page of the app, showing leaderboards and links to various queues.
3. queue: is the page in which the user actually plays.
4. task-template: renders the HTML fragment for each task.

Client-side Script Files

deTypewriter contains a single script file called queue-js that calls the client-side part of the library. This file instantiates a TaskQueue with application-specific settings. The functions vote and flipHandedness are called from within the HTML fragments generated by task-template.

Server-side Script Files

The files task and vote call the Task Queue library as but are allowed to do application-specific work.

Queries and Tags

deTypewriter has several type-based queues (people, movies, etc), each of which can be activated by a URL parameter to queue, as in queue?question-tags=/film/film.

deTypewriter also has a pseudo-query file called query-task-options that contains options for the library as it retrieves tasks from RABJ. This file contains a uMQL query that retrieves the article blurb of the task's topic as well as the topic's images. (More information on eMQL.)