JQuery API

---

Initial ROUGH draft overview of SPI

---

#API js-tree-table has a javascript API. This can be used with the column controls and row controls. All API interactions will override row and column controls, which become defaults.

The API is accessed through the table element, e.g. $('table.js-tree-table').jstt

For the most part table rows can be represented as:

• js-tree-table Row objects (these are what tree table will return from functions, they can be unpacked using the row API)

##insertRow(A,B) Insert row A after row B.

A and B can both be specified as JQuery, DOM elements, or a js-tree-table Row object. B may also be a String data-jstt-id of the row.

If B is null then insert at top of table.

Returns jstt on which it is called.

Throws Error if:

• B is not part of the table,
• the insertion would violate table constraints
• A is not a table row (the row may still be invalid, e.g. have the wrong number of columns though)

##removeRow(A, withChildren) Remove row A from the table.

If withChildren is true then all rows identified as children of A are also removed.

If A has children and withChildren is not specified, throws an Error.

##cutRow(A) Remove row A from table and place on a cut stack.

If row A has children these are also removed from the table and kept with A on the stack.

##pasteRow(B) Pastes the top row from cut stack after row B.

If no cut row exists, does nothing.

If row B does not exist, throws Error

If the paste operation would violate constraints, throws Error.

##cutStack The cutStack, which has the following methods.

'Row' on the cutstack may include children associated with the row. The Row and its children are dealt with as a single item.

###push(A) Push a row onto the cut stack.

###pop(A) Removes the top row from cut stack and returns it.

###peek() Returns the row from the top of the cut stack without removing it.

##children(A, all) Return an ordered array of the rows considered children of A.

If all is true return children recursively, flattened into array. Since, in reality the tree structure is entirely artificial (each entry being a tr element in the table) this is how they are treated outside js-tree-table (as a simple list of tr elements).

##propose(A,B) Propose the insertion of row A after row B.

A and B can be specified as String data-jstt-id of the row or as JQuery or DOM elements

If B is null then the proposal is for insertion at the top of the table.

Returns true if proposal meets constraints, otherwise false.

##sort(column) Sort the table rows according to the currently imposed constraints, sort columns, and sort ordering.

If column is provided (as either an integer, a column object, JQuery object, DOM element) the sort is performed for that column only using the current sort order as a start point and using currently imposed constraints. If supplied as an integer this is an index into the array as returned from sortColumns NOT the column as displayed in the table.

Note if a JQuery or DOM element is used to identify the column then an Error is thrown is it is not recognised as a js-tree-table sortable column. That is, the td or th element identified must appear in a position identified as a sort column.

##sortColumns An ordered array of sort columns. This presents the sort column objects, sorted by their sort predence.

##sortColumn(col, {order: "[asc|desc]" [, sort: (a,b)={}]}) col can be a column object or index into sortColumns. Replaces the order and, optionally sort function.

#Row API Row objects, as returned from API calls above have the following interface.

##children(all) The list of this rows children, returned as row objects.

if all is false or missing, returns only the immediate children, otherwise returns all recursive children as a flat list.

##asElement() Unwraps the tr element and returns it as a simple DOM element.

##asJQuery() Unrwraps the tr element and returns is as a JQuery object.

#Notes

##A note on sorting Any table with a data-jstt-tree column is immediately identified as sort column 0. It will always be the first column sorted and will be sorted withing the constraints of the defined tree structure.