Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mbest/knockout-table

Table binding plugin for Knockout
https://github.com/mbest/knockout-table

Last synced: 2 months ago
JSON representation

Table binding plugin for Knockout

Awesome Lists containing this project

README 

        
### **TABLE** binding for [Knockout](http://knockoutjs.com/)



The `table` binding provides a fast method for displaying tables of data using Knockout. `table` is about ten times faster than nested `foreach` bindings.



#### Examples



This example outputs a two-dimensional array as a table.



```javascript

var vm = {

    data: [

        [ 1, 2, 3 ],

        [ 4, 5, 6 ],

        [ 7, 8, 9 ]

    ]

};

```



```html



```



This example uses a `header` array (which determines the number of columns in the table) and a `data` two-dimensional array.



```javascript

var vm = {

    header: [ 'x', 'y', 'z' ],

    data: [

        [ 1, 2, 3 ],

        [ 4, 5, 6 ],

        [ 7, 8, 9 ]

    ]

};

```



```html



```



This example uses `rows` and `columns` definition arrays and a `data` object.



```javascript

var vm = {

    columns: [ 'x', 'y', 'z' ],

    rows: [ 'a', 'b', 'c' ],

    data: {

        a: { x: 1, y: 2, z: 3 },

        b: { x: 4, y: 5, z: 6 },

        c: { x: 7, y: 8, z: 9 }

    }

};

```



```html



```



This example uses `header` and `dataItem` options to define the values for those items.



```javascript

var vm = {

    columns: [

        { heading: 'x', datavalue: 'col1' },

        { heading: 'y', datavalue: 'col2' },

        { heading: 'x', datavalue: 'col3' } ]

    data: [

        { col1: 1, col2: 2, col3: 3 },

        { col1: 4, col2: 5, col3: 6 },

        { col1: 7, col2: 8, col3: 9 }

    ]

};

```



```html



```



This example uses `header` and `dataItem` functions to define the values (uses same view model as above).



```html



```



This example uses a `dataItem` function to output a multiplication table (up to five).



```html



```



#### Parameters



The `table` binding expects a single parameter of a two-dimensional array to output. It also accepts an object literal with the following properties:



* `data` - an array or object containing either objects or arrays, depending on the `columns` and `rows` options. `data` is required unless a `dataItem` function is provided.

* `columns` - either the number of columns in the table or an array, with each item representing a column. In the former case, the rows in `data` should be arrays; in the latter case, they should be objects, with the values in `columns` being the keys in the object. If no `columns` option is provided, it will default to either the length of the `header` array (if it’s given and an array) or the longest row in `data`. `columns` can also be an array of objects, in which case the `dataItem` option must also be specified.

* `rows` - either the number of the rows in the table or an array, with each item representing a row. In the former case, `data` should be an array of rows; in the latter case, it should be an object, with the values in `rows` being the keys for each row. If no `rows` option is given, it will default to the length of the `data` array.

* `header` - either an array of header values, a function that returns the header for each column value, or a string used to read the header from the column object. (optional)

* `dataItem` - either a function that returns the data value for a given row and column, or a string used to read the data-item key from the column object (which is then used to read from the row object). (optional)

* `evenClass` - the name of a class that will be applied to even rows in the table, starting with the second row. (optional)



Any of the above parameters can be an observable and will cause the table to be regenerated if updated. For the purpose of making the binding faster, the entries in `data`, `rows`, `columns`, or `headers` cannot be observables. The actual data items, though, can be observable, and if updated, will update only the corresponding table cell’s contents.



#### How this binding works



The `table` binding uses a very fast method of table generation. 1) It first generates the table HTML as a string. 2) It then parses the string into DOM elements using `innerHTML` on a detached node. 3) Finally, it inserts the table contents into the table element in the document.



#### Additional interfaces



* `ko.utils.safeString(string)` - returns the string wrapped in a special object. The `table` binding will accept this string as safe and not escape it. This allows you to output HTML codes as part of the row or header data.

* `ko.utils.escape(string)` - returns a string with HTML special characters (&, <, >, ", etc.) converted to entities. This is used internally by the `table` binding to ensure that data values are treated as text when assembled into the table HTML.



#### License and Contact



**License:** MIT (http://www.opensource.org/licenses/mit-license.php)



Michael Best


https://github.com/mbest


[email protected]