HTML and special types

TreeGrid documentation

Html type

Html type show in cell any HTML code as is without any change.
The HTML code must be fully valid. TreeGrid does not check the HTML code validity, the invalid HTML code can break down the whole grid layout!

HTML code in XML

To put HTML code into XML, you need to escape the '<' and '&' entities by &lt; and &amp; and if placed to XML attribute value also the '"' must be replaced by &quot;
If you include the XML data directly into HTML page, you have to escape the entities twice: '<' by &amp;lt; and '&' by &amp;amp; and '"' by &amp;quot;

Anchor links (<a href>)

Since 15.0 clicks to the <a href> links in the html code are handled the same as the Link attribute.
The links use the cell LinkBase and LinkTarget attributes and can be handles by the Link actions.

Editing HTML

The Html type is not editable by default. The editing must be explicitly permitted by CanEdit="1" for the cell or column or by EditHtml.
The Html type can be edited as plain text or plain HTML code according to EditHtml value.
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.
Since 15.0 it is read also from row.
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="Html" 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'.
Since 15.0 it is read also from row.
If and how the Html Type cell will be edited. For Html edited by HTML editor use EHtml type instead.
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.

EHtml type (HTML editor) since 15.0

Included in SpreadSheet component
Html editable as CSS styled text in contentEditable tag.
EHtml type is available since 15.0.
EHtml type show in cell any HTML code as is without any change, it preserves also white space and CR/LF.
The HTML code must be fully valid. TreeGrid does not check the HTML code validity, the invalid HTML code can break down the whole grid layout!
Not fully available in Internet Explorer 9 and older!

HTML code in XML

To put HTML code into XML, you need to escape the '<' and '&' entities by &lt; and &amp; and if placed to XML attribute value also the '"' must be replaced by &quot;
If you include the XML data directly into HTML page, you have to escape the entities twice: '<' by &amp;lt; and '&' by &amp;amp; and '"' by &amp;quot;

Anchor links (<a href>)

Since 15.0 clicks to the <a href> links in the html code are handled the same as the Link attribute.
The links use the cell LinkBase and LinkTarget attributes and can be handled by the Link actions.

Images (<img>)

Images can be inserted by opening local files by system dialog or by dropping image files to the cell. The can be also copied and pasted via clipoboard.
It is also possible to resize the images by mouse dragging during editing.
For inserting images see Insert image.

Editing HTML by HTML editor

The EHtml type is editable by default and it is editable as HTML by (contentEditable) HTML editor.
Also Auto type can be edited with the HTML editor if set AutoHtml=1.

The HTML editor actions add and modify only <span> tags for style modifications, <a> tags for links, <img> tags for images and <br> tags for new lines.
The tags are not nested, only <a> tag can contain the <span>, <img> and <br> tags and <span> tag can contain the <br> tags.
On begin editing all tags are made root to not be nested. All tags <b>, <i>, <strong>, <em>, <u>, <strike>, <sup>, <sub> and <font> are converted to <span> tags with appropriate style. Tags <div> are converted to <span> and separated by one <br>, tags <p> are converted to <span> and separated by two <br>.

The HTML editor permits these actions:
Enter - Enter key (depending on AcceptEnters settings) creates new line by <br> tag.
Bold - both actions BoldOn / BoldOff switch selected text or text from cursor between bold and normal. Adds / removes <b> tag in the source.
Italic - both actions ItalicOn / ItalicOff switch selected text or text from cursor between italic and normal. Adds / removes <i> tag in the source.
Underline - both actions UnderlineOn / UnderlineOff switch selected text or text from cursor between underlined and normal. Adds / removes <u> tag in the source.
Strike - both actions StrikeOn / StrikeOff switch selected text or text from cursor between strikeout and normal. Adds / removes <strike> tag in the source.
Superscript - action VAlignTop switches selected text or text from cursor between superscript (small text above) and normal. Adds / removes <sup> tag in the source.
Subscript - action VAlignBottom switches selected text or text from cursor between subscript (small text below) and normal. Adds / removes <sub> tag in the source.
Background color - actions SetColor, ChooseColor and NoColor set background color of selected text or text around cursor. Adds / removes <font style='background-color:xxx'> tag in the source.
Text color - actions SetTextColor, ChooseTextColor and NoTextColor set text color of selected text or text around cursor. Adds / removes <font style='color:xxx'> tag in the source.
Text shadow color - actions SetTextShadowColor, ChooseTextShadowColor and NoTextShadowColor set shadow color of selected text or text around cursor. Adds / removes <font style='textShadow:0px 0px 5px xxx'> tag in the source.
Text size - actions SetTextSize, ChooseTextSize and NoTextSize set font size of selected text or text around cursor. Adds / removes <font style='font-size:xxx;line-height:xxx'> tag in the source.
Text font - actions SetTextFont, ChooseTextFont and NoTextFont set font face of selected text or text around cursor. Adds / removes <font style='font-family:xxx'> tag in the source.
Clear style - action ClearStyle removes all styles from selected text.
Insert image - action OpenImage. The image files can be also dropped to the cell, see InsertImg setting.
Copy to clipboard - action Copy copies selected text to clipboard.
Cut to clipboard - action Exclude copies selected text to clipboard and deletes it.
Upper case - action UpperCase converts selected text to upper case.
Lower case - action LowerCase converts selected text to lower case.

By default the focused and edited cell has preset global background and text colors. To always show cell colors instead remove Class and Color from FocusCell attribute value, e.g. <Def><D Name='R' FocusCell='Border'></Def>.
To define EHtml type, set column or cell attribute Type to "EHtml".
The HTML string displayed when the value is empty.
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="EHtml" 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.
Since 15.0 it is read also from row.
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="EHtml" 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'.
Since 15.0 it is read also from row.
If set, the Auto type uses EHtml type instead of Lines type for the texts.

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.

Since 15.0 the Icon type can accept local files dropped to the cell or opened by system open file dialog, see Insert image.
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".
How the image will be resized / shrunk according to the cell size.
0 - no
1 - contain - resize the image to be displayed whole
2 - cover - resize the image to cover the whole cell, but preserve aspect ratio
3 - fill - resize the image to cover the whole cell regardless on aspect ratio
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	size 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:
Since 15.0 it is read also from row.

Editable Link type

The clicks to Link type are handled the same as in Link, see the events and actions at Link attribute.
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 inline in the cell as part of the cell value, 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". If not set, it is used LinkTarget
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
Since 15.0 it is read also from row.
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
Since 15.0 it is read also from row.
String added before urls in types Img and Link, if their format specifies it.
Deprecated since 15.0. Since 15.0 the Link type click is handled the same as Link attribute.
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.

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.

Since 15.0 the Img type can accept local files dropped to the cell or opened by system open file dialog, see Insert image.
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. The click to link is handled the same as to Link attribute.
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
Since 15.0 it is read also from row.
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
Since 15.0 it is read also from row.
String added before urls in types Img and Link, if their format specifies it.

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 File Type cell accepts also files dropped by mouse to the cell if set DropFiles.

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 an array of inserted file objects. 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] as the file list array like in the standard <input type='file'> files array.
This cell value is uploaded to server separately as files under name.
Before 15.0 the cell value contained the <input type='file'> DOM object, so the files were accessible as row[col].files, since 15.0 they are accessible as row[col].
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*'>"
Since 15.0 it is read also from row.
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.
Since 15.0 If set to 2, the files are added to the previous files array, to the end.
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.
files is array of files to add / insert. It is possible to change the array, especially remove individual items.
Prior to 15.0 the files was <input type='file'>
Return true to cancel the action, false to continue. Prior to 15.0 the return true cleared the cell, since 15.0 clear the cell by setting files.length = 0 and return false.
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.