w2grid.columns

Array of column objects.

Array, default = []

This array should be defined during the object creation, but it can be changed anytime thereafter. If you change the columns array, you will need to call .refresh() method to refresh the grid.

During object creation: Each column is an object with properties listed below:

column = {
    text           : '',    // column text (can be a function)
    field          : '',    // field name to map the column to a record
    size           : null,  // size of column in px or %
    min            : 20,    // minimum width of column in px
    max            : null,  // maximum width of column in px
    gridMinWidth   : null,  // minimum width of the grid when column is visible
    sizeCorrected  : null,  // read only, corrected size (see explanation below)
    sizeCalculated : null,  // read only, size in px (see explanation below)
    sizeOriginal   : null,  // size as defined
    sizeType       : null,  // px or %
    hidden         : false, // indicates if column is hidden
    sortable       : false, // indicates if column is sortable
    sortMode       : null,  // sort mode ('default'|'natural'|'i18n') or custom compare function
    searchable     : false, // bool/string: int,float,date,... or an object to create search field
    resizable      : true,  // indicates if column is resizable
    hideable       : true,  // indicates if column can be hidden
    autoResize     : null,  // indicates if column can be auto-resized by double clicking on the resizer
    attr           : '',    // string that will be inside the <td ... attr> tag
    style          : '',    // additional style for the td tag
    render         : null,  // string or render function
    title          : null,  // string or function for the title property for the column cells
    tooltip        : null,  // string for the title property for the column header
    editable       : {},    // editable object (see explanation below)
    frozen         : false, // indicates if the column is fixed to the left
    info           : null,  // info bubble, can be bool/object
    clipboardCopy  : false, // if true (or string or function), it will display clipboard copy icon
}

Size

The size of the column (width) can be in px or %. The size of 10 or the size of '10px' will define the same column width of 10px. The size of '10%' will define 10 percent width. You may define some columns in px and some in % for the same grid at the same time. When .refresh() method is called it will calculate size of all columns in px and store it in .sizeCalculated property. First it assigns size to the columns that defined in px, then it will distribute the remaining width between the columns defined in %. If total sum of columns defined in percentage will be more then 100, it will correct its values and record new size in .sizeCorrected.

SortMode

If set to "natural", a compare function is used that will result in an order that feels more natural to humans. This can be useful for IP addresses, or when numbers are used in strings, so that "48" (as a string) comes after "9" (as a string) - whereas the default sorting would put it the other way round.

If set to "i18n", a compare function is used that takes into account diacritical marks. For example, the letter "ä" would be sorted after "z" in default sort mode, while in "i18n" sort mode, the letter "ä" would be sorted between "a" and "b".

You can also pass a compare function in the same way you would use it as argument for Array.prototype.sort().

Render

The render function(record, extra) can be used to format the column data. If the function is defined then it will be executed for each cell in the column and anything this function returns will be used instead of the original column data. The render function will receive two arguments, first is the current record add the second is extra information, which is following object. The render function can be bound to any object, is it not bound to grid by default. This allows to execute it in the diferent context, that is often useful. You will still have reference to the grid in extra.grid property.

The render function can return a primitive value or an object. If it is an object, it will be used for different portions of the generated markap. This object has following structure If render function returns an object, it can be used to add a class and a style to the cell. For example: If render property is a string, then it is a formatter function from w2utils.formatters, you can add custom formatter functions. Below is the list of predefined formatters:

age - age in human readable format
currency - money format
date:date_format - date, see w2utils.settings
datetime:date_format|time_format - date & time, see w2utils.settings
float:XX - formatted number, where XX is number digits after comma
gmt - time in GMT
int - formatted integer, see w2utils.settings
interval - time interval in human readable format
money - money format, see w2utils.settings
number:XX, - formatted number, where XX is number digits after comma
password - password ****
percent - formatted percent
size, - file size in human readable format
time:time_format, - time, see w2utils.settings
timestamp - timestamp, see w2utils.settings
toggle - yes/no text

You can use them int he following way:

Editable

The editable property indicates if column fields are editable. If this field is an object, then the record can be edited inline by the user. This object is of the following structure: If the editable property is a function, it should return an object as described above. It will get same arguments as a render function would.

With this object you can supply other properties that will be passed to $('input').w2field(column.editable) so you can use any field type supported by w2field object. The type of the field can be one of the following:

text
int
float
hex
money
currency
percent
alphanumeric
date
time
datetime
color
list
combo
check
checkbox
select

You can make some of the reocrds not editable, for example:

Info

The info property can be either true or an object with the following structure:

info = {
    icon        : null,     // string|function|object, icon used in the cell, default: 'w2ui-icon-info'
    style       : null,     // string|function|object, style applied to the icon
    fields      : null,     // Array of field names, or a function that returns an array of field names,
                            // or an object in the form { 'caption_1': 'field_1', ..., 'caption_N': 'field_N' }
    render      : null,     // function to render the info bubble, gets passed (record, index, column_index)
    showEmpty   : false,    // flag to indicate if fields with empty values should be part of the bubble
    maxLength   : null,     // integer, max length of individual field values, after which they are cut off
    showOn      : 'click',  // string, e.g. 'mouseover|mouseenter|...',
    hideOn      : '',       // string, e.g. 'mouseout|mouseleave|...',
    options     : {},       // options that are passed to the w2tag constructor, e.g. options.position = 'top'
    ...                     // you can pass additional properties
}

There can only ever be one info bubble visible at a time. By default, the bubble will only show when you click the icon and will hide when you click anywhere else.