Cell spanning

TreeGrid documentation

Cells in TreeGrid can be spanned horizontally among columns, vertically among rows or in both directions together.
Since version 7.0 it is not possible to cross vertical and horizontal span, it is possible only to span rectangular areas.

Horizontal spanning among columns

Cells cannot be spanned between column sections (Left, Mid, Right).
It is possible to drag column into spanned range, the dropped column will get the span setting from the range.
It is possible to drag column outside spanned range, the dropped column will loose its col span and the cells become displayed.
It is possible to drag column inside the spanned range.
If you permit column moving between spanned columns, you should forbid saving the changes to cookies by <Cfg ColsPosLap='1'/>.
If grid contains any spanned cells between columns (<I Spanned='1'/>), the column moving is done by re-rendering whole grid. If the row contains any horizontally spanned cells among columns (marked with Span attribute).
Every row that contains some spanned or merged cells among columns must have set Spanned="1", otherwise the cell Span, Merge or MergeEdit attributes will be ignored. The name is not ColSpan, but Span only!
For horizontally spanned cell among columns, how many cells it covers, at least one. Including hidden columns.
The row with spanned cell must have set Spanned='1', otherwise the attribute is ignored.
In the whole spanned cell is shown value of this column. It can be changed by Merge attribute. To show more or other values in one cell. A comma separated list of column names to show in the cell.
The row with merged cell must have set Spanned='1', otherwise the attribute is ignored.
The cell will show values from all the row cells from the columns listed. The way of showing is specified by MergeFormat and MergeType.
The attribute is intended to show more values in spanned cell, but can be used also for display other or more values in any cell.
This attribute is ignored in export to Excel. If set, it specifies full HTML for display the merged values. The column names are replaced by the cell values.
If not set, the cell values are merged in <table> according to the 1. bit of MergeType.
For example "Path/Name.Ext" can be used for file path, where Path, Name and Ext are column names. Special MergeFormats used for particular Merge columns combination when some of the cells are empty.
Can be used to better specify what will be excluded from format instead of MergeType='4'.
The XXX are column names that are not empty for this row in the same order as in Merge.
For example for Merge='Path/Name.Ext' can be MergeFormatNameExt used when Path is empty. MergeFormat use when all merged cells are empty. MergeFormat used for editing. Set it especially when MergeFormat contains HTML code. If not set, the MergeFormat is used instead. Special MergeEditFormats used for particular Merge columns combination when some of the cells are empty.
Can be used to better specify what will be excluded from format instead of MergeType='4'.
The XXX are column names that are not empty for this row in the same order as in Merge.
For example for Merge='Path/Name.Ext' can be MergeEditFormatNameExt used when Path is empty. MergeEditFormat use when all merged cells are empty. Called after the cell with MergeFormat is edited. The val is the edited string, the result is default parsed val into array of cell values.
The order in result is the same as in MergeEditFormat.
Fill the result with new values if the value needs special parsing. Remember, the result has already filled its items.

For example, to parse file path in order Path, Name, Ext use such handler:
Grids.OnMergeChanged = function(G,row,col,val,res){
var idx = val.lastIndexOf("/");
if(idx>=0){ res[0] = val.slice(0,idx); val = val.slice(idx+1); } else res[0] = "";
var idx = val.lastIndexOf(".");
if(idx>=0) { res[1] = val.slice(0,idx); res[2] = val.slice(idx+1); } else { res[1] = val; res[2] = ""; }
} Used only without MergeFormat set. Specifies the one cell value that can be edited in merged cell. Only one value in merged cell can be edited without MergeFormat.
It is a column name. This column should be listed in Merge array.
The row with merged cell must have set Spanned='1', otherwise the attribute is ignored. Various flags for merging cells, bit array.
1. bit (&1) 0 - (only without MergeFormat) merged cells are displayed in one line (horizontally), 1 - merged cells are displayed in more lines (vertically)
2. bit (&2) 0 - if column is hidden, its cell value is removed too, 1 - all merged cell values are always visible regardless of column visibility. See FastMerge.
3. bit (&4) 1 - (only for MergeFormat) remove separated part after empty value (for the last column before empty value). If set to 1, ignores MergeType&2 (takes it as 1) for all cells when showing / hiding column.
It is faster, because the merged cells do not need to be refreshed. Controls sorting in Spanned row.
By default, the grid sorts spanned rows always according to value in sorted column, even if this is invisible due spanning.
You can set values in these columns for spanned rows to support sorting in the way you want.
Or you can set SortSpan = '1' and row will be sorted always according to spanned column's value. You can span the whole left column section and show here any HTML code.
All cell values in the section will be ignored. You can span the whole variable column section and show here any HTML code.
All cell values in the section will be ignored.
(Version 7.0) For cell paging it is shown only on the first column page, on the next ones is shown MidHtml2. For ColPaging the user section is spanned only through the one page, this value is shown on the second and next column pages in the middle section. You can span the whole right column section and show here any HTML code.
All cell values in the section will be ignored. Set to 1 if some MainCol cell is spanned between columns (has set Span attribute).
If set to 1, it shows tree icons in included <table> tag and slows down rendering.
Cannot be used when the main column cells have set RowSpan. Controls moving column, it is useful especially if there are some cells spanned to or from other columns.
If set to > 0, it is the block the column belongs to. Create blocks that contain the spanned cells. The blocks must be continuous.
The columns can be moved only inside its block and any other column cannot be moved into the block from outside.
The first (left) column in the block cannot be moved within the block and also must stay the first.
The whole block can be moved by dragging the first left column to another location.
It also preserves splitting block of columns to more pages when printing and for column paging.
Since 9.2 it was renamed from Group.

Vertical spanning among rows

IE8 strict mode has problems with rowSpan HTML attribute, so when using RowSpan switch IE8 to quirks mode (no !DOCTYPE) or to IE7 compatibility mode.
The functions problematic in IE8 strict mode and RowSpan: column with both RowSpan and Span - hide, show and move. Row with RowSpan - add, delete, move. Sort, filter and group are without problems.

In tree are all rows' children spanned according to its parent row. The last row's children are or are not included in range, according to the RowSpan is integer or not.
Cells are never spanned vertically among pages, the created page is always as high as to accommodate all spanned rows. In server paging you must ensure it by yourself.
Spanned rows are sorted and grouped together, their position within spanned range is always preserved.
It is possible to drag or add row into spanned range, the dropped row will get the span setting from the range.
It is possible to drag row outside spanned range, the dropped row will loose its row span and the cells become displayed.
It is possible to delete row from range, when deleted the first row (with RowSpan set), the range is split and the cells become visible, the row deleting will happen after uploading to server.
It is possible to drag whole spanned range by dragging the first row in range, when moved to another spanned range, the original spanned range is split.
It is possible to drag row inside the spanned range, only the first row (with RowSpan set) will stay always the first row in the range.
The row spanning was updated in version 7.0, in 6.x version it had various limitations and could broke layout in various cases. If the column contains any vertically spanned cells among rows (marked with RowSpan attribute).
Every column that contains some spanned cells among rows must have set Spanned="1", otherwise the cell RowSpan attribute will be ignored. For vertically spanned cell among rows, how many cells it covers, at least one. Including hidden rows.
In tree it is a count of rows on the same level as this row. All their children are spanned automatically.
(New in 7.0) The last row's children are spanned within range when added 0.5 to the RowSpan, e.g. RowSpan='3.5' means span for three row and also the last row's children. The 0.5 cannot be used in ReversedTree.
The column with spanned cell must have set Spanned='1', otherwise the attribute is ignored.

Dynamic spanning

The cells in grid can be spanned dynamically by a user. He can select the cells by mouse dragging or shift/ctrl + click and click to Join button on toolbar. The spanned cells can be similarly split by selecting them and clicking to Split button on toolbar. The actions for spanning / splitting can be attached also to any other event like right/middle button click or popup menu item action.
The changes can be also uploaded to server, see Upload_Type="Span" and Upload_Flags="Spanned"
Only variable rows can be dynamically spanned. Set it to 1 to show icons for spanning on Toolbar and also prepare grid for spanning when no cell in grid is spanned on start.
When set to 1, it also saves changes in span and column moving to Undo.
Since 12.0 if set to 2, it also sets Spanned = 1 to all default rows and columns.
To permit selecting cells or cell ranges set <Cfg SelectingCells='1'/>.
By default cells can be selected by Ctrl + mouse drag. To swap the action with dragging rows, set <Actions OnDragCell="SelectCells" OnCtrlDragCell="DragRow"/>.
To clear selection on click set <Actions OnClickCell="ClearSelection,FocusEdit" OnClickOutside="ClearSelection,Blur"/>. Spans selected cells into one cell spanned horizontally and / or vertically.
If the selected cells are not in one rectangle, it creates more rectangles from the selection and spans one by one.
If there were already some cells spanned and interfered with the ranges, they are cut and split.
Fails if there is no selected cell. Since 12.0 version without ...F fails if the actual cell is not selected.
Splits all spanned cells within selected range(s).
Fails if there is no selected cell. Since 12.0 version without ...F fails if the actual cell is not selected.
Spans focused cell range into one cell spanned horizontally and / or vertically.
Fails if there is no focused range. Version without ...F fails if the actual cell is not focused.
Splits all spanned cells within focused range.
Fails if there is no focused range. Version without ...F fails if the actual cell is not focused.
Splits spanned actual or focused cell.
Fails if the cell is not spanned. Spans the range into one cell with value from cell [row1,col1].
The [row1,col1] must be the upper left corner. Splits the spanned cell. The row, col can be any cell within the rectangle to split.