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?

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.

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

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

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.

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}]