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

x1=int,x2=nil,y1=nil,y2=nil            -> return all cells in the row defined by x1
x1,x2                                  -> return the rows in range x1-x2 (inclusive)
y1                                     -> return all cells in this column    
y1,y2                                  -> return the columns in range y1-y2
x1,y1                                  -> return the cell at x1,y1
x1,y1,x2,y2                            -> return the cells bound by (x1,y1), (x2,y2)

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
 methods - Array - return the metadata from only these named_methods: key

 x1 - [positive integer] - row/upper left co-ordinate
 y1 - [positive integer] - column/upper left co-ordinate
 x2 - [positive integer] - row range/bottom right co-ordinate
 y2 - [positive integer] - column range/bottom left co-ordinate
 

The server will understand how to translate "named_method" into a value that is legal for the property bound to that name in the configuration (see below). Client will translate :named_method => value properties of returned cells into CSS or related properties as mapped in configuration.

In the configuration we bind display level properties to server-side functions, e.g.:

  data-background-color=named_method

Mappable cell properties:

  background-color: CSS legal values
  border-color: CSS legal value
  color: CSS legal values

Mappable state properties:

  background-color: CSS legal values

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: arrayOfArrays that points to a hash:

      {
        data: {state: {properties}, {state1: {properties}, ... {stateN: {properties}},
        cell: {properties}
      }  

Examples

Request: http://foo.org/path/to/api_action?methods[]=author&methods[]=date&x1=1&y1=1&x2=100&y2=50

Response:

{
  "matrix": {
    "height": 1000,
    "width": 1000
  },
  "row": {
    "labels": ["label1", "label2", ..., "label100"]
  },
  "column": {
    "labels": ["label1", "label2", ..., "label50"]
  },
  "data": [
    [
      {
        "data": {
          "author": "red",
          "date": "black"
        },
        "cell": {
          "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 named_methods 'author' and 'date'