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.

Request level variables

Variables prefaced with ?? are under discussion. [???] Indicates that some controlled vocabulary of options needs to be determined.

?? on_click_action - [???] - have the API return the name of a javascript method to call on click of a cell value ?? radar - [true/false] - response should return only a 0/1 based presence/absence representation of the data

cb - I don't think the API needs to worry about the on_click_action. I think this should be set either as an attribute on the DOM element wrapper, or in some javascript instantiation. Also, I think it would be cool to not only set a single on click action, but make it dynamic based on cell data. Does anyone think this would be useful? Is there a reason someone would want one cell to act differently than another after a click?

mjy - agreed on the on_click_action -> stiking

cb - The more I think about it, the more I think the api should just return an array of arrays in most, if not all requests, then its up to the javascript to determine what to do with it. If the api returns an array of arrays with 0s and 1s, again, a DOM element attribute, or javascript instantiation with radar: true will do the right thing.

mjy - Sounds good to me. I think I was initially envisioning APIs being able to speed up data access

pg - Just a small addition. Do you think it would be useful to have the api return the size of the matrix?

my - yes, definitely, perhaps their is a configuration response that is returned when first initiated?

Matrix level metadata

matrix_metadata - [true/(false)] - returns a top level hash describing the matrix (:rows => int, :columns => int, :name => name, :created_on => date_time) ... others?  should we looks at NeXML or some other ontology describing matrices?) Typically this will only be set to true on the first request

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

cb - ok, now I think I'm wrong in that the api should just return an array of arrays - row / column metadata would indeed be useful. It could be defined on the client side, and also returned with data. Now I'm thinking api responses should be an associative array, something like { metadata: { row: rowdata, column: columndata }, data: arrayOfArrays }

Window defining

 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

For each request one of the following window defining patterns must be met:

x1            -> return all cells in this row
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)

cb - I agree with the above requests, but wonder if we only use x1,y1,x2,y2 so that it requires less handling by the server side api.

mjy - agreed, request will require all 4, we'll assume the pattern above holds, we need to determine a value for null, perhaps -1?

### Layer metadata ``` ?? layer -> [integer] the layer to which the request should be rendered, is repeated in response (might not be needed) ?? metadata_type -> [???] a list of ```

cb - I don't think the server side needs to care about what layer it will be rendered. I'm not sure how, but I think this should all be done on the client.

pg - I agree that server side shouldn't know about which layer will be rendered. But, if there is different data for different layers, then this should be useful to request for only the layer that we are rendering.

mjy - so we work under the assumption that any given request returns data to given layer?

Response

All responses are in JSON. ** Examples **

**http://foo.org/path/to/api_action/&x1=1 **
?? this needs work, the basic response should be an [x][y] Array of Arrays with the value being a hash
{ "cells": 
    [
      1:
        [0:{"values":[value1, value2...value n]}],
        [1:{...}],
     ]
}

cb - My suggestion is the following : **http://foo.org/path/to/api_action?x1=1&y1=1&x2=100&y2=100 ** { metadata: { row: rowdata, column: columndata }, data: arrayOfArrays } I think we should let any type of json object inside each of the "cells". The user could simply specify that the object is a primitive to be displayed as text, it could be a json object and the user could specify a property to display, a function could be specified to return what should be displayed.

pg - I suggest that we can allow additional fields metadata. { metadata: { row: rowdata, column: columndata, property1: value1, property2: value2, ...}, data: arrayOfArrays } and during the configuration, user can pass a list of properties that the plugin should handle to render the cell elements differently. e.g. the user gives in configuration: metadata: [{field: 'property1', renderer: {css-properties}}, field: 'property2', renderer: {css-properties}]

mjy - I like this approach, we might want to consider encapsulating matrix: matrixdata metadata, though the property:value pairs can likely handle things like matrix_name:foo, matrix_creation_date: 2/12/1920