These are the functions and methodologies for date handling in Invenio.

Contents

1. Overview
2. Converting dates
3. Internationalizing parts of dates
4. Generating GUI elements

1. Overview

Three ways of representing dates are handled by this library:

datetext:

textual format => 'YEAR-MONTH-DAY HOUR:MINUTE:SECOND'
e.g. '2005-11-16 15:11:44'
default value: '0000-00-00 00:00:00'
This format is the the one used by current Database for storing dates.

datestruct:

tuple format => see Python reference
(YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, WEEKDAY, YEARDAY, DAYLIGHT)
e.g. (2005, 11, 16, 15, 11, 44, 2, 320, 0)
default value: (0, 0, 0, 0, 0, 0, 0, 0, 0)
This format is the one used by python. Time module provides methods for calculations.

dategui:

textual format for output => 'DAY MONTH YEAR, HOUR:MINUTE'
e.g. '16 nov 2005, 15:11' default value: _("N/A")

The dateutils python module provides ways of converting between these formats. The default value is used whenever a date is non-valid (for python, dates before epoch are unvalid!).

2. Converting dates

The functions for conversion are listed below.

convert_datestruct_to_dategui(datestruct, ln=CFG_SITE_LANG)

(2005, 11, 16, 15, 11, 44, 2, 320, 0) => '16 nov 2005, 15:11'
Month is internationalized

convert_datestruct_to_datetext(datestruct)

(2005, 11, 16, 15, 11, 44, 2, 320, 0) => '2005-11-16 15:11:57'

convert_datetext_to_dategui(datetext, ln=CFG_SITE_LANG)

'2005-11-16 15:11:57' => '16 nov 2005, 15:11'
Month is internationalized

convert_datetext_to_datestruct(datetext)

'2005-11-16 15:11:57' => (2005, 11, 16, 15, 11, 44, 2, 320, 0)

get_datestruct(year, month, day)

year=2005, month=11, day=16 => (2005, 11, 16, 0, 0, 0, 2, 320, -1)

get_datetext(year, month, day)

year=2005, month=11, day=16 => '2005-11-16 00:00:00'

3. Internationalizing parts of dates

The following functions provide means of internationalizing part of dates.

get_i18n_day_name(day_nb, display='short', ln=CFG_SITE_LANG)

get the string representation of a weekday, internationalized
@param day_nb: number of weekday UNIX like. => 0=Sunday
@param ln: language for output
@return the string representation of the day

get_i18n_month_name(month_nb, display='short', ln=CFG_SITE_LANG)

get a non-numeric representation of a month, internationalized.
@param month_nb: number of month, (1 based!) => 1=jan,..,12=dec
@param ln: language for output
@return the string representation of month

4. Generating GUI elements

The following functions create HTML fields for date selection:

create_day_selectbox(name, selected_day=0, ln=CFG_SITE_LANG)

Creates an HTML menu for day selection. (0..31 values).
@param name: name of the control (i.e. name of the var you'll get)
@param selected_day: preselect a day. Use 0 for the label 'Day'
@param ln: language of the menu
@return html as string

create_month_selectbox(name, selected_month=0, ln=CFG_SITE_LANG)

Creates an HTML menu for month selection. Value of selected field is numeric
@param name: name of the control (your form will be sent with name=value...)
@param selected_month: preselect a month. use 0 for the Label 'Month'
@param ln: language of the menu
@return html as string

create_year_inputbox(name, value=0)

Creates an HTML field (simple input) for year selection.
@param name: name of the control (i.e. name of the variable you'll get)
@param value: prefilled value (int)
@return html as string

create_year_selectbox(name, from_year=-1, length=10, selected_year=0, ln=CFG_SITE_LANG)

Creates an HTML menu (dropdownbox) for year selection.
@param name: name of control( i.e. name of the variable you'll get)
@param from_year: year on which to begin. if <0 assume it is current year
@param length: number of items in menu
@param selected_year: initial selected year (if in range), else: label is selected
@param ln: language
@return html as string