DateTime Contrib

This topic is primarily meant for Foswiki developers.

Introduction

DateTime Contrib enables the use of the data type datetime in data forms. Under the hood it uses the extensive DateTime libraries, including:

DateTime Contrib adds the field definition Datetime to /lib/Foswiki/Forms/

Usage

Working with dates

  • Date-time strings are parsed as dates as long as they adhere to one of the input formats (see below).
  • Dates are rendered in local time and formatted according to Configure setting {DefaultDateTimeFormat}.
  • Times are in UTC and can have a time zone offset specified, either an offset number or a time zone name.
    • A time zone offset number is relative to UTC, in the form of a sign character (+/-) followed by a four digit time providing hours and minutes of the offset; no colon is used.
    • A time zone name is one of the Olson Time Zone names.

Supported input formats

Simplest 2012-05-05 15:28:37 UTC time is assumed
Time zone offset (number) 2012-05-05 15:28:37 -0500 Offset should not include Daylight Savings
Time zone name 2012-05-05 15:28:37 America/Nassau One of the Olson Time Zone names. Offset will be calculated automatically.
Time zone offset plus time zone name 2012-05-05 15:28:37 -0500 America/Nassau Probably redundant format

Supported output formats

Dates are rendered according to Configure setting {DefaultDateTimeFormat}, which may contain tokens shown in the table below.
Token Rendering
%a The abbreviated weekday name.
%A The full weekday name.
%b The abbreviated month name.
%B The full month name.
%c The default datetime format for the object's locale.
%C The century number (year/100) as a 2-digit integer.
%d The day of the month as a decimal number (range 01 to 31).
%D Equivalent to %m/%d/%y. This is not a good standard format if you want folks from both the United States and the rest of the world to understand the date!
%e Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.
%F Equivalent to %Y-%m-%d (the ISO 8601 date format)
%G The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ)
%g Like %G, but without century, i.e., with a 2-digit year (00-99).
%h Equivalent to %b.
%H The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j The day of the year as a decimal number (range 001 to 366).
%k The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)
%l The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)
%m The month as a decimal number (range 01 to 12).
%M The minute as a decimal number (range 00 to 59).
%n A newline character.
%N The fractional seconds digits - not supported.
%p Either 'AM' or 'PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as 'pm' and midnight as 'am'.
%P Like %p but in lowercase: 'am' or 'pm' or a corresponding string for the current locale.
%r The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to '%I:%M:%S %p'.
%R The time in 24-hour notation (%H:%M). (SU) For a version including the seconds, see %T below.
%s The number of seconds since the epoch.
%S The second as a decimal number (range 00 to 61).
%t A tab character.
%T The time in 24-hour notation (%H:%M:%S).
%u The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
%U The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.
%V The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also %U and %W.
%w The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%W The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.
%x The default date format for the object's locale.
%X The default time format for the object's locale.
%y The year as a decimal number without a century (range 00 to 99).
%Y The year as a decimal number including the century.
%z The time-zone as hour offset from UTC. Required to emit RFC822-conformant dates (using "%a, %d %b %Y %H:%M:%S %z").
%Z The time zone or name or abbreviation.
%% A literal '%' character.
Overview copied from DateTime.

Data form template

In a data form, specify datetime as type. For instance:
| *Name* | *Type*   | *Size* |
| Name   | text     | 100    |
| Date   | datetime | 35     |

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Contrib Info

Contrib Author: Foswiki:Main.ArthurClemens
Copyright: © 2012 Arthur Clemens and Foswiki Contributors
License: GPL (GNU General Public License)
Version: 14696 (2012-05-06)
Release: 1.0.0
Change History:  
06 May 2012 1.0 Arthur Clemens First release
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
License: GPL (GNU General Public License)
Plugin Home: http://foswiki.org/Extensions/DateTimeContrib
Support: http://foswiki.org/Support/DateTimeContrib
I Attachment Action Size Date Who Comment
DateTimeContrib.md5md5 DateTimeContrib.md5 manage 168 bytes 10 Oct 2012 - 22:01 ArthurClemens  
DateTimeContrib.sha1sha1 DateTimeContrib.sha1 manage 192 bytes 10 Oct 2012 - 22:01 ArthurClemens  
DateTimeContrib.tgztgz DateTimeContrib.tgz manage 718 K 10 Oct 2012 - 22:00 ArthurClemens  
DateTimeContrib.zipzip DateTimeContrib.zip manage 1 MB 10 Oct 2012 - 21:57 ArthurClemens  
DateTimeContrib_installerEXT DateTimeContrib_installer manage 47 K 10 Oct 2012 - 22:01 ArthurClemens  
Topic revision: r1 - 10 Oct 2012, ArthurClemens
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy