Use

In development

We'd like the plugin to be unobtrusive, using HTML data- elements. Something like this:

<div id="my_browser" 
    data-jmatrix_browser=true 
    data-api="http://foo.org/path/to/api" 
</div>

It would also be possible to initialize the jMatrixBrowse on already existing elements by passing hash for the configuration options $('#myDiv').jMatrixBrowse( { api: 'http..' } ).

Configuration options

Required

data-api=http://foo.org/path/to/api     -  The API to call 
data-jmatrix_browser=true               -  This element is the wrapper for a jMatrixBrowser

Optional

data-initial-window-size="2,3"          -  Define the width, height of the initial window (defaults to 10,10 ?)
data-initial-window-position="x,y"      -  Define the x,y position of the window  (defaults to 0,0)
data-jmatrix-browser-css                 - URL/URI

Planned extensions

data-translation-method                 -  A users jQuery method that translates request parameters and API response into a
data-background-load=[none|???]         ?? The algorithm to use for background loading (defaults to "none")
                                           The server should have these values in response. 
                                           jMatrixQuery jSon acceptable response. This can be used to generate a matrix
                                           on client side by using the request parameters and an undefined response.

data-layers="0:data,1:age,2:confidence" ?? I think we could allow custom API layers based on key-value configuration.

cb - I like this idea with regard to data-layers. One could simply give keys ( or perhaps functions that are given cell data and return a value ), that correspond to different z-index layers of data. This is one reason I'm not 100% sure I like the API response sending back the cell value (literal) in one property, and the cell properties (metadata) about the data in another property. I think the API response for a single cell should be either a literal, or a json object. When the data layers is specified, it can just pick out the property it wants to display as a cell value.

mjy - I had initially envisioned each request returning data for a specific layer, but now I'm wondering if, perhaps, all layers could be updated with their respective mapped properties for any given response?

mjy at present we decided to move away from the layers concept, but rather consider sudo-layering via sets of CSS stylings down the road

CSS mapping

user.css -> references to named classes that are "fixed"

Configurable css subclasses based on response as provided for data: {}

 | class         |  expected response |
 |  cell-background-color   | a valid CSS background-color, e.g. #fef | <- some issues with row/column in the model
 |  cell-border-color       |         |

Events

jMatrixBrowse will trigger several events which the user can bind to to perform specific tasks.

jMatrixBrowseChange     - Triggered on the change of content in jMatrixBrowse. 
                          This is triggered when a row/col goes out of focus and a new one is loaded. 
                          Properties:  
                               `previousCell.row, previousCell.col` and `currentCell.row, currentCell.col`.

jMatrixBrowseDragBegin   - Triggered when a drag on jMatrixBrowse begins.
jMatrixBrowseDragStop    - Triggered when a drag on jMatrixBrowse stops.
jMatrixBrowseClick       - Triggered when a cell in matrix is clicked. 
                           Properties:
                               `row` and `col`
jMatrixBrowseRowHeaderClick     - Triggered when a row header in matrix is clicked. 
                                  Properties:
                                    `row`
jMatrixBrowseColumnHeaderClick  - Triggered when a cell in matrix is clicked. 
                                  Properties:
                                    `col`
jMatrixBrowseRendererInitialized - Triggered when jMatrixBrowse finished initialisation.
jMatrixBrowseAnimationStep - Triggered at every step of the deceleration animation.
                             Properties:
                               `now` - the top and left of the drag container. 
                               `fx`  - fx.elem for drag container.
jMatrixBrowseAnimationComplete - Triggered after the deceleration animation for jMatrixBrowse is complete. 
jMatrixBrowseLoadComplete   - Triggered after the background loading finishes loading everything in the matrix into the DOM. 

Custom Styling

You can plug in your own css to change the look and feel of jMatrixBrowse. Below is the description of the class names for different elements.

jmb-matrix-container - The container for jMatrixBrowse. 
  jmatrixbrowse-col-header - The container for column headers.
  jmatrixbrowse-row-header - The container for row headers.
  jmatrixbrowse-drag-container-container - The container for jMatrixBrowseDragContainer.
    jmatrixbrowse-drag-container - jMatrixBrowseDragContainer. Container for matrix content.
      jMatrixBrowse-content - The container for all matrix cells. 
        jMatrixBrowse-cell - A matrix cell. Every cell contains two attributes data-row and data-col.
  jMatrixBrowse-background-data-container - The container for background data.