Message Providers
Overview
Some of the form elements need to automatically obtain (possibly localized) messages:
- Date element needs month and weekday names;
-
HTML_QuickForm2_Element_InputFile
needs error messages to display if its internal validation (checking
'error'field within$_FILESarray) fails.
Instead of giving all possible messages to each element, an object implementing HTML_QuickForm2_MessageProvider interface (or a callback with a signature similar to HTML_QuickForm2_MessageProvider::get()) is given which returns messages on-demand.
Default message provider
Default message provider will be used by 'date' and 'file'
elements if another one is not explicitly given. It contains an array of pre-translated messages
and allows overriding them and setting additional translations for new languages. As this message
provider is a Singleton, the updated translations will be available throughout the application.
Adding a new "translation"
<?php
HTML_QuickForm2_MessageProvider_Default::getInstance()->set(
array('date', 'months_long'),
'elderscrolls',
array("Morning Star", "Sun's Dawn", "First Seed", "Rain's Hand",
"Second Seed", "Mid Year", "Sun's Height", "Last Seed",
"Heartfire", "Frostfall", "Sun's Dusk", "Evening Star")
);
$date = HTML_QuickForm2_Factory::createElement(
'date', 'test', array(),
array('format' => 'd F Y', 'language' => 'elderscrolls')
)->setValue(
'2012-04-01'
);
// remove all tags from the output
$date->toggleFrozen(true);
$date->persistentFreeze(false);
echo $date;
?>
the output of the above code being
01 Rain's Hand 2012
If 'language' field is not explicitly given to element's constructor,
'language' option set with
<?php
HTML_Common2::setOption('language', '...');
?>
will be used, defaulting to 'en'.
Strftime message provider
This message provider will only work for 'date' elements and relies on strftime() function to generate
lists of months and weekdays. You will need to properly set LC_TIME locale
category for it to work.
Using Strftime message provider
<?php
setlocale(LC_TIME, 'ru_RU.CP1251', 'Russian_Russia.1251');
// Strftime message provider will be used if 'locale' is given as 'language' value
$date = HTML_QuickForm2_Factory::createElement(
'date', 'test', array(), array('format' => 'd F Y', 'language' => 'locale')
)->setValue(
'2012-04-01'
);
// remove all tags from the output
$date->toggleFrozen(true);
$date->persistentFreeze(false);
echo $date;
?>
which outputs (in CP1251 encoding, actually):
01 Апрель 2012