summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAngie Byron2011-01-04 00:58:30 (GMT)
committer Angie Byron2011-01-04 00:58:30 (GMT)
commitde8e5566afe9e2f60452ca3d538b48d44bc69ea5 (patch)
treecbf91383bf80512c3d0bcad3d5256f0747e526ad
parent56d353c721997906098a137b1dcd62e661f917c2 (diff)
#989366 follow-up by jhodgdon: EVEN better docs for format_date() and friends.
-rw-r--r--modules/system/system.api.php79
1 files changed, 44 insertions, 35 deletions
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index bb13e09..fcc3a37 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -3717,15 +3717,21 @@ function hook_archiver_info_alter(&$info) {
* Define additional date types.
*
* Next to the 'long', 'medium' and 'short' date types defined in core, any
- * module can define additional types that can be used when displaying dates. A
- * date type is a key that can be passed to format_date() to return a date in
- * the configured display format, once a format has been assigned to it. To
- * assign a format to a date type, use
+ * module can define additional types that can be used when displaying dates,
+ * by implementing this hook. A date type is basically just a name for a date
+ * format.
+ *
+ * Date types are used in the administration interface: a user can assign
+ * date format types defined in hook_date_formats() to date types defined in
+ * this hook. Once a format has been assigned by a user, the machine name of a
+ * type can be used in the format_date() function to format a date using the
+ * chosen formatting.
+ *
+ * To define a date type in a module and make sure a format has been assigned to
+ * it, without requiring a user to visit the administrative interface, use
* @code variable_set('date_format_' . $type, $format); @endcode
* where $type is the machine-readable name defined here, and $format is a PHP
- * date format string. This can also be done in the administrative interface,
- * which allows date types defined here to be associated with date format
- * strings defined in hook_date_formats().
+ * date format string.
*
* To avoid namespace collisions with date types defined by other modules, it is
* recommended that each date type starts with the module name. A date type
@@ -3739,6 +3745,7 @@ function hook_archiver_info_alter(&$info) {
* @see format_date()
*/
function hook_date_format_types() {
+ // Define the core date format types.
return array(
'long' => t('Long'),
'medium' => t('Medium'),
@@ -3755,12 +3762,12 @@ function hook_date_format_types() {
* they appear to be provided by the system.
*
* @param $types
- * A list of date types. Each date type is keyed by name and the values are
- * associative arrays containing:
+ * A list of date types. Each date type is keyed by the machine-readable name
+ * and the values are associative arrays containing:
* - is_new: Set to FALSE to override previous settings.
- * - module: The name of the module that created the date format type.
- * - type: The date type name.
- * - title: The title of the date type.
+ * - module: The name of the module that created the date type.
+ * - type: The machine-readable date type name.
+ * - title: The human-readable date type name.
* - locked: Specifies that the date type is system-provided.
*/
function hook_date_format_types_alter(&$types) {
@@ -3772,40 +3779,42 @@ function hook_date_format_types_alter(&$types) {
/**
* Define additional date formats.
*
- * This hook is used to define the date format strings that are used to format
- * date types for different locales. Next to the 'long', 'medium' and 'short'
- * date types defined in core, any module can define additional date types in
- * hook_date_format_types(). For example, a date type could be
- * 'mymodule_extra_long' (defined in mymodule_date_format_types()), while a date
- * format string is like 'Y-m-d' and can be defined with this hook.
- *
- * A module may use this hook to provide date format strings for its own date
- * types provided in hook_date_format_types() or add date format strings to a
- * date type provided by another module or to the 'long', 'medium' and 'short'
- * date types provided by core.
+ * This hook is used to define the PHP date format strings that can be assigned
+ * to date types in the administrative interface. A module can provide date
+ * format strings for the core-provided date types ('long', 'medium', and
+ * 'short'), or for date types defined in hook_date_format_types() by itself
+ * or another module.
*
* Since date formats can be locale-specific, you can specify the locales that
* each date format string applies to. There may be more than one locale for a
* format. There may also be more than one format for the same locale. For
* example d/m/Y and Y/m/d work equally well in some locales. You may wish to
* define some additional date formats that aren't specific to any one locale,
- * for example, "Y m". For these cases the locales component should be omitted.
+ * for example, "Y m". For these cases, the 'locales' component of the return
+ * value should be omitted.
+ *
+ * Providing a date format here does not normally assign the format to be
+ * used with the associated date type -- a user has to choose a format for each
+ * date type in the administrative interface. There is one exception: locale
+ * initialization chooses a locale-specific format for the three core-provided
+ * types (see locale_get_localized_date_format() for details). If your module
+ * needs to ensure that a date type it defines has a format associated with it,
+ * call @code variable_set('date_format_' . $type, $format); @endcode
+ * where $type is the machine-readable name defined in hook_date_format_types(),
+ * and $format is a PHP date format string.
*
* @return
- * A list of date formats. Each date format is a keyed array consisting of
- * three elements:
- * - 'type': The date type name, as declared in an implementation of
- * hook_date_format_types().
+ * A list of date formats to offer as choices in the administrative
+ * interface. Each date format is a keyed array consisting of three elements:
+ * - 'type': The date type name that this format can be used with, as
+ * declared in an implementation of hook_date_format_types().
* - 'format': A PHP date format string to use when formatting dates. It
* can contain any of the formatting options described at
* http://php.net/manual/en/function.date.php
- * - 'locales': (optional) An array of 2 and 5 character locale codes; for
- * example, 'en', 'en-us'. The language codes are used to determine which
- * date format to display for the user's current locale. If more than one
- * date format is suggested for the same date type and locale, then the
- * first one will be used unless overridden via the administrative UI at
- * admin/config/regional/date-time/locale. If your date format is not
- * language-specific, leave this array empty.
+ * - 'locales': (optional) An array of 2 and 5 character locale codes,
+ * defining which locales this format applies to (for example, 'en',
+ * 'en-us', etc.). If your date format is not language-specific, leave this
+ * array empty.
*
* @see hook_date_format_types()
*/