Travis CI build status

concrete-js

concrete-js is a JavaScript library for working with Concrete, a set of NLP data types defined by a Thrift schema. Thrift makes it easy to use a shared set of data structures across multiple programming languages.

concrete-js is designed for visualization and annotation. While it is technically possible to implement NLP algorithms in JavaScript, you should instead use concrete-python or concrete-java.

In general, you should use concrete-js when you have a Concrete Communication object that was created by another tool, and need a UI that visually represents data in the Communication. You may also need the user/annotator to interactively modify Concrete data structures, and then save their modifications.

The concrete-js library contains:

  • Serialization and deserialization code for Concrete data structures. The serialization code is generated by the Thrift compiler from the Thrift schema for Concrete.
  • Utility code for working with Concrete objects
  • Visualization code that maps Concrete data structures to DOM elements using jQuery

API documentation for concrete-js is available at: http://hltcoe.github.io/concrete-js/

Including concrete-js in your project

In order to use concrete-js, you will need jQuery version 1.9 or later, and the files dist/thrift.js and dist/concrete.js. You do not need any of the files in the src/ directory. Those files are concatenated together to create dist/concrete.js.

In your HTML file, you should include the scripts in this order:

<script src="your/copy/of/jquery.js"></script>
<script src="thrift.js"></script>
<script src="concrete.js"></script>

Fetching Communications with JavaScript

There are two primary ways to load Concrete Communications into JavaScript - Thrift RPC (Remote Procedure Calls) and HTTP GET requests for JSON serialized Communications. The JavaScript version of Thrift only supports the TJSONProtocol serialization protocol.

The Communication class in concrete-js has been extended with some helper functions for working with TJSONProtocol. Here is an example of how to retrieve a JSON-serialized Communication with a GET request using jQuery:

  // When the page has loaded...
  $(document).ready(function() {
    // ...make an HTTP GET request to retrieve a JSON-serialized Communication...
    $.getJSON('dog-bites-man.concrete.json', function(commJSONData) {
      // ...and call this (unnamed) callback function with the JSON data.

      // Create an empty Concrete Communication object
      var commOne = new Communication();

      // Load JSON-serialized Communication data into Communication object
      commOne.initFromTJSONProtocolObject(commJSONData);

The examples/index.html file uses this technique to retrieve a Communication.

concrete-js provides functions that serialize and deserialize Communication objects using TJSONProtocol:

var comm = new Communication();
var comm_as_json_object = comm.toTJSONProtocolObject();
var comm_as_json_string = comm.toTJSONProtocolString();

var comm2 = new Communication();
comm2.initFromTJSONProtocolObject(comm_as_json_object);

var comm3 = new Communication();
comm3.initFromTJSONProtocolString(comm_as_json_string);

Building concrete-js

You do not need to build concrete-js in order to use concrete-js - a working copy of the library is included in the dist/ directory. The concrete-js library only needs to (re)built when the Thrift schema files for Concrete have been updated, or when the code in src/ is modified.

Requirements for building concrete-js:

  • A copy of the Concrete repo in your home directory - ${HOME}/concrete
  • Thrift
  • Node
  • Grunt - a JavaScript build tool

Install the Node packages required for building concrete-js using:

npm install

Build concrete-js using the command:

grunt

which will:

  • call the Thrift compiler to generate JavaScript code for the Thrift schema under ${HOME}/concrete
  • combine the Thrift-generated JavaScript code with the hand-written utility function JavaScript code
  • run JSHint on the combined JavaScript code to check for problems
  • minify the combined code
  • download the latest version of thrift.js from the Apache Thrift repository