TreeGrid v6.3
Date type
Date type shows date and / or time in selected format.
It supports direct editing or selecting the date(s) from popup calendar.
<C> <cell> string Type [“Text”] Type=”Date” .
To define Date type, set column or cell attribute Type to “Date”
<cell> type value .
The date values in input XML can be set as string in these formats,
date: yyyy-M-d, M-d, M/d/yyyy, M/d, dd.MM.yyyy, dd.MM
time: HH:mm, HH:mm:ss, hh.mm, hh.mm.ss, including am/pm, AM/PM, a.m./p.m., A.M./P.M.
If set only time, it cannot be separated by dot.
The date values in input XML can be also set as number of milliseconds from 1/1/1970 00:00:00
The date values uploaded to server are by default in format “M/d/yyyy HH:mm:ss”, if some part of date is 0, it is omitted.
If some date in input XML is set as number of milliseconds, all uploaded dates are also in number of milliseconds. See <Cfg DateStrings/> attribute.
The date values in API are always integers as number of milliseconds from 1/1/1970 00:00:00
<C> <cell> bool CanEmpty [1] new 6.0 .
If the cell date value differ between 1/1/1970 00:00:00 and “”
It has sense especially for time only values.
If set to 0, the empty input value is always converted to 1/1/1970 00:00:00, internally to 0. So the cell never contains (empty) string value.
<C> <cell> string EmptyValue [“”] new 6.0 .
The string displayed when the date value is entered as empty string.
The cell can contain empty value only if CanEmpty is 1.
It is shown only for display, not for edit.
It is not escaped, it can contain HTML code.
<Cfg> <C> <cell> string DefaultDate new 6.3;upd 6.7.
Default date (and time) shown in calendar for empty dates.
(new 6.7) Used also when editing date / time in cell, the missing in the input are got from the DefaultDate.
For example input: “12/12” and DefaultDate: “1/1/2000 21:30” will return “12/12/2000 21:30”
<C> <cell> string Format upd 6.3 .
Specifies date and / or time string format – how the date and / or time will be displayed.
This format string uses almost the same formatting as Microsoft .NET System.DateTime.ToString (string format) function.
Empty format
If the Format is not set or is empty (default), the default English format is used “M/d/yyyy HH:mm:ss”.
If some part of the date is 0, it is omitted, some examples: “5/9/2000 12:43:56”, “12:00”, “6/5/2000”.
The language settings are ignored, the date separator is always ‘/’, the time separator always “:”.
Standard format
Standard format is one letter format. This format loads user format from file Text.xml, tag <Format>
d Short date ("M/d/yyyy")
D Long date ("d. MMMM yyyy")
t Short time ("H:mm")
T Long time ("H:mm:ss")
f Long date + short time ("d. MMMM yyyy H:mm")
F Long date + long time ("d. MMMM yyyy H:mm:ss")
g Short date + short time ("M/d/yyyy H:mm")
G Short date + long time ("M/d/yyyy H:mm:ss")
m, M Day and month ("d. MMMM")
s Sortable date time ("yyyy-MM-ddTHH:mm:ss")
u Universal sortable date time ("yyyy-MM-dd HH:mm:ssZ")
There are more standard formats with fixed meaning that cannot be changed in Text.xml.
r, R RFC1123 for example: Tue, 13 Jan 2004 18:12:34 GMT
y, Y Month and year for example: January 2004. For month name uses the attribute LongMonthNames2 (from file Text.xml, tag <Format>)
LongMonthNames2 could contain noun’s first case if the language supports it.
U Universal date time for example: 13. January 2004 17:12:34. This date time is converted to GMT !
User format
User format can contain any characters but only few have special meaning and other are written into output without any change.
: Place for time separator, defined in file Text.xml, tag <Format>, attribute TimeSeparator. (colon by default).
/ Place for date separator, defined in file Text.xml, tag <Format>, attribute DateSeparator. (slash by default).
d Month days 1 – 31
dd Month days 01 – 31
ddd Weekdays Sun – Sat
dddd Weekdays Sunday – Saturday
ddddd Weekdays S – S
dddddd Month days 1st – 31st
ddddddd Year weeks 1 – 52
D not used
DD The rest of days in week, in count of weeks from 1/1/1970 (it is not weekday!) (new 6.1)
DDD Year day 0 – 365 (new 6.1)
DDDD Count of days from 1/1/1970, for duration in days (new 6.1)
DDDDD Count of weeks from 1/1/1970, for duration in weeks, see DD (new 6.1)
DDDDDD Tenths of month days: empty,1,2,3 (new 6.3)
DDDDDDD Month days: 1-9,0-9,0-9,0-1 (new 6.3)
M Month 1 – 12
MM Month 01 – 12
MMM Month Jan – Dec
MMMM January – December
MMMMM Year quarters, I, II, III, IV
MMMMMM Year halves, I, II
y Year 0 – 99
yy Year 00 – 99
yyy Count of years from 1/1/1970, for duration in days (new 6.1)
yyyy Year 0000 – 9999
h Hours 1 – 12
hh Hours 01 – 12
hhh Count of hours from 1/1/1970 00:00:00, for duration in hours (new 6.1)
hhhh Tenths of hours empty or 1 (new 6.3)
hhhhh Hours 1-9, 0-2 (new 6.3)
H Hours 0 – 23
HH Hours 00 – 23
HHH not used
HHHH Tenths of hours empty or 1 (new 6.3)
HHHHH Hours 0-9, 0-9, 0-3 (new 6.3)
m Minutes 0 – 59
mm Minutes 00 – 59
mmm Count of minutes from 1/1/1970 00:00:00, for duration in minutes (new 6.1)
mmmm Tenths of minutes 0 – 5 (new 6.3)
mmmmm Minutes 0 – 9 (new 6.3)
s Seconds 0 – 59
ss Seconds 00 – 59
sss Count of seconds from 1/1/1970 00:00:00, for duration in seconds (new 6.1)
ssss Tenths of seconds 0 – 5 (new 6.3)
sssss Seconds 0 – 9 (new 6.3)
f Hundreds of milliseconds, 0 – 9 (new 6.3)
ff Tenths of milliseconds 00 – 99 (new 6.3)
fff Milliseconds – 000 - 999 (new 6.3)
ffff Tenths of milliseconds 0 – 9 (new 6.3)
fffff Milliseconds – 0 - 9 (new 6.3)
t First letter of AM/PM designator, by default A or P.
tt AM/PM designator, by default AM or PM. Defined in file Text.xml, tag <Format>, attributes AMDesignator and PMDesignator.
z Timezone hours -12, +0, +13
zz Timezone hours -12, +00, +13
zzz Timezone hours and minutes, -12:00, +0:00, +13:00
\ Escape character, the next character is placed to output without any changes. Use to place format characters as d,M,y,... It needs to be doubled ‘\\’
‘xxx’ or “xxx” Characters in quotes or double quotes are placed to output without any changes. Use to place format characters as d,M,y,...
% Place before format when use one character user format like ‘d’ (=> ‘%d’) to not be taken as standard format
For example: Format=’dddd, MMMM yyyy hh:mm:ss tt’ => “Sunday, February 2004 13:24:00”
Format=’”date:” MM/dd/yyyy“, time:” HH:mm” => “date: 10/03/2001, time: 12:34”
If you want add HTML tags before and after value, use rather cell attributes HtmlPrefix and HtmlPostfix instead of Format.
If you really need to place HTML tags into output (for example to use HTML tags for one part of date only), set <Cfg NoFormatEscape=’1’>. The HTML tags can be set in Format only, not in EditFormat.
<C> <cell> string EditFormat upd 6.0.
Format string for editing the date and / or time.
Empty format
If is not set or is empty, it accepts all formats like input XML:
date: yyyy-M-d, M-d, M/d/yyyy, M/d, dd.MM.yyyy, dd.MM
time: HH:mm, HH:mm:ss, hh.mm, hh.mm.ss, including am/pm, AM/PM, a.m./p.m., A.M./P.M.
If set only time, it cannot be separated by dot.
Standard or user format
Its structure is the same as Format, but not all formats are possible for input, only number inputs are supported.
The format should contains only these parts of custom format: d, dd, M, MM, y, yy, yyyy, h, hh, H, HH, m, mm, s, ss, t, tt
If set t or tt, as AM/PM are accepted only “a”,”p”,”am”,”pm” – it cannot be changed or localized.
The user can use more separators set by InputDateSeparators and InputTimeSeparators.
The user can also enter the date / time without separators, only as number, in formats like HHmm, HHmmss, MMddyy, MMddyyyy, in the order set in the EditFormat.
<C> <cell> string ExportFormat .
A date time format to export to Excel. Used only for Export_Type = 0.
When set <Cfg> ExportType&64 to export dates as string, this format is used as standard TreeGrid Format to format the date string.
Otherwise it is specific Excel date format to export the date as number.
If you don’t know the format for the cell, create xls file with one cell, specify its format you want and save it as web page (html file).
Open this htm file and search style property “mso-number-format” and its value set to the ExportFormat.
<Cfg> bool NoFormatEscape [1] chg 6.0 .
If set to “”, it means 0 for text and 1 for number and date.
If set to 0, the Format is escaped, so the characters & and < are displayed as they are.
If set to 1, you can use HTML tags in columns Format string, in prefix and postfix for text and anywhere for numbers.
<Cfg> type DateStrings [0/1] chg 6.0 .
If set to 0, Date values are uploaded as numbers (milliseconds from 1/1/1970), see also GMT attribute.
If set to 1, Date values are uploaded as strings in English format (M/d/yyyy HH:mm:ss).
If set to 2, Date values are uploaded as strings in JAVA format (yyyy-MM-dd HH:mm:ss).
If set to string, it specifies the full date format for upload
By default it is set to 0, if some date in input XML is set as number of milliseconds, otherwise is set to 1.
<Format> bool GMT [1] chg 6.0 .
If set to 1, all number dates are in GMT / UTC and are not affected by a user time zone, all users will see the same times.
If set to 0, all number dates are in the local time of user time zone, so they are shown different for different time zones.
The number dates are the input / output dates set as count of milliseconds from 1/1/1970 00:00:00.
The dates are internally stored always as the numbers, so if you access the cell values directly, you get / set always the count of milliseconds.
This setting is global for all grids on page!
<C> <cell> bool GMT new 6.2.
Cell GMT modification for display and edit.
If this attribute has different value than <Format GMT> value, it shows the cell date in local or GMT timezone.
It affect only display and editing date string, not the value itself, so for upload, API, calculations, sort, filter, search and Gantt are still used the original values.
<Format> int Hirji [0] RTL .
If grid uses and shows Persian Hirji / Jalali dates and calendar instead of standard Gregorian dates, bit array.
1. bit (&1) – 1 – All dates are displayed and entered in Hirji
2. bit (&2) – 2 – All dates in XML are in Hirji.
global func. string DateToString (Date date, string format) .
Converts date to string according to format string like in function ToString() in C#.NET.
date can be string or number, will be converted to date by standard Date(string).
If format is missing, uses English format “mm/dd/yyyy hh:mm:ss”, for today uses “hh:mm:ss”, for 00:00:00 uses “mm/dd/yyyy”, seconds are omitted if are 0.
global func. Date StringToDate (string str, string format) .
Converts string to date according to format string as in function ToString() in C#.NET.
If format is missing, converts str as in standard format for date “d.m.y”, “d.m”, “m/d/y”, “m/d”, “y-m-d”,”m-d” and time “hh:mm:ss”, “hh:mm” and for date and time combines these formats separated by any other character
<C> <cell> string Button [“Date”] .
For editable Date type is the button set to “Date” by default, except is set <Cfg AutoCalendar=’1’/>.
It shows right side button to display popup Calendar dialog on click to choose the date from.
To hide the calendar button set Button=””, it is useful especially for time only values.
<Cfg> bool AutoCalendar .
If set to 1, Calendar dialog for Date cells is displayed automatically when user starts editing. In this case the calendar reflects changes in the input and vice versa.
If set to 1, the Button type Date is not displayed for Date type by default. To display it, there must be explicitly set by Button=’Date’.
<C> <cell> bool AutoCalendar new 6.0 .
If set to 1, Calendar dialog for Date cells is displayed automatically when user starts editing. In this case the calendar reflects changes in the input and vice versa.
If set to 1, the Button type Date is still displayed for Date type by default. To hide it, there must be explicitly set by Button=’’.
The difference to <Cfg AutoCalendar/> is only in the default visibility of the Date button.
<C> <cell> int CalendarButtons [0/7] chg 6.0;upd 6.7.
Which calendar buttons will be visible. By default for empty value are all buttons displayed for Range and no button for standard date cells. Bit array.
1. bit (&1) – Today button, 2. bit (&2) – Clear button, 3. bit (&4) – OK button. = 0 no button visible, = 7 all buttons visible.
Since 6.7 there can be 4.bit (&8) for Yesterday button.
<C> <cell> string Calendar new 6.2 .
Full settings of the calendar in JSON format. See the documentation.
<Actions> ShowCalendar ...F Attached to events OnClickSideDate, OnEnter, OnCtrlDown .
Displays the Calendar dialog for selecting date for the actual or focused cell
API event bool OnCanEditDate (TGrid grid, TRow row, string col, Date date) .
Called when displaying Calendar dialog for every date in the calendar to permit only some dates to be selected by user.
global func. TCalendar ShowCalendar (TCalendar Calendar, TPosition Pos, function Func, type Date) new 6.2 .
Shows custom calendar on given position. For more information see the ShowCalendar.
The default date format and setting are specified in Text.xml, in <Lang><Format /></Lang> tag.
The default settings is for English language, changing the Format tag attributes you can easily localize it to another language.
<Format> string[] ShortDayNames .
The week day short names, starting Sunday, used for the format “ddd”
Default is "Sun,Mon,Tue,Wed,Thu,Fri,Sat"
<Format> string[] LongDayNames .
The week day full names, starting Sunday, used for the format “dddd”
Default is "Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday"
<Format> string[] Day1CharNames .
The week day one character names, starting Sunday, used for the format “ddddd”
Default is "S,M,T,W,T,F,S"
<Format> string[] Day2CharNames .
The week day calendar names, starting Sunday, used in calendar.
Default is "Su,Mo,Tu,We,Th,Fr,Sa"
<Format> string[] DayNumbers .
The month day numbers 1 – 31, used for the format “dddddd”
Default is "1st,2nd,3rd,4th,5th,6th,7th,8th,9th,10th,11th,12th,13th,14th,15th,16th,17th,18th,19th,20th,21st,22nd,23rd,24th,25th,26th,27th,28th,29th,30th,31st"
<Format> string[] ShortMonthNames .
The month short names, starting January, used for the format “MMM”
Default is "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
<Format> string[] LongMonthNames .
The month full names, starting January, used for the format “MMMM” and also in calendar
These names are expected for month name with day, like 20th January 2000.
Default is "January,February,March,April,May,June,July,August,September,October,November,December"
<Format> string[] LongMonthNames2 .
The month full names, starting January, used for the format “MMMMMMM”
These names are expected for month name without day, like January 2000.
Default is "January,February,March,April,May,June,July,August,September,October,November,December"
<Format> string[] Quarters .
The year quarter names or numbers, used for the format “MMMMM”
Default is "I,II,III,IV"
<Format> string[] Halves .
The year half names or numbers, used for the format “MMMMMM”
Default is "I,II"
<Format> string DateSeparator [/] .
The string displayed in place of ‘/’ in the format string. It is intended to separate date parts.
<Format> char[] InputDateSeparators [/.-] new 6.0 .
The characters accepted as date separator while editing
<Format> string TimeSeparator [:] .
The string displayed in place of ‘:’ in the format string. It is intended to separate time parts.
<Format> char[] InputTimeSeparators [:] new 6.0 .
The characters accepted as time separator while editing
<Format> string AMDesignator [AM] .
The string displayed for dates before noon. It is used only for display.
<Format> string PMDesignator [PM] .
The string displayed for dates after noon. It is used only for display.
<Format> int FirstWeekDay [0] .
The starting day of the week, the 0 is Sunday, 1 Monday, ....
It is used by Calendar dialog.
<Format> string NaD [NaN] .
String displayed for incorrect date – Not A Date.
.