Columns Configuration

Columns configuration is specified by parameter columns and all settings are managed on its level.

webix.ui({
    view:"datatable",
    columns:[{...}, {...}],
});

With the help of the columns parameter you can:

specify headers/footers;
set widths of columns;
add built-in filter;
set built-in sorting;
set the text alignment in a column;
set the format of data presentation;
specify data of columns through math formulas;
specify data source for the column;
define templates for data presentation;
define individual CSS class for any column;
hide/show a column;
hide/show columns in groups;
add/delete columns dynamically;
group columns;
define colspans and rowspans;

Automatic Column Configuration

Normally, you need to specify an array of column configurations for the datatable, which allows setting various parameters for each column:

view:"datatable",
columns:[
    {id:"id", header:"Id", width:50, sort:"int"},
    {id:"title", header:[ "Film title",{content:"textFilter"}]
]

At the same time, you can switch to the data-based column configuration provided by the autoConfig property:

view:"datatable",
autoConfig:true

In this case the columns array is no longer needed. Datatable will analyze the dataset passed to it and build columns automatically. The columns will have default settings:

sort:"string" (columns that begin with $- are not included; these columns are helper fields, e.g. $css, $count);
editor:"text" (works only if editable:true in the datatable configuration);
fillspace:true for the first column, width:100 for the rest;
select:"row" (unless other setting is passed in the datatable configuration)

Headers/Footers

The header and footer are enabled by the parameters header and footer, correspondingly (by default, headers are enabled).

The values of the attributes header and footer can be both string and object. In case of string, you can put into the header text labels, images, HTML inputs, and links. See the details in the related section.

The object definition allows you to specify a more complex column presentation. As an object, a header/footer can contain the following properties:

text - the text label of a column;
colspan - the number of columns a cell should span;
rowspan - the number of rows a cell should span;
content - the built-in filter of a column (textFilter, selectFilter or any other from the list of filters);
tooltip - the tooltip for cells of the column, more details;
height - defines a custom height for a header line.

Defining header and footer for a specific column

// a simple string
webix.ui({
    view:"datatable",
    footer:true,
    columns:[
        { id:"col1", header:"Column 1", footer:"Footer 1" }
    ]
});
 
// an object
webix.ui({
    view:"datatable",
    footer:true,
    columns:[
        {
            id:"col1",
            header:[{ text:"Column1", colspan:"2"},{ content:"selectFilter" }],
            footer:[{ text:"Total", rowspan:"2"}, { text:" " } ]
        }
    ]
});

For more details, read the Headers and Footers article.

Widths of Columns

Setting the width of columns

To set widths of columns you should use the width attribute.

Setting the width of a column

columns:[
    { id:"col1",  width:200 }
]

Adjusting the width of columns to the parent container

To make a column or several columns fill the unused space of the parent container, use the fillspace attribute with the true value:

columns:[
   { id:"title", header:"Film title", fillspace:true },
//    ...
]

The column with the "title" value will take all the free space of the container. If there are more than one column with the enabled fillspace attribute, they will divide the free space between them.

Distributing free space between columns

If you want columns to divide the width of the datatable proportionally, set fillspace as numbers:

columns:[
   { id:"title", header:"Film title", fillspace:3 },
   { id:"year", header:"Released in", fillspace:1 },
   // ...
]

The "title" column is 3 times wider than the "year" column, which is 25 to 75 percent relation.

Adjusting column width to its content

To adjust the width of a column to the related content size, you can use the adjust attribute. There are three possible options:

data - (the default one) adjusts column width to the content of the widest item in it;
header - adjusts column width to its header content;
true - searches for the widest item among data and header(s) and adjusts column width to its content.

columns:[
    { id:"title", header:"Film title", adjust:"data" },
    { id:"rank", header:"Rank", adjust:"header" }
    // more columns
]

Pay attention that the resulting column's width won't be less than minWidth, in case this parameter is set for the column.

In case of a large dataset, you can limit the number of rows that will take part in the calculation of the maximum column width with the help of the adjustBatch attribute of the column config. The property works in tandem with the adjust:"data" or adjust:true attributes.

webix.ui({
    rows:[
        {
            view:"datatable",
            columns:[
                {id:"id"},
                {id:"title", adjust:"data", adjustBatch:50},
                {id:"title", adjust:true}
            ],
            //data count is big
            data:big_film_data
        }
    ]
});

For more details, read the Sizing and resizing article.

Built-in Filters

The header or footer of a column can contain a filter. See the full list of available filters.

A filter is set by the content property of the header attribute.

Adding filter to the header of a specific column

columns:[
    { id:"col1", header:[{ text:"Column 1", colspan:"2"}, { content:"selectFilter" }]},
    {/* ... */}
]

For more details, read the Filtering article.

Built-in Sorting

You are allowed to sort data in columns. The way of sorting depends on the column sorting type. There are several predefined sorting types:

"int"
"date"
"string"
"string_strict" (case-sensitive string sorting)
"text"
"server"
"raw"

You can also set a custom sorting type.

The sorting is specified by the sort attribute.

Activating sorting for a specific column

columns:[
    { id:"col1", sort:"string" },
    {/* ... */}
]

For more details, read the Sorting article.

Text Alignment

To set the text alignment in a column you should use attribute css:

Setting the text alignment in a column

<style>.myStyle{
    text-align:right;
}
</style>

columns:[
    { id:"col1" css:"myStyle"},//in a separate css class
    { id:"col2", css:{'text-align':'right'} //directly in the attribute
]

Read more about using the css attribute in the Styling article.

Data Formats

Formatting is applied to date and number values and defined for each column separately. To set some format for a column, use the format attribute.

Setting the format for a specific column

columns:[
    // data will be formatted according to the current locale
    {
        id:"col2", format:function(value){
            return webix.i18n.numberFormat(value);
        }
    }
]

Related sample: Using Date Templates

For more details, read the Number and Date formatting article.

Math in Columns

You can write simple math formulas to specify values in column cells. Formulas can be set for a whole column or for a single cell.

Using formulas for setting values in the whole column

columns:[
    { id:"col1", math:"[row_id,col_name] + [row_id,col_name]" }
]

For more details, read the Using Formulas article.

External Data Source for the Column

By default, column cells take values from the main data set of Datatable. You can provide data for the column from any source using the collection or options properties of the column. Column data can be taken from:

DataCollection
any data component (the source component must be initialized first)
URL with the path to the data file
array with id-value objects [{ id:1, value:"one"}, ...]
array with values ["one", "two"]
associative array { 1: "one", 2: "two"}
function / proxy

{
    view:"datatable",
    columns:[
        //ID of datatable
        { id:"product", header:"Product", options:"dash-pro" },
        //path to a script
        { id:"quantity", header:"Quantity", options:"data/goods/" },
        //array of objects
        { id:"price", header:"Unit price", options:[
            { id:"1", value:100 },
            { id:"2", value:200 }
        ] }
    ],
    url:"data/orderproducts/", //main data source
};

Regardless of the way you define options/collection, the column data will be stored in a datacollection and can be accessed via the column configuration, e.g. within a data template:

{
    view:"datatable",
    columns:[
        { id:"price", header:"Unit price", options:[
            { id:"1", price:100 },
            { id:"2", price:200 }
        ],
        template:function(obj, common, val, config){
            //config is column config
            return config.collection.getItem(obj.price).price;
        } }
    ],
    url:"data/orderproducts/", //main data source
};

DataCollections and Relational Databases

You can display connected tables from relational database in one datatable with the help of the collection property. To unite related tables and display the resulting data in a DataTable, use several DataCollections for each table and set up the DataTable columns to display values from the corresponding collections.

1. Sync the datatable with either of the collections:

$$("orders_grid").sync(orders);

2. Specify the other collections as data sources for the corresponding columns:

{
    view:"datatable", id:"orders_grid",
    columns:[
        { id:"date", header:"Order Date" },
        { id:"employee", header:"Employee", collection:employee },
        // other columns
    ]
}

Templates

Through attribute template, you can set a template of cells presentation corresponding to your needs.

Using templates for configuration data of a column

columns:[
    {
        id:"col4", template:function(obj){
            return obj.col1 + obj.col2*2 + obj.col3*3;
        }
    }
]

Related sample: Using String Templates

For more details, read the Data Templates article.

Styling

Many aspects of a column can be customized to achieve the desired look-and-feel. Column style can be adjusted in a CSS class and applied through the css attribute.

Applying a CSS class to a specific column

columns:[
    { id:"col1", css:"someStyle" }
]

For more details, read the Styling article.

Hiding/Showing Columns

Initially, all the datatable columns are visible by default unless a specific hidden property is used in its configuration:

var grid = new webix.ui({
    view:"datatable",
    columns:[
        //this column is hidden initially
        { id:"col1", header:"Title", hidden:true},
        //this column is visible
        { id:"col2", header:"Rating"}
   ]
})

Through the hideColumn() and showColumn() methods you can manipulate visibility of columns dynamically.

Hiding a column

grid.hideColumn("col2");

Setting Hidden/Visible Columns in Groups

Datatable API allows for setting the initially visible group of columns (visibleBatch) as well as show and hide any chosen column group defined by batch property:

grida = new webix.ui({
    view:"datatable",
    visibleBatch:1,
    columns:[
        { id:"id",  header:"#", css:"rank",  batch:2,   width:50},
        { id:"title", header:"Film title", fillspace:true },
        { id:"year",  batch:1,  header:"Released" , width:80},
        { id:"category", header:"Category", batch:1},
        { id:"votes", batch:3, header:"Votes",  width:100},
        { id:"rating", batch:3, header:"Rating", width:100},
        { id:"rank", header:"Rank", css:"rank",  batch:2,width:50}
    ]
});

Any column group can be shown with the showColumnBatch method that takes column batch value as parameter:

//show show id, rank
grida.showColumnBatch(2);
//show votes, rating
grida.showColumnBatch(3);

Related sample: Column Batches

Adding/Deleting Columns Dynamically

Since datatable columns is an array of JSON objects, you can treat it like any JavaScript array. At any moment you can add elements (columns) to this array and delete elements from it - and then repaint the datatable with the new configuration.

Replacing current columns with new ones

grid.config.columns = [/* ..new collection of columns.. */];
grid.refreshColumns();

In addition, Webix offers its own API for working with arrays:

webix.toArray() - converts an array to "Webix" array;
array.insertAt() - inserts an element to array into the specific position;
array.removeAt() - removes an element from the array at the specific position.

Adding/Removing Separate Columns

var columns = webix.toArray(grid.config.columns);
//adding
columns.insertAt({
    id:"c"+webix.uid(),
    header:"New column"
},2);
 
//deleting
columns.removeAt(2);
 
//refreshing
grid.refreshColumns();

Related sample: Adding/removing Columns

Grouping Columns

The functionality is available in Webix Pro edition only.

Column batches can be used to organize groups of columns that are shown/hidden by clicking on the header of an aggregating column:

For these needs a multiple line header is used. The first line of an aggregating column is defined via an object with the following properties:

content (string) - content-forming property, here: columnGroup. The property is also used to define header filters;
batch (string, number) - ID of the group;
groupText (string) - title of the group (it is shown when the group is in a closed state);
closed (boolean) - the initial state of the group, false by default;
colspan (number) - the number of columns in the group, including the aggregating one.

Also, each column that belongs to some group, should be given a group ID defined by batch property:

columns:[
    //aggregating column
    { id:"2008_1", header:[
      { content:"columnGroup", closed:true, batch:"2008", groupText:"2008", colspan:12},
      "January"
    ]},
    //other columns from the group
    { id:"2008_2",  batch:"2008", header:[null, "February"] },
    { id:"2008_3",  batch:"2008", header:[null, "March"] },
    { id:"2008_4",  batch:"2008", header:[null, "April"] },
    // ...
]

Read more about colspans and rowspans in Webix datatable header.

Setting Colspans/Rowspans

The feature is available in Webix Pro edition only.

Datatable allows defining colspans and rowspans by span configuration provided with the dataset within the data property of the grid.

To enable the rowspans and colspans functionality, you should set the spans parameter with the true value in the datatable configuration.

Each rowspan/colspan definition consists of the row id, column id, width and height of the span, value to display and css class to apply:

grida = new webix.ui({
    view:"datatable",
    columns:[...],
    spans:true,
    data:{
        data:grid_data,
        spans:[
            [1, "title", 3]
        ]
    }
});

Related sample: Colspans in Datatable

To learn more on this topic, please visit the Datatable Rowspans and Colspans article.

If you have not checked yet, be sure to visit site of our main product Webix html5 ui library and page of datagrid javascript product.