JsTable   v0.4.5
Author: AT Mulyana           25 Juli 2005


Table of Contents

Description

JsTable is a DHTML widget of table that can be inserted into a web page via JavaScript. The table has the following three main features or purposes:
Formerly, I was tempted to include the paging to be the one of the features. But then, I realized that the purpose of this table is for an input, not for a report. You should find easily the kind of that table out there.

Requirements

Here is the supported browsers by JsTable. Actually, it's the best version I have but I choose them as the minimum version for JsTable. Even if it's the minimum version, it's not  guaranteed that the later version will still be good (I found some lack).  I hope you get the best browser so that you can run JsTable correctly. The target browsers are:

Story Behind JsTable

I have found a client that gave me a complaint because he cannot work fast to fill a goods list when he had to finish a lot of transaction in rush. The user interface on web application we provide (and I guess on most web application) is too ugly for this condition. The user wants easily to move from one cell to another, only by pressing keyboard, such as arrow key or enter. The key Tab can be used but with some lack of free movement. So, I create this DHTML widget to enhance web application. There are some reasons to still maintain web application (you know if you like web application).

To design this DHTML widget, I consult table widget in Java Swing named JTable (Therefore, I name this widget with JsTable). But I don't make JsTable become exactly the same as JTable, you know it's very hard, JTable is too complex for my purposes and also the simplicity is still needed for web widget. But some mechanisms in JTable still give me the idea.

TableModel and Sets The Editability of A Cell

TableModel here is not the same as one in Java Swing JTabel. After defined for a JsTabel, it cannot be redefined for that JsTabel. TabelModel here is only to collect some properties for JsTabel and also a method to control  editability of the cells on JsTabel. To create TableModel, use statement:

    var oTableModel = new JsTableModel(columns,phpStyle,numberDenominator,dateFormat,oldValIfInvalid,withPrimaryKey);

Parameters:
    columns is an array of column type. Next section will show how to define column type. The first item (index 0) in array is column type for column 0, the second is column type for column 1 and so on.
    phpStyle is boolean to determine whether the server script is PHP or not. In PHP, to create HTTP POST/GET parameter as an array, we must provide bracketed brace ( [] ) after the name of FORM element that will become an item of the array, beside each of those elements must have the same name. As far as I know, this behaviour is only in PHP.
    numberDenominator is the character that will be used to seperate thousands denomination for the value in number column. The valid character is ',' (comma) or '.' (period). The default is period. If the chosen denominator is period then the decimal point is comma and vice versa.
    dateFormat is string to detemine the date format. The valid values are 'd-m-y' (format: dd-mm-yyyy) or 'm-d-y' (format: mm-dd-yyyy). The default is 'd-m-y'. This format is used by column whose type of date or date time. The value typed by user on these columns must conform the defined format here.
    oldValIfInvalid is boolean to determine whether the old value must be rollbacked when the user type the invalid value. The default for this parameter is false, that is if the invalid value appears then this value will be considered as the default value depending on its column type.
    withPrimaryKey is boolean to determine whether the primary key (uses database term) will be given when insert a row into table. The default is false, that is the primary key will not be given but use the row index in table to replace this primary key. Primary key is needed by column whose type of boolean (whose editor is check box). The primary key will become the value of checkbox that will be sent to the web server.

Properties:
The properties are set after TableModel is created.
TableModel has a method to control the editability of the cells, named isCellEditable. This method takes two parameters, the first is the row index (starting from 1, the index 0 is column's header)  and the second is the column index (starting from 0). With these two paramters, we can control the editability for a specific cell. If for the combination of a row index and a col index, the method returns false then the cell whose index with that combination will not be editable. By default, this method always returns true (all cells are editable). Below is the examples.
       oTableModel.isCellEditable = function(iRow,iCol) {
          if (iRow == 1 && iCol == 0) return false;
          return true;
       }
        oTableModel.isCellEditable = function(iRow,iCol) {
          if (iRow == 1) return false;
          return true;
       }
        oTableModel.isCellEditable = function(iRow,iCol) {
          if (iCol == 0) return false;
          return true;
       }

You may search more conditions to determine the cell is editable or not, not only check the row index or column index directly.

Column Type

Each column in table has the specific type of data for value contained in all cells on that column. If the user types the invalid value then the value will be altered to default value of data type of that column or, as defined in TableModel, the old value will be rollbacked. The examples of default value are 0 for number type, the first option for options type, '00-00-0000' for date type etc. Each column type will have the appropriate cell editor to edit the cell's content. Each column type is defined when creating TableModel as described in previous section. To announce the column type, we must create an object of a column type class. Then this object become the item of the array that become the first parameter for creating TableModel. The following list is the classes of column type that are currently provided by JsTable. Each class declares some parameters that will become the properties of the created object. The parameters of each class is varied but the first four parameters must be columnName, inputName, width and align. The meaning of each parameters are:
    columnName is header/title of column that will be displayed on the top row in table.
   inputName is the name of form element representing each cell that will be sent to web server. Mostly, this form element is an <INPUT type=hidden>. This form element exists inside each cell and its value always represents the cell's content. For column type of boolean, the form element is <INPUT type=checkbox>. The value of columnName will become the value of attribute name of  those form elements. For column type of link, the value of columnName will become the value of attribute name of link. This rule has consequences that each column will send an array to web server (if submitted) that each item in array representing each value in the cells on the column. Note, if phpStyle is set to true in TableModel, each form element's name will be appended with '[]' to construct an array. For other server scripts, it may not construct an array if the table only has one row.
    width is initial width for the column. It's integer.
    align is the text alignment inside cell. The valid value is 'left', 'right' or 'center'.

Here, the available column class:
One more interesting column class is radio button (element <INPUT type=radio>). But because each row must have different name for its radios (each row has one group of radios and thus the radios have the same name, but different row must have different name because different group), not convenient to construct an array  for one column that will be sent to web server as HTTP POST/GET parameter. The radio column class can be substituted by options column class (JsTableColumnOptions).
 
Example:
    var columns = [
        new JsTableColumnString('String','string',120),
        new JsTableColumnNumber('Number','number',75),
        new JsTableColumnNumber('Denominated Number','denNumber',75,'right',true,2),
        new JsTableColumnBoolean('Boolean','boolean',50),
        new JsTableColumnOptions( 'Options','options',100,align,
            new JsTableOptionValues(['Satu','Dua','Tiga'],['_Satu','_Dua','_Tiga']) ),
        new JsTableColumnDate('Date','date',70,'center',true),
        new JsTableColumnLink('','link',50,'center','Edit',
            'javascript:editRow(__PRIMARY_KEY__)')
    ];
    var oTableModel = new JsTableModel(columns,true);

How To Create JsTable

To create JsTable, use the statement:

    oJsTable = new JsTable(sId,oTableModel,oParent,oNextSibling);

Now, oJsTable is holding the reference of an instance object of JsTable. Note, oJsTable doesn't refer to object of HTML Table element on which we will do editing but it holds the reference object that controls the table object.
Parameters:
Example:
    var oTableModel = new JsTableModel(columns,true,'.','d-m-y',true);
    var oJsTable = new JsTable('goodsList', oTableModel, document.forms[0], document.forms[0].elements['submit']);

Methods and Properties JsTable

Methods:
Properties:
All properties here must be treated as read only.

How To Edit and Navigate

To give focus to table, click on the table. The cell on which we click, automatically become the active cell. As said before, the active cell is the cell in which we can edit its content. If usually its cell editor is hidden for that cell, when the cell is active, it reveals its cell editor, so we can edit it.

Navigation:
    We can move the active cell by pressing the arrow keys on keyboard by intuitive direction. We can also click on a cell, if we want that cell become active.

Editing:
    To edit the cell's content needs some steps which is different for different cell editor. I will explain for each cell editor.

Event Handler (Not yet tested)

As usual term, the event handler is a function that will be executed when an event happens. JsTable supports some event handlers. Note, it's not event handler attached via DOM Event method, but it's only a method of JsTable that you can redefine. These event handlers are executed after all process for JsTable itself (you cannot cancel what JsTable does). Here are those event handlers:

Stylesheets

JsTable script, when embeded to a web page, will try to insert some stylesheet rules for the necessity of JsTable's appearance itself. This rules can be overwritten by you to fit your taste. The style rules of yours should be inserted after the JsTable script is inserted. Below is the default style rules inseted by JsTable script.

       .JsTable {
        background-color:black; }
    .JsTable TH {
        background-color:white;
        height:18px;
        font-family:arial,sans-serif;
        font-size:12px; }
    .JsTable TD {
        background-color:white;
        height:18px;
        font-family:arial,sans-serif;
        font-size:12px; }
    .JsTable TEXTAREA {
        background-color:#cccccc;
        margin:0px;
        padding:0px;
        font-family:arial,sans-serif;
        font-size:12px; }
    .JsTable INPUT {
        background-color:#cccccc;
        margin:0px;
        padding:0px;
         font-family:arial,sans-serif;
        font-size:12px; }
    .JsTable INPUT.checkbox {
        background-color:transparent; }
    .JsTable .cell-focus {
        background-color:#cccccc; }
    .JsTable SELECT {
        background-color:#cccccc;
        margin:0px;
        padding:0px;
        font-family:arial,sans-serif;
        font-size:12px;
        height:16px; }

There are some points to be explained here. All JsTable's class name is 'JsTable'. The rule for class 'JsTable' above is only to set background. This background, actually is used to make the border of cell. This is done by specifying attribute cellspacing of JsTable is higher than 0. So, the background color of JsTable will look like the border of cell. You should not create the rule for setting the border of cell.
As explained before, element TEXTAREA, INPUT and SELECT are used for cell editor. The background color of these element is distinguished from background color of cell. It is to distinguish which the active cell and not. Because the background of cell editor will be the background of active cell. There is also the class 'cell-focus' which is used to set the background of the active cell inside the column whose type of boolean and link. The checkbox and link as the cell editor are not too big to show that its cell is currently active.
Class 'checkbox' is used by checkbox. It is especially for Internet Explorer. Explore yourself.

Additional Methods For Standard Objects

JsTable enhance some standard javascript objects with some additional methods to support the process inside JsTable itself. However, once you insert JsTable script then those additional methods will be available for you. You may use them for your own purpose. I will explain these methods per one object.

Object String :
Object Date :

Known Bugs

JsTable has been tested on

Windows 2000/XP:
Linux Mandrake 10:
From testing, I found some bugs. May be, it's not bug but only naughty behaviour. I will explain per version of browser.

Bugs Report

You may send bugs reports to atmulyana@yahoo.com. Tell the exact version of your browser and under which Operating System you run the script.

Next Features

There may be some enhancement features in JsTable next time. However, the main feature I desire to implement is to read from HTML format and then translate it become an instance object of JsTable. So, you can see the template of JsTable. Another feature that is somewhat crucial, is smarter editing behavior, like in Excel. This would make the user feels more comfortable.