TreeGrid v6.3

Date type

TreeGrid documentation index

 

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

 

Calendar

 

<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.

 

Dates dialog for date ranges and repeating

 

<C> <cell>        string    Button      [“Dates”]                                                                                                                             new 7.0 .

It shows right side button to display popup Dates dialog on click to choose the date ranges.

This dialog is used for Text type in special format “Repeat1#Date1a~Date1b#Value1;Repeat2#Date2a~Date2b#Value2;...”

This format is used for GanttExclude, GanttBackground and Gantt resource Availability. And can be used also for any custom reason.

The default meaning of the format is repeat date range set by DateXa~DateXb every RepeatX time unit and optionally assign given ValueX to these ranges.

It is possible to set only Value as for all dates. It is also possible to omit Value to not use it. And it is possible to omit Repeat to not repeat the date range.

The Dates dialog shows new popup grid with columns defined by next attributes.

The popup grid has set its id to DatesDialog, you can control it in API events as usual, e.g. Grids.OnLoaded = function(G){ if(G.id==’DatesDialog’) { ... } }

The grid internal column names are Repeat, Start, StartTime, End, EndTime, Value.

Due internal implementation the Dates dialog is available only in Extended API!

 

<C> <cell>        type      DatesRepeatXXX                                                                                                                           new 7.0 .

Sets attribute XXX of column Repeat in the Dates grid.

Attribute Type of the Repeat column is Text by default.

For example set: DatesRepeatType="Enum" DatesRepeatEnum="||Weekly|Daily" DatesRepeatEnumKeys="||w|d"

To hide the column set DatesRepeatVisible=’0’

 

<C> <cell>        type      DatesStartXXX                                                                                                                                  new 7.0 .

Sets attribute XXX of column Start in the Dates grid.

Attribute Type of the Start column is Date by default.

For example set: DatesStartFormat="dddd, dddddd MMMM" DatesStartEditFormat="M/d/yyyy"

 

<C> <cell>        type      DatesStartTimeXXX                                                                                                                   new 7.0 .

Sets attribute XXX of column StartTime in the Dates grid.

Attribute Type of the StartTime column is Date by default.

This column is automatically hidden, if Start column is not of Type Date

 

<C> <cell>        type      DatesEndXXX                                                                                                                                    new 7.0 .

Sets attribute XXX of column End in the Dates grid.

Attribute Type of the End column is Date by default.

For example set: DatesEndFormat="dddd, dddddd MMMM" DatesEndEditFormat="M/d/yyyy"

 

<C> <cell>        type      DatesEndTimeXXX                                                                                                                     new 7.0 .

Sets attribute XXX of column EndTime in the Dates grid.

Attribute Type of the EndTime column is Date by default.

This column is automatically hidden, if End column is not of Type Date

 

<C> <cell>        type      DatesValueXXX                                                                                                                               new 7.0 .

Sets attribute XXX of column Value in the Dates grid.

Attribute Type of the Value column is Float by default.

For example set DatesValueType="Enum" DatesValueEnum="|-5|-4|-3|-2|-1|0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15"

To hide the column set DatesValueVisible=’0’

 

<C> <cell>        string    DatesXXXCaption                                                                                                                        new 7.0 .

Caption for the XXX column, where XXX can be Repeat, Start, End or Value.

 

<C> <cell>        bool       DatesEndLast            [1]                                                                                                                   new 7.0 .

If set to 1 and end date has not set time, it is shown as day before.

For example 1/1/2000 is shown as 12/31/1999, but 1/1/2000 1:00 is shown as 1/1/2000 1:00.

 

Localization

 

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>          int          FirstWeekYearDay               [3]                                                                                                       new 7.0 .

The first day in week to be the week marked as the first week in year.

Set it to 0 for U.S. week numberings and to 3 for ISO/European week numberings.

 

<Format>          string    NaD               [NaN]                                                                                                                                                     .

String displayed for incorrect date – Not a Date.