API Details

The plugin is intended to work with any application, client or server side, that can respond to an request using the following variables.

Request

Variables

Prefix variables with "&", postfix with "=", see examples.

Row/column metadata

row_labels - [(true)/false] - return row labels for window requested, true when not provided
column_labels - [(true)/false] - return column labels for window request, true when not provided

Window defining

row1=int,row2=nil,col1=nil,col2=nil            -> return all cells in the row defined by row1
row1,row2                                  -> return the rows in range row1-row2 (inclusive)
col1                                     -> return all cells in this column    
col1,col2                                  -> return the columns in range col1-col2
row1,col1                                  -> return the cell at row1,col1
row1,col1,row2,col2                            -> return the cells bound by (row1,col1), (row2,col2)

A value of -1 for a parameter will qualify as being null. The parameters that are ignored will also be considered as null.

Request variable summary

 metadata_only = [true/(false)] - don't return the cell values, just the pertinent metadata, used to stub the matrix
 matrix - [true/(false)] - return all possible metadata properties for the matrix: key
 row - [true/(false)] - return all possible metadata properties for the row: key
 column - [true/(false)] - return all possible metadata properties for the column: key

 row1 - [positive integer] - row/upper left co-ordinate
 col1 - [positive integer] - column/upper left co-ordinate
 row2 - [positive integer] - row range/bottom right co-ordinate
 col2 - [positive integer] - column range/bottom left co-ordinate
 

Response

All responses are in JSON.

A response is a single hash with the following keys possible:

• matrix: (metadata properties of matrix)
  • name
  • other metadata
• row: (metadata properties for the returned row)
  • labels (hash of row_index => row_name)
• column: (metadata properties for the returned columns)
  • labels
• data: the "cells", an arrayOfArrays, each of which points to a hash (i.e. each cell is hash):

      {
        state1: {properties},
        state2: {properties},
        stateN: {properties},
        value: {properties} !! Revisit: value is a property inside state?!
      }  

Examples

Request: http://foo.org/path/to/api_action?row1=1&col1=1&row2=100&col2=50

Response:

{
  "matrix": {
    "height": 1000,
    "width": 1000
  },
  "row": {
    "labels": ["label1", "label2", ..., "label100"]
  },
  "column": {
    "labels": ["label1", "label2", ..., "label50"]
  },
  "data": [
    [
      {
        "author": "XYZ",
        "date": "YYYYMMDDhhmm",
        "value": 100
      },
      {data_{1,2}},
      .
      .
      .
      {data_{1,50}}
    ],
    [data_2],
    .
    .
    .
    [data_100]
  ]
}

The requests can also be for metadata only. In this case, the response is similar but without the cell key in the data ArrayOfArrays. A configuration for using jMatrixBrowse to handle these requests and responses should specify the 'author' and 'date' as layers which would then be handled accordingly.