Defining Columns

ZiadJ edited this page Dec 9, 2012 · 15 revisions

In KoGrid, you can define what columns your grid will display using the columnDefs configuration option.

A columnDef (short for ColumnDefinition) includes the following properties:

  • field (required): The property that the column should bind to
  • displayName (optional) : The name that the column header will display (defaults to field if not provided)
  • cellTemplate (optional) : The id of the <script type="text/html"> tag that contains the cell template you want this column to use
  • cellClass (optional) : The css class you would like to be applied to all data cells in that column
  • cellFilter (optional) : Function that takes the value of your data as the first argument and returns transformed data to display
  • aggLabelFilter (optional) : Same as the cellFilter but can be defined separately for aggregate row labels.
  • headerClass (optional) : The css class you would like to be applied to the header in that column
  • headerCellTemplate (optional) : The element ID of the template you want to use for the column's header
  • sortable (optional) : Defines whether or not the column is sort-able
  • resizable (optional) : Defines whether or not the column is resize-able
  • sortFn (optional) : Sorting algorithm for the column in case you prefer a fancy sort.
  • headerCellTemplate (optional): Template for the header cell.
  • visible (optional) : Initial visible state of the column, defaults to true.
  • width (optional) : The width (px) that you would like the column to display (outerWidth of the column)
  • minWidth (optional) : Minimum column width when resizing (default 50px)
  • maxWidth (optional) : Maximum column width when resizing (default 9000px)

An example of defining the columns of a grid looks like:

<div data-bind="koGrid: { data: myDataSource, 
                          columnDefs: [{ field: 'firstName', displayName: 'First Name', width: 90 },
                                       { field: 'lastName', displayName: 'Last Name', width: 80 },
                                       { field: 'age', cellClass: 'ageCell', headerClass: 'ageHeader' }]">
</div>

Width can also be defined in percentages (20%, 30%) or in weighted *s (much like WPF/Silverlight) example:

<div data-bind="koGrid: { data: myDataSource, 
                          columnDefs: [{ field: 'firstName', displayName: 'First Name', width: '*'},
                                       { field: 'lastName', displayName: 'Last Name', width: '*' },
                                       { field: 'age', cellClass: 'ageCell', headerClass: 'ageHeader', width: '**' }]">
</div>

If the div bound to the koGrid is 400px wide then having 4 total *s would make each star worth 100px each. Column 1 would be 100px wide, Column 2: 100px, and Column 3: 200px. This is always rounded down. In the event that you have a grid 1000px wide with two columns and 3 total stars you would have 1 pixel remaining and each * worth 333 pixels

The widths are calculated in the following order:

  • Pre-defined width (width: 50)
  • Asterisks (width: "**") Rounded down
  • Percentages (width: "33%") Rounded down

Special note on percentages:

You can go over 100% of grid width, this is intended. If you have a grid 1000px wide with 4 columns, You can specify each column to be 50% width. This will result in each column being 500px wide and the Viewport overflowing as intended.