Voodookit: Test Suite

At its simplest, Voodookit will silently process a table of data:

HTML

Javascript

Demos and Tests

Demo: vkex1.col(1).sort()

Demo: vkex1.col(1).sortReverse()

?Test: vkex1.numRows() → ? (expected 3)

?Test: vkex1.numCols() → ? (expected 2)

?Test: vkex1.numContentRows() → ? (expected 2)

?Test: vkex1.numHeaderRows() → ? (expected 1)

In addition to getting general information about the table, you can query for a specific cell by (row, col) position. Position coordinates are 0-indexed from the top left, and non-content rows are skipped. The return value is an instance of VkCell.

?Test: vkex1.cell(0,1).value() → ? (expected "1.0")

?Test: vkex1.cell(0,1).toString() → ? (expected "1.0")

?Test: vkex1.cell(1,0) → ? (expected "Chair")

If you want to handle an entire column at once, you can request it by index:

?Test: vkex1.col(1).cellValues().join(", ") → ? (expected "1.0, 4.0")

You can even calculate aggregate values for a column using the reduce function:

?Test: vkex1.col(1).reduce( function(x,y) { return parseFloat(x)+parseFloat(y); } ) → ? (expected 5.0)

Or find matching cells using the grep function, which returns an array of VkCells for which the test function returns a true value:

?Test: vkex1.col(0).grep( function(vkcell) { return vkcell.value()=="Chair"; } )[0].row().cell(1) → ? (expected 4.0)

Finally, you can also get Voodookit objects based on a new or already-Voodookit-enabled <table> element, or from tr or td elements within such a table:

?Test: $("#ex1").voodoo().constructor.toString().indexOf("function VkTable") >= 0 → ? (expected true)

On nonsucky browsers, you can do this test with nicer syntax:

?Test: $.browser.msie? "VkTable" : $("#ex1").voodoo().constructor.name → ? (expected "VkTable")

?Test: $.browser.msie? "VkRow" : $("#ex1 tr:last").voodoo().constructor.name → ? (expected "VkRow")

?Test: $.browser.msie? "VkCell" : $("#ex1 tr:last td:first").voodoo().constructor.name → ? (expected "VkCell")

Voodookit's default sorting works fine for alphabetical data. But what if you've got a bunch of actual floating-point numbers?

HTML

Javascript

Demos and Tests

Demo: vkex2.col(1).sort()

As you can see, this doesn't work so well. We need to tell Voodookit that the second column contains floating-point numbers.

HTML

Javascript

Demos and Tests

Demo: vkex3.col(1).sort()

Demo: vkex3.col(1).sortReverse()

Here we're passing a little bit of information to Voodookit about the columns in our table. The $.voodoo.types.float object is a Voodookit column type, whose main purpose is to provide a parseValue method, converting the table cell's HTML contents into a Javascript value. For this type, the parseValue method is simply a call to Javascript's built-in parseFloat function.

Declaring types ensures that any cell's value() function returns a Javascript object of the appropriate type. It also lets you use the type-correct operators for things like arithmetic, and the convenient built-in column arithmetic function:

?Test: vkex3.col(1).sum() → ? (expected 1320.00)

Voodookit also supports date and date+time data types: DateTime, for a date and time, and Date, which is a date only. One way to express the values for cells of these types is in milliseconds since epoch. An advantage of this approach is that times can be localized on the client side, so you don't have to care what time zone your user is in.

HTML

Javascript

Demos and Tests

?Test: vkex4.cell(0,2).value().constructor == Date → ? (expected true)

?Test: vkex4.cell(0,2).value().getTime() < vkex4.cell(1,2).value().getTime() → ? (expected true)

?Test: vkex4.cell(1,2).value().getTime() < vkex4.cell(2,2).value().getTime() → ? (expected true)

?Test: vkex4.cell(0,2).value().getTime() < vkex4.cell(2,2).value().getTime() → ? (expected true)

Demo: vkex4.col(2).sort()

Demo: vkex4.col(2).sortReverse()

Demo: vkex4.col(2).sortReverseBlanksLast()

Want to add an odd class to the odd rows? Or respond to changes in the table's sort order? Voodookit generates events you can register for:

• vkRowScan — generated when a content row (a tr element that contains one or more td elements) is handled by Voo2do: on first review of the table content, and on subsequent changes to row position (sorting). The event originates from the row tr element. In this event's data hash:
  • rowIndex: an integer indicating this row's position among all content rows in the table, starting from 0.
  • vkRow: the VkRow object for this table row.
• vkChange — generated when the value of a cell is changed. The event originates from the changed td element, and bubbles up the document so you can also bind to a table and get this event. Because you may be interested in changes within a column, the vkChange event is also fired by the corresponding column, which provides a bind method for this purpose. In this event's data hash:
  • oldValue: the cell's previous value.
  • cell: the VkCell object for the affected cell. You can get the current (new) value by calling cell.value().
• vkRowAppend — generated when a new row is added to the table after the table's initial loading, e.g. with append or appendRow. Originates with the new tr element and bubbles up.
• vkRowDelete — generated before a row is deleted from the table using the deleterow() method. Originates with the delete tr element and bubbles up. Note that deleting a row will also trigger vkRowScan events to be triggered for all remaining rows; these are triggered after the vkRowDelete event.
• vkRowsReordered — generated once after a table's rows have been re-ordered, such as in a sort operation. Originates on the table object.

These events are triggered on the underlying tr elements, so you can listen for and react to them in the typical jQuery way.

HTML

Javascript

Demos and Tests

Demo: vkex5.col(0).sort()

Demo: vkex5.col(1).sort()

Did that bolding work correctly? We have to tolerate either a textual value ("bold") or a numeric one (700) for the font-weight property, depending on the browser used.

?Test: $("#ex5 tr:eq(2)").css("font-weight")=="bold" || $("#ex5 tr:eq(2)").css("font-weight")==700 → ? (expected true)

?Test: $("#ex5 tr:eq(1)").css("font-weight")=="normal" || $("#ex5 tr:eq(1)").css("font-weight")==400 → ? (expected true)

?Test: vkex5_got_rowAppend → ? (expected 1)

?Test: vkex5_got_rowsReordered → ? (expected 1)

In the examples so far, the values displayed in our HTML tables have simply been the default, stringified version of the cell's value. For a $.voodoo.types.date column, we see something like "06/23/2009". But what if you want your cell displayed in different format?

That's where renderers come in. Renderers determine how to display the values of cells in HTML. The renderer has access to the cell's VkCell object, allowing the rendering behavior to be based on the cell's value as well as its row, column, and table.

Voodookit includes the following built-in renderers. These are classes and should be instantiated using new. You can also build your own renderer—more on that later.

• $.voodoo.render.String
• $.voodoo.render.HtmlString
• $.voodoo.render.FloatHours *TODO*
• $.voodoo.render.Currency *TODO*
• $.voodoo.render.LocaleDate
• $.voodoo.render.LocateDateTime

Many of these renderers accept options that configure how they behave. Options can be passed in as an associative array parameter. Two options are supported by all renderers: default, which specifies the result to return when rendering an empty cell, and defaultValue which does something slightly different: it treats empty cells as having the given value — useful if you want to apply the same logic to generate the HTML for empty cells.

Note: The word default is a reserved word in Javascript. This option should probably be renamed; in any usage, be sure to quote the word default. For example, the object literal { default: "none" } will work in Firefox but cause a syntax error in Google Chrome, whereas { "default": "none" } works in all browsers.

Let's see how the default setting works using the String renderer.

HTML

Javascript

Demos and Tests

?Test: $("#ex6 tr:last td:last").html().toLowerCase() → ? (expected "<i>unknown</i>")

Note that in our HTML, the value for Alice's pizza choices is a single space character— not considered empty by Voodookit. Hence it is rendered as a space:

?Test: "["+$("#ex6 tr:eq(2) td:last").html().toLowerCase()+"]" → ? (expected "[ ]")

In the second table, we used the defaultValue option instead of default. What does this mean?

?Test: $("#ex6_2 tr:eq(1) td:last").html() → ? (expected "&lt;i&gt;unknown&lt;/i&gt;")

Often, you'll want to let users not only view the data in a table cell, but also edit that data. Voodookit's editable renderers make this easy, by providing a representation of the cell value as an editable HTML form widget, whose change event triggers a value change on the corresponding vkCell. That means the changes are more than just skin deep—you can instantly re-sort, or use event listeners to react to vkValueChange events.

HTML

Javascript

Demos and Tests

Demo: vkex7.col(0).sort()

Demo: vkex7.col(0).sortReverse()

Demo: vkex7.col(1).sort()

Demo: vkex7.col(1).sortReverse()

Demo: vkex7.col(2).sort()

Demo: vkex7.col(2).sortReverse()

When a cell's value is changed, the vkChange event fires. This event bubbles up from the changed td element, so you can listen for it on a particular cell or on the whole table.

HTML

Javascript

Demos and Tests

?Test: vkex8_gotTableEvent → ? (expected true)

?Test: vkex8_gotRowEvent → ? (expected true)

?Test: vkex8_gotColumnEvent → ? (expected true)

The vkChange event is also used by renderers to update the rendered value when a cell's value is changed; try this increment operation to see how that works:

Demo: vkex8.cell(1,2).value( 1+vkex8.cell(1,2).value() )

In addition to changing data in existing rows, you can add rows to a Voodookit-enabled table. You can do this in two ways:

1. use a standard jQuery method on the table, like $("#mytable").append("...") followed by a call to $("#mytable").voodoo.findNewRows(), or
2. use the built-in $("#mytable").voodoo.append() method, which does the same thing.

When content is added this way, any new rows are processed and rendered based on the parameters first sent to Voodookit on initialization of the parent table. A vkRowScan event is also generated for each new row.

HTML

Javascript

Demos and Tests

?Test: vkex9_newRowIndex → ? (expected 3)

?Test: vkex9_newRowText → ? (expected "Dave")

So to recap, there's the two-step method: add table content however you want and then call findNewRows:

Demo: $("#ex9").append("<tr><td>Ed</td><td>Spinach</td><td>2</td></tr>")

Demo: $("#ex9").voodoo().findNewRows()

Or the append method built into Voodookit's VkTable class, which returns the VkTable object so it's chainable:

Demo: $("#ex9").voodoo().append("<tr style=display:none><td>Ed</td><td>Spinach</td><td>2</td></tr>").$table.find("tr:last").fadeIn("slow") && false

Add too many rows? Maybe you want to delete some. You can do this with standard jQuery/DOM methods if you wish: just .remove() a tr and all VoodooKit methods (row counts, positional cell coordinates, etc.) will keep working just fine, because VoodooKit treats the DOM (plus jQuery .data) as the primary underlying data structure whenever possible.

However, in most cases it is preferable to use the VkRow.deleterow() method, which will not only remove the appropriate tr from the table, but also generate some useful events:

• vkRowDelete on the row about to be deleted, while the VkRow object is still accessible.
• vkRowScan on all remaining rows in the table.

HTML

Javascript

Demos and Tests

?Test: vkex10.numContentRows() → ? (expected 2)

?Test: vkex10_name_deleted → ? (expected "Alice")

The row we deleted should have 1 row scan, from the initial load:

?Test: vkex10_num_scans_per_name["Alice"] → ? (expected 1)

Remaining rows should have 2 row scans, one from initial load and one after the deletion of the Alice row:

?Test: vkex10_num_scans_per_name["Bob"] → ? (expected 2)

?Test: vkex10_num_scans_per_name["Charlie"] → ? (expected 2)

In some cases, you might not want to immediately remove the deleted tr from the document. For example, you might want to animate the removal effect. You can do this by calling prepToDelete instead of delete— prepToDelete will ready the row for deletion and send the appropriate events, and like delete will return a jQuery object wrapping the relevant tr. But unlike delete, prepToDelete counts on you to make a final call to remove the row when you're done. (It is important that you actually do remove the row from its containing table; until you complete that step, the VkTable object's state, such as the result of numRows(), will be inconsistent with the events that have been generated.)

Demo: $("#ex10 tr:eq(1)").voodoo().prepDelete().fadeOut(function(){ $(this).remove(); }) && false;

Sometimes you want to calculate a value for a row. For example, if you are tracking tasks you might have estimated time and a time elapsed columns entered by the user. What if you want to also display a time remaining column?

Voodookit makes this easy by letting you define a computed column. Computed columns are like regular columns in your table, but instead of reading their value from the content of a <td> element, their value is calculated according to a formula you specify.

Computed cell values can be based on any non-computed columns in the current row, as well arbitrary Javascript. Values based on other columns will automatically change if their parameters are changed. And of course, cells in computed columns still generate the same events as other cells.

HTML

Javascript

Demos and Tests

?Test: vkex11.col("num_slices").is_computed() → ? (expected false)

?Test: vkex11.col("pct_of_za").is_computed() → ? (expected true)

?Test: vkex11.cell(0,2).value() → ? (expected 0.125)

But wait, there's more! Computed columns listen for vkChange events on their neighbor cells specified in the compute_from_cols parameter. So if we change one of the num_slices cells:

?Test: vkex11.cell(1,1).value(3) → ? (expected 3)

?Test: vkex11.cell(1,2).value() → ? (expected 0.375)

Try it yourself... just edit one of the central column values and watch the right column change in response!

Sometimes it's simpler to specify how a column might look by writing an HTML template, instead of a renderer function. Voodookit includes a simple template processor that, given a HTML-like template string, compiles a Renderer class that executes the given template. The template can refer to other cells in the same row as variables, and can execute some basic javascript code.

HTML

Javascript

Demos and Tests

?Test: vkex12.cell(0,2).$td.text() → ? (expected "Alice ate 2 slice(s).")

?Test: vkex12.cell(2,2).$td.text() → ? (expected "Charlie is STARVING!")

Note that currently, templates will only automatically re-render when their cell's value changes, but not when other values that may have been used in the template change.

Voodookit includes a flexible facility to generate an alternate representation of the data in your table. This allows you to take a VkTable in your document and, based on its current state including any recent user modifications, get a representation of that table. You can use it to quickly get a JSON serialization of your table, or a custom representation specific to your needs.

HTML

Javascript

Demos and Tests

Demo: $("#ex13_altrender").text(vkex13.altRender("json")) && false

?Test: vkex13.altRender("json").indexOf("\"Charlie\",\"0\"") > 0 → ? (expected true)

?Test: vkex13.altRender("json").charAt(0) → ? (expected "[")

To create a custom rendering, you supply methods for the VkTable, VkRow, VkColumn, and/or VkCell classes that return data in the desired format. You can do this by directly adding methods to the classes:

• $.voodoo.VkTable
• $.voodoo.VkColumn
• $.voodoo.VkRow
• $.voodoo.VkCell

Here's an example where we'll write custom handlers to generate a printable HTML rendering of the table.

HTML

Javascript

Demos and Tests

This code follows a typical rendering pattern: the table's as_printable method calls a method of the same name on each of its rows, which in turn call a method of the same name on each of their cells. This approach works well in many cases and yields generally readable code, but there's no reason you need to stick with it. The only requirement is that, for myvktable.altRender(format) to work, there must be an as_format method on the VkTable object.

?Test: $("#ex14_altrender td:eq(2)").text() → ? (expected "Bob")

Demo: $("#ex14_altrender").html(vkex14.altRender("printable")) && false

Demo: $("#ex14_altrender").text(vkex14.altRender("json")) && false

Voodookit's paging support works on a simple principle: loading the contents of another HTML table into the current table. You can use the same mechanism to dynamically load a table's contents, or to grow a table, or to turn pages back and forth.

HTML

Javascript

Demos and Tests

?Test: vkex15.cell(0,0).$td.text() → ? (expected "0")

?Test: vkex15.cell(4,1).$td.text() → ? (expected "0.2")

This loading should be non-destructive to the original table:

?Test: $("#ex15_staticpage td:eq(3)").text() → ? (expected "0.2")

Try it yourself:

Demo: vkex15.loadRowsFromTable($("#ex15_staticpage"));

Demo: vkex15.clear();

Of course, paging is much more useful when you can load data that's not already in your document!

HTML

Javascript

Demos and Tests

Demo: vkex16.loadRowsFromUrl($("#ex16_pagelink").attr("href"));