HTML and special types

TreeGrid documentation

Html type

Basic Html type without any special feature. It shows its value as is in html without any change.
It can also contain a link, use Link attribute.

Remember, to put HTML code into XML, you need to escape the '<' and '&' entities by &lt; and &amp;
If you include the XML directly into HTML page, you have to escape the entities twice: '<' by &amp;lt; and '&' by &amp;amp;
The Html type is not editable by default.
If set CanEdit="1" for Html type, the cell value is edited as the HTML code without any validation.
To define Html type, set column or cell attribute Type to "Html".
The HTML string displayed when the value is empty.
Usable especially for Select type or if used Button='Defaults' with Range='1'.
JSON named array of display values for particular cell values. All other cell values are displayed unchanged.
The items can contain HTML code. The names are case sensitive.
For example if <C Type="Html" Format = '{One:"Red", Two:"Green", Three:"<b>blue</b>"}'/> and the cell value is Two, it displays Green, if the cell value is Four, it displays Four.
Specifies format for editing - how the text will be modified for edit and the edited value back to data. For Html type is used especially for Defaults dialog to have name/key pairs.
JSON named array of input values for particular cell values. Format must start by '{'. All other cell values are edited unchanged. The items must not contain HTML code. The names are case sensitive.
For example if <C Type="Text" EditFormat = '{1:"one", 2:"two", 3:"three"}'/> and cell has value 2, the value for input will be two. If entered 'three', the cell value will be 3, if entered 'four', the cell value will be 'four'.
If and how the Html Type cell will be edited.
0 - As Html and only if the cell has explicitly set CanEdit='1'.
1 - As Html always except if the CanEdit attribute is set to '0'.
2 - As Text always except if the CanEdit attribute is set to '0'.
3 - Like 2, but it asks before saving the value if the original value contained some Html code.

Icon type

Shows one clickable image inside cell. To show more complex image button use Button Type.
It can also contain a link, use Link attribute.
It shows the image as background cell image to speed up rendering. To show <IMG> tag, place the <IMG> into Html type cell instead.
The Icon type cell cannot show left side Icon, because it uses the same logic.
The Icon type is not editable by default.
To define Icon type, set column or cell attribute Type to "Icon".
Cell value contains the image source URL.
The URL can be set also by <C Icon /> for the whole column.
The URL is relative to actual page URL, not to Grid.css, not to XML data!
How the image will be aligned. Case insensitive keyword: "Left", "Right", "Center".
Called on click to custom Icon type Icon.
x, y is click position inside the icon.
Return true to suppress the default action.

Abs type

Abs type shows one or more HTML elements absolutely positioned inside the cell in layers.
It does not affect row height, it is always overflowed.

The count of displayed tags is unlimited.
The tags are displayed in given order, the next tags overlays the previous.
To define Abs type, set column or cell attribute Type to "Abs".
Cell value is first character separated array: |x|y|width|height|html|cls|style|borderheight|x|y|width|height|html|cls|style|borderheight|x|...

x, y	position relative to left top cell edge.
width, height	ize of the tag. They can be void to not overflow the html tag, but the html tag is still overflowed by the final cell size (column width, row height).
html	any HTML code displayed on the position
cls	CSS class for the tag
style	inline style added for the part, e.g. background image
borderheight	(new 7.0) if set CSS class or style with border or padding, here must be set the height of the padding+border

Example: "|0|0|||<div style='background:red;height:100px;'></div>||||20|3|50|20|The text"

List type

List is HTML type to show more values with the same repeated parts for many rows.
It is intended to shorten the input XML, otherwise it can be always replaced by basic Html type.

The List type is not editable by default.
If set CanEdit="1" for List type, the cell value is edited as it is without any validation.
To define List type, set column or cell attribute Type to "List".
The value contains the array of items, separated by the first character.
The values are merged together using Format. The result can be any HTML code.
Syntax: |BaseFlags|BasePrefix|BasePostfix|Reserved|ItemPrefix|ItemPostfix|Search|Flags|Replace|Reserved|... |ItemNPrefix|ItemNPostfix|NSearch|NFlags|NReplace|NReserved
'|' is any character not contained in any section to separate section values.

'BaseFlags'	is bit array of main flags
1	does not insert ItemPrefix before the first item and ItemNPostfix after the last item
2	escape HTML code in item value
'BasePrefix'	is HTML code added to the beginning
'BasePostfix'	is HTML code added to the end
'Reserved'	is not used yet
'ItemPrefix'	is HTML code added in front of every item
'ItemPostfix'	is HTML code added after every item
'Search'	is RegExp string to replace it for 'Replace' string, for every item. 'Flags' are flags for RegExp, any of 'g', 'i', 'm'.
'Reserved'	is not used yet

If there are more sequences of ItemPrefix, ItemPostfix, ..., the values are used for items in order. For example if there are three sequences, the first sequence will be used for the first, the fourth and the seventh item, the second sequence for the second, the fifth, ...
Examples:

Editable Link type

For normal not editable links is better to use Link attribute.

The Link type represents editable link as HTML attribute <A HREF>.
It supports editing of the url and text, unlike the simple Link attribute.
To define Link type, set column or cell attribute Type to "Link".
Cell value contains array of values, first character is separator: |Url|Text|Window
Url is the link url
Text is a text to display, if is empty the Url is displayed instead
Window is browser window name where the link will be opened, for new window set "_blank"
Syntax: |UrlPrefix|UrlPostfix|HtmlPrefix|HtmlPostfix|BaseUrlType
'|' is any character not contained in any section to separate section values.
'UrlPrefix' is string added before link url
'UrlPostfix' is string added after link url
'HtmlPrefix' is html code added before link text
'HtmlPostfix' is html code added after link text
'BaseUrlType' is integer type, if BaseUrl (from <Cfg> tag) is added before url, 0 - no, 1 - yes
Syntax: |line|url|link
'|' is any character not contained in any section to separate section values.
'line' = 0 to edit all at one line, 1 to edit at more lines if needed, 2 to edit every value (url,text) at one line
'url' = 1 to display and edit link url
'text' = 1 to display and edit link text
String added before urls in types Img and Link, if their format specifies it.
Called after user clicks link at cell of type Link or Img.
It is not called for normal link defined by Link attribute.
Returns true to suppress default action. url is url opened in browser, target is target browser's window.
Called as <Actions> or cell event when the link is clicked.
Attach the action or any JavaScript code to the cell to be run on the click, like <I ... Col1OnClick='alert("changed!")' ... />
Return true to follow the link, false to cancel
If you display alert or confirm message in this dialog, you must set Grids.Alert = 1; alert("...."); Grids.Alert = 0; otherwise the link will not be followed.
Navigates to URL in Link or Img type in actual or focused cell.

Editable Img type

For normal not editable images is better to use Icon type.

The Img type represents editable image with optional link as HTML attribute <A HREF><IMG SRC></A>.
It supports editing of the url, size and link, unlike the simple Icon type.
To define Img type, set column or cell attribute Type to "Img".
Cell value contains array of values, first character is separator: "|image_URL|width|height|left|top|link_URL|link_window",

image_URL	URL with picture to display,
width, height,	Size of the image
left, top	Position of the image inside its source image, to display only part of the image, must be set with width and height.
link_URL	link to page displayed after click to image
link_window	browser window name (target) where the link will be opened, for new window set "_blank"

Example: "|/img/test.gif|100|100|0|200|/test/test.html" or "|/img/test2.gif" or "|/img/test.gif|||||/test/test.html"
Syntax: |UrlPrefix|UrlPostfix|HtmlPrefix|HtmlPostfix|LinkPrefix|LinkPostfix|BaseUrlType
'|' is any character not contained in any section to separate section values.
'UrlPrefix' is string added before source url
'UrlPostfix' is string added after source url
'HtmlPrefix' is html code added before image
'HtmlPostfix' is html code added after image
'LinkPrefix' is string added before link url
'LinkPostfix' is string added after link url
'BaseUrlType' is integer type, if BaseUrl (from <Cfg> tag) is added before urls, 0 - no, 1 - before source, 2 - before link, 3 - before both
Syntax: |line|src|extents|link
'|' is any character not contained in any section to separate section values.
'line' = 0 to edit all at one line, 1 to edit at more lines if needed, 2 to edit every value (src,extents,link) at one line
'src' = 1 to display and edit source
'extents' = 1 to display and edit extents (left, top, width, height)
'link' = 1 to display and edit link
String added before urls in types Img and Link, if their format specifies it.
Called after user clicks link at cell of type Link or Img.
It is not called for normal link defined by Link attribute.
Returns true to suppress default action. url is url opened in browser, target is target browser's window.
Navigates to URL in Link or Img type in actual or focused cell.

DropCols type

Special interactive cell to drag column captions or other such values here.
It is used for custom grouping, but it can be used for any other action.
Only for cell in Space rows.
To define DropCols type, set column or cell attribute Type to "DropCols".
Cell value contains comma separated array of names.
Since 9.2 it can contain any strings, not only column names.
JSON named array of display values for particular cell values. All other cell values are displayed unchanged.
The items can contain HTML code. The names are case sensitive.
For example if XXXType="DropCols" XXXFormat = '{One:"Red", Two:"Green", Three:"<b>blue</b>"}' XXX='Two,Four'/> it displays 'Green Four'.
Minimal width (in pixels) of every cell tab.
If the cell tab is column name, it uses the column width, but between MinCellWidth / MaxCellWidth
Maximal width (in pixels) of every cell tab.
If the cell tab is column name, it uses the column width, but between MinCellWidth / MaxCellWidth
If and how the item widths will be updated, bit array.

&1	The width will be shrunk if the sum is wider than the cell width.
&2	The width will be extended if the sum is more narrow than the cell width.
&4	If the item is column name, the column width will be ignored.

If it is possible to drop to this row an item dragged from outside (from another row or columns header).
0 The item cannot be deleted (does not affect moving to another row, see CanMove).
1 Item is deleted if moved outside any row.
2 Item is deleted if moved outside any row or to place where it is not accepted.
0 No moving items inside and outside the row (only deleting or copying or adding, if permitted by other attributes)
1 It is possible to move the items inside the same row. After such move the item is just placed to another position in the same row. Ignored for CanCopy=1/3
2 It is possible to move the items outside the row (to another row). After such move the item is removed from this source row. Ignored for CanCopy=2/3
3 Both moving inside and outside is permitted.
0 No copying items inside and outside the row (only deleting or moving or adding, if permitted by other attributes)
1 It is possible to copy the items inside the same row. After such copy the item is duplicated to another position in the same row. Only if also Duplicates is permitted.
2 It is possible to copy the items outside the row (to another row). After such copy the item remains also in the source row.
3 Both copying inside and outside is permitted.
If items with the same names are permitted in this row.
Empty - It permits duplicated column name like 1, if the column has set GroupMore; for other items (not column names) it permits duplicates like 2.
0 - Never.
1 - Yes, but not next to the same item.
2 - Yes, everywhere.
Comma separated list of item names that can be dropped to this row.
If not set, all items can be dropped here.
Comma separated list of DropCols cells in format: rowid1,col1,rowid2,col2,rowid3,...
If set it checks these cells for presence of the dragged value according to the SingleType.
The Single must not contain actual cell.
0 - Single ignored
1 - A value must be present maximally once in the cells (can be deleted).
2 - A value must be present exactly once in the cells.
3 - A value must be present minimally once in the cells (can be added).
A text displayed on empty area inside cell
Minimal width of the Text item part. In pixels
Set it to 1 to resize the cell to whole rest of the space row
Called as <Actions> or cell event when cell value is changed.
Attach the action or any JavaScript code to the cell to be run on cell value change, like <I ... Col1OnChange='alert("changed!")' ... />
The new value can be got by Get(Row,Col).
Called while dragging some item from DropCols and also on drop this item to some place.
grid, row, col is the source grid and cell.
value is the DropCols item name being dragged.
togrid, torow, tocol is cell under mouse cursor. Now it is not possible to drag to another grid, so the togrid = grid.
topos is actual position where the item will be dropped. Or -1 means delete item, -2 ignore action.
drop is true when the item is being dropped. The event is called once on the end with drop = 1.
Return null to not change anything or new topos value.

Upload File type

Type to select file(s) from local disk to upload them to server and / or display them in the cell.
Not available in Internet Explorer 9 and older!

The File Type cell by default shows right side Button="File". If the cell value is not empty, it automatically shows also left side Icon="Clear".
To not show the side button / icon, set the Button/Icon to different button or empty string.

The files are uploaded to server as standard <input type="file"> value under name "rowid$columnname".
If more files are uploaded for one cell, the next files have names "rowid$colname$index", with index starting 1. Note, the first file is without the index.
On server they are accessible: In ASP.NET in Request.Files collection, in PHP in $_FILES, in JSP by request.getPart() method.
To define File type, set column or cell attribute Type to "File".
Cell value contains the <input type='file'> DOM object. It is the only cell value in TreeGrid assigned by reference and not by value.
To access the actual files for upload by API use row[col].files as the file list array like in the standard <input type='file'>.
This cell value is uploaded to server separatelly as files under name.
Used to display the selected files in the cell.
It can contain any html code with some specific keywords to be replaced by the files attribute.

*Name*	File name with extension, but without the full path.
*Type*	File type, e.g. "image/gif".
*Size*	File size in bytes.
*Url*	Url of image or video file to display e.g. in <img> tag or in some tag background. Not available in IE9 and older browsers!
*Height*	Height of the cell in pixels.
*Width*	Width of the cell in pixels.

For example: Format="*Name* &lt;img src='*Url*' height='*Height*' width='*Height*'>"
HTML code that separates individual files defined by Format attribute.
Default value is ValueSeparatorHtml defined in <Lang><Format> in Text.xml.
If set to 1, it permits selecting more files, otherwise only one file.
File types that can be selected. The value is the same as <input type='file' accept> attribute.
It can be "audio/*" or "video/*" or "image/*" or any MIME type.
Called after the file dialog was closed.
input is actual <input type='file'> tag for the cell. Do not modify it.
Return true to clear the cell, false to continue.
Here you can restrict choosing some files, e.g. too long files:
Grids.OnSetFile = function(G,row,col,input){
for(var i=0;i<input.files.length;i++) if(input.files[i].size>100000){ alert("too large file"); return true; }
}
Shows the system dialog to select one or more files for the cell.