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.
Since 16.2 if set to 2 it prefers during row span initialization the later RowSpan before the sooner RowSpan - it cuts the RowSpan when some spanned cell has set the RowSpan attribute.
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 focused or 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.
TreeGrid cannot span whole row or whole column, if the action is called to span whole rows or columns, it spans only already loaded cells in these rows / columns.
Splits all spanned cells in focused or selected range(s) or in actual cell.
Replaced by action Span.
Replaced by action Split.
Spans the range into one cell with value from cell [row1,col1].
Since 16.2 if set noshow, it does not display the changes in grid, re-render is required.
The noshow can be set also when spanning more cells individually in the same rows, to do the refresh only in the last span.
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. If and how will be cells automatically spanned and split to show their whole content. Bit array.
It is an alternative to Overlay.
1. bit &1 - The cells will be spanned or split vertically after value and its size changed.
2. bit &2 - The cells will be spanned or split horizontally after value and its size changed.
3. bit &4 - The cells will be spanned or split vertically on start. Can be slow!
4. bit &8 - The cells will be spanned or split horizontally on start. Can be slow!
5. bit &16 - If set, the cell will be auto spanned only through empty cells. The cell is not re-spanned if the next cell value is changed.
6. bit &32 - If set, the calculation will use actual row heights instead of default row heights. For bits 1 and 2.
Automatically spans the actual or focused cell through next rows and columns to show fully its content without changing the row height and overlaying the column.
Automatically spans the actual or focused cell through next rows to show fully its content without changing the row height.
Automatically spans the actual or focused cell through next columns to show fully its content without overlaying the column.
Automatically spans the cell through next rows and columns to show fully its content without changing the row height and overlaying the column.
type=1 spans only vertically, type=2 spans only horizontally, type=3 spans in both directions.
Returns true if changed the cell span.