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?

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=int,x2=nil,y1=nil,y2=nil            -> 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?

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?

Request variable summary

 metadata_only = [(false)/true] (don't return the cell values, just the pertinent metadata, used to stub the matrix?)
 matrix_metadata - [true/(false)] - return all possible metadata properties for the matrix: key
 row_metadata - [true/(false)] - return all possible metadata properties for the row: key
 column_metadata - [true/(false)] - return all possible metadata properties for the column: 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
 
 named_method1=true  - Configuration will map client side style properties to server-side named methods
 named_method2=true  ...
 named_methodn=true  ...

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

my - Alternately we could just have the server recognize the named cell-properties and forgo the mapping, though I think this extra level of complexity will allow more flexible server responses?

• strike the "_metadata" bit? in requests?
• do we want to provide client-side ranged "heat-maps", or have that all calculated server side? For example we could map a property to an integer range (1-100), have the server return a legal value, and have the client generate the color map (based perhaps on some configuration). Alternately we could just have the server calculate the values to map.

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 ... OR we could just flatten the whole response

mjy - After a little more thought here's my proposed model:

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