Docs For Class DBLDateTimeField

Description

Field used to display/edit date and/or time.

This field it can be used to display and edit date and/or time values. It is quite complicated, since the date/time format differs from country to country.

The most important input is the datetime format. It is a string and it is very similar to the format passed to the strftime() function. It implements following conversion specifiers:

%Y - Year (4 digit)
%m - Month (numeric)
%b - Month (Textual, may be localized by setting the monthNames property. They may be got from locale in the future.)
%d - Day of month
%H - Hour (00..24)
%M - Minute
%S - Second
%I - Hour (00..12)
%P - AP/PM
%% - The % sign.

These characters are called parameters and upon format/edit thet are replaced by their values/edit boxes. Other characters in the string are kept intact.

The field provides several methods of the date editing (controlled by setting the editStyle property)

DBL_DES_SINGLE - User enters date in one input box. Entered string must follow the format passed to the field.
DBL_DES_SEPARATE - Each value has a separate input box.
DBL_DES_JS - Date is edited by a javascript popup. (Not yet implemented! Any volunteers?)

Since date/time format differs in each DB engine, the field requires that it is passed a query. This query is not used to query/modify database in any way, only it's date/time formatting/parsing functions are called. The query should be of the same class as is the query used to get/store date from the database. (It would be satisfactory to only pass class reference, but PHP cannot do this.)

INTERNAL NOTE: For internal purposes, the field passes datetime in an array, where keys are parameter letters (described above). Only the "YmdHMS" keys are considered, others are used only in zero/default values.

Located in /DBLDateTimeField.php (line 63)

DBLField
   |
   --DBLDateTimeField

Variable Summary

bool $containsDate

bool $containsTime

array $editStyle

array $emptyDateTime

int $filterSize

string $formatParams

array $formatSeparators

array $monthNames

DBLQuery $query

int $size

array $zeroDateTime

Method Summary

DBLDateTimeField DBLDateTimeField (string $name, string $titleTxt, string $titleHTML, string $format, DBLQuery &$query)

void acceptValue (mixed $value, mixed &$err, mixed &$r, mixed $new)

void checkValue (mixed $value, mixed &$err, mixed &$r, mixed $new)

string escapeRE (string $str)

void fixPM (array &$arr)

void formatDetail (mixed $value, mixed &$r)

void formatEdit (mixed $value, mixed &$r, mixed $dataSource, mixed $formName)

void formatFilter (mixed $value, mixed &$r, mixed $formName)

void formatIndex (mixed $value, mixed &$r)

string formatParsed (array &$dateTime)

string formatValue (mixed $value, array $dateTime)

void jsCheck (mixed $formName, mixed $new)

int monthNameToNumber (string $name)

void parseValue (string $value, &array &$arr, bool $zeroValues)

void setupBaseValues ()

Variables

bool $containsDate (line 106)

var: Internal flag saying whether format contains date.

bool $containsTime (line 110)

var: Internal flag saying whether format contains time.

array $editStyle (line 82)

var: Edit style to use (see class description).

array $emptyDateTime (line 98)

var: Internal, used to store "empty" time.

int $filterSize (line 90)

var: Size of the widget in filter form.

string $formatParams (line 73)

var: Internal string where format parameters (letters) are stored. (First parameter on index 0, second on index 1, etc.)

array $formatSeparators (line 68)

var: Internal array where characters between values are stored.

array $monthNames (line 94)

var: Month names. First element (month) must have index of 1, not 0!

DBLQuery $query (line 78)

var: Query object used to convert datetime from/to database format.

int $size (line 86)

var: Size of the widget in edit form.

array $zeroDateTime (line 102)

var: Internal, used to store "zero" time.

Inherited Variables

Inherited from DBLField

DBLField::$addAsterixes
DBLField::$allowEmpty
DBLField::$computed
DBLField::$dbName
DBLField::$default
DBLField::$detailAttributes
DBLField::$detailPostfix
DBLField::$detailPrefix
DBLField::$editAttributes
DBLField::$editPostfix
DBLField::$editPrefix
DBLField::$filterAttributes
DBLField::$filterPostfix
DBLField::$filterPrefix
DBLField::$indexAttributes
DBLField::$indexPostfix
DBLField::$indexPrefix
DBLField::$lookupField
DBLField::$name
DBLField::$needsMultipart
DBLField::$noOrderByTitle
DBLField::$readOnly
DBLField::$referenceURL
DBLField::$titleHTML
DBLField::$titleTxt
DBLField::$widgetAttributes

Methods

Constructor DBLDateTimeField (line 122)

Constructor.

DBLDateTimeField DBLDateTimeField (string $name, string $titleTxt, string $titleHTML, string $format, DBLQuery &$query)

string $name: Field name - see DBLField.
string $titleTxt: Textual title - see DBLField.
string $titleHTML: HTML title - see DBLField.
string $format: Field format - see class description.
DBLQuery $query: Query to parse/format database datetime - see class description.

acceptValue (line 457)

void acceptValue (mixed $value, mixed &$err, mixed &$r, mixed $new)

Redefinition of:

DBLField::acceptValue(): Accept value from post.

checkValue (line 452)

Check value method is not implemented in this class, since checking value is tightly integrated with parsing the value in acceptValue().

void checkValue (mixed $value, mixed &$err, mixed &$r, mixed $new)

Redefinition of:

DBLField::checkValue(): Check value (from post)

escapeRE (line 262)

Internal function - escape regular expression special characters.

return: Escaped string

string escapeRE (string $str)

string $str: String to escape

fixPM (line 272)

Internal function - if the AM/PM was used and is set to PM, advance hours.

void fixPM (array &$arr)

array $arr: Datetime to affect.

formatDetail (line 342)

void formatDetail (mixed $value, mixed &$r)

Redefinition of:

DBLField::formatDetail(): Format field for record detail.

formatEdit (line 347)

void formatEdit (mixed $value, mixed &$r, mixed $dataSource, mixed $formName)

Redefinition of:

DBLField::formatEdit(): Format field for record edit form.

formatFilter (line 437)

void formatFilter (mixed $value, mixed &$r, mixed $formName)

Redefinition of:

DBLField::formatFilter(): Format field for the filter form.

formatIndex (line 337)

void formatIndex (mixed $value, mixed &$r)

Redefinition of:

DBLField::formatIndex(): Format field for record index.

formatParsed (line 212)

Internal function to format datetime using user specified format.

Does not detect "empty" time.

return: Formatted date.

string formatParsed (array &$dateTime)

array $dateTime: Datetime in internal representation.

formatValue (line 246)

Internal function to convert value from database to user specified format.

Detects "empty" time correctly.

return: Formatted date.

string formatValue (mixed $value, array $dateTime)

array $dateTime: Datetime in internal representation.

jsCheck (line 442)

void jsCheck (mixed $formName, mixed $new)

Redefinition of:

DBLField::jsCheck(): Create javascript to check the field value before post.

monthNameToNumber (line 196)

Internal function to convert month name to number.

return: Month number (1-12), 0 when name not found.

int monthNameToNumber (string $name)

string $name: Month name

parseValue (line 290)

Internal function - parse value from user specified to internal (array) format.

void parseValue (string $value, &array &$arr, bool $zeroValues)

string $value: Value to parse.
&array $arr: Array where we store parsed datetime.
bool $zeroValues: True - use zero values, false - use empty values.

setupBaseValues (line 184)

Internal function to set emptyDateTime and zeroDateTime properties.

void setupBaseValues ()

Inherited Methods

Inherited From DBLField

DBLField::DBLField()
DBLField::acceptFilterValue()
DBLField::acceptValue()
DBLField::addCondition()
DBLField::checkValue()
DBLField::formatDetail()
DBLField::formatEdit()
DBLField::formatFilter()
DBLField::formatIndex()
DBLField::jsCheck()
DBLField::setTitle()
DBLField::splitValue()