Date and Time
The Topic Maps Data Model offers the storage of date and time related information in occurrences of these three datatypes:
- http://www.w3.org/2001/XMLSchema#date
- http://www.w3.org/2001/XMLSchema#time
- http://www.w3.org/2001/XMLSchema#dateTime
When an occurrence type is connected to one of the above through an occurrence datatype constraint, Topincs will validate all values upon storage accordingly.
In addition the Topincs Form will use special input components to simplify date selection. The user can either textually edit the date corresponding to his current locale or use a date/time picker.
Timezone
Hint: Topincs time zone selection is currently hard to use. There is plans to improve it.
By default Topincs omits timezones meaning all dates and times are in local time and their interpretation is left to the human consumer whether it is someone looking at a factsheet or a programmer writing data processing code.
When users are distributed across time zones, the Topincs Form component can handle this with these two tweaks:
- The timezone selection element in the date/time picker has to be made visible with the help of a CSS rule for the topic type.
- A user can be forced to enter a timezone by using a compound constraint.
CSS rule for showing the time selector
Hint: You can edit the css for a specific
topic type by visiting the Source code for it through the page
menu on its fact sheet.
#form.tt1009 .t1007 .timezone-select {
display: block !important;
}
// id of the topic type is 1009 in this example
// id of the occurrence type is 1007
Validation code of a compound constraint forcing timezone input
function (date) {
return date !== null && date.isTimezoned() === false;
}
Programming
When a topic type has a topic occurrence constraint with a date/time
datatype, the getters of the API return instances TopincsDateTime
which is sub class of the standard PHP class DateTime.
For dates, only the date members will be significant. For times, only the time members. For dateTime, both are significant. The timezone is only considered, if the value actually holds a timezone, otherwise an untimezoned value will be saved. This can be tested by using is_timezoned (only necessary in rare cases).
When a setter is passed a standard DateTime object, it ignores
the time zone information. If time zone information is important,
you need to use TopincsDateTime and explicitly create
it with a TimeZone.
Alternatively the setter of an occurrence type always accepts the correctly formatted string value. It will be validated before writing it to the database.
Code fragments
// value of the occurrence will have no timezone information
$user->set_last_login(new DateTime());
// Passing an ISO 8601 formatted string
$person->set_date_of_birth("2012-01-01");
// This fails
$person->set_date_of_birth("01.01.2012");