php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-08-26 14:26:54 +08:00
Code Issues Packages Projects Releases Wiki Activity

finished data formatting guide [skip ci]

Browse Source
This commit is contained in:
Qiang Xue
2015-06-03 21:23:38 -04:00
parent ca44b4e9c5
commit 47e9e7d0e3
2 changed files with 60 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
docs/guide/output-formatting.md
View File

@ -103,51 +103,53 @@ The following format shortcuts are supported (the examples assume `en_GB` is the
### Time Zones <span id="time-zones"></span> ### Time Zones <span id="time-zones"></span>
When formatting date and time values, Yii will convert them to the default [[yii\i18n\Formatter::timeZone|time zone]]. When formatting date and time values, Yii will convert them to the target [[yii\i18n\Formatter::timeZone|time zone]].
Therefore the input value is assumed to be in UTC unless a time zone is explicitly given. For this reason The value being formatted is assumed to be in UTC, unless a time zone is explicitly given or you have configured
it is recommended to store all date and time values in UTC, preferably as a UNIX timestamp, which is always UTC by definition. [[yii\i18n\Formatter::defaultTimeZone]].
If the input value is in a time zone different from UTC, the time zone has to be stated explicitly like in the following example:
In the following examples, we assume the target [[yii\i18n\Formatter::timeZone|time zone]] is set as `Europe/Berlin`.
```php ```php
// assuming Yii::$app->timeZone = 'Europe/Berlin'; // formatting a UNIX timestamp as a time
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00 echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
// formatting a datetime string (in UTC) as a time
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00 echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
// formatting a datetime string (in CEST) as a time
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00 echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
``` ```
Since version 2.0.1 it is also possible to configure the time zone that is assumed for timestamps that do not include a time zone
identifier like the second example in the code above. You can set [[yii\i18n\Formatter::defaultTimeZone]] to the time zone you use for data storage.
> Note: As time zones are subject to rules made by the governments around the world and may change frequently, it is > Note: As time zones are subject to rules made by the governments around the world and may change frequently, it is
> likely that you do not have the latest information in the time zone database installed on your system. > likely that you do not have the latest information in the time zone database installed on your system.
> You may refer to the [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data) > You may refer to the [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data)
> for details on updating the time zone database. > for details on updating the time zone database. Please also read
> See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment). > [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
Formatting Numbers <span id="numbers"></span> ## Formatting Numbers <span id="numbers"></span>
------------------
For formatting numeric values the formatter class provides the following methods: The formatter supports the following output formats that are related with numbers:
- [[yii\i18n\Formatter::asInteger()|integer]] - the value is formatted as an integer e.g. `42`. - [[yii\i18n\Formatter::asInteger()|integer]]: the value is formatted as an integer e.g. `42`.
- [[yii\i18n\Formatter::asDecimal()|decimal]] - the value is formatted as a decimal number considering decimal and thousand - [[yii\i18n\Formatter::asDecimal()|decimal]]: the value is formatted as a decimal number considering decimal and thousand
separators e.g. `2,542.123` or `2.542,123`. separators e.g. `2,542.123` or `2.542,123`.
- [[yii\i18n\Formatter::asPercent()|percent]] - the value is formatted as a percent number e.g. `42%`. - [[yii\i18n\Formatter::asPercent()|percent]]: the value is formatted as a percent number e.g. `42%`.
- [[yii\i18n\Formatter::asScientific()|scientific]] - the value is formatted as a number in scientific format e.g. `4.2E4`. - [[yii\i18n\Formatter::asScientific()|scientific]]: the value is formatted as a number in scientific format e.g. `4.2E4`.
- [[yii\i18n\Formatter::asCurrency()|currency]] - the value is formatted as a currency value e.g. `£420.00`. - [[yii\i18n\Formatter::asCurrency()|currency]]: the value is formatted as a currency value e.g. `£420.00`.
Note that for this function to work properly, the locale needs to include a country part e.g. `en_GB` or `en_US` because language only Note that for this function to work properly, the locale needs to include a country part e.g. `en_GB` or `en_US` because language only
would be ambiguous in this case. would be ambiguous in this case.
- [[yii\i18n\Formatter::asSize()|size]] - the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`. - [[yii\i18n\Formatter::asSize()|size]]: the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`.
- [[yii\i18n\Formatter::asShortSize()|shortSize]] - is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`. - [[yii\i18n\Formatter::asShortSize()|shortSize]]: is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
The format for number formatting can be adjusted using the [[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] and The format for number formatting can be adjusted using the [[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] and
[[yii\i18n\Formatter::thousandSeparator|thousandSeparator]] which are set by default according to the locale. [[yii\i18n\Formatter::thousandSeparator|thousandSeparator]], both of which take default values according to the
active [[yii\i18n\Formatter::locale|locale]].
For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]] For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]]
can be used to configure the internally used [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php) can be used to configure the [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php) used internally
to implement the formatter. For example, to adjust the maximum and minimum value of fraction digits, you can configure
For example, to adjust the maximum and minimum value of fraction digits, you can configure [[yii\i18n\Formatter::numberFormatterOptions]] property like the following: the [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
```php ```php
'numberFormatterOptions' => [ 'numberFormatterOptions' => [
@ -156,62 +158,62 @@ For example, to adjust the maximum and minimum value of fraction digits, you can
] ]
``` ```
Other formatters <span id="other"></span>
----------------
In addition to date, time and number formatting, Yii provides a set of other useful formatters for different situations: ## Other Formats <span id="other"></span>
- [[yii\i18n\Formatter::asRaw()|raw]] - the value is outputted as is, this is a pseudo-formatter that has no effect except that Besides date/time and number formats, Yii also supports other commonly used formats, including
- [[yii\i18n\Formatter::asRaw()|raw]]: the value is outputted as is, this is a pseudo-formatter that has no effect except that
`null` values will be formatted using [[nullDisplay]]. `null` values will be formatted using [[nullDisplay]].
- [[yii\i18n\Formatter::asText()|text]] - the value is HTML-encoded. - [[yii\i18n\Formatter::asText()|text]]: the value is HTML-encoded.
This is the default format used by the [GridView DataColumn](output-data-widgets.md#data-column). This is the default format used by the [GridView DataColumn](output-data-widgets.md#data-column).
- [[yii\i18n\Formatter::asNtext()|ntext]] - the value is formatted as an HTML-encoded plain text with newlines converted - [[yii\i18n\Formatter::asNtext()|ntext]]: the value is formatted as an HTML-encoded plain text with newlines converted
into line breaks. into line breaks.
- [[yii\i18n\Formatter::asParagraphs()|paragraphs]] - the value is formatted as HTML-encoded text paragraphs wrapped - [[yii\i18n\Formatter::asParagraphs()|paragraphs]]: the value is formatted as HTML-encoded text paragraphs wrapped
into `<p>` tags. into `<p>` tags.
- [[yii\i18n\Formatter::asHtml()|html]] - the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can - [[yii\i18n\Formatter::asHtml()|html]]: the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can
pass additional options such as `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`. pass additional options such as `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`.
- [[yii\i18n\Formatter::asEmail()|email]] - the value is formatted as a `mailto`-link. - [[yii\i18n\Formatter::asEmail()|email]]: the value is formatted as a `mailto`-link.
- [[yii\i18n\Formatter::asImage()|image]] - the value is formatted as an image tag. - [[yii\i18n\Formatter::asImage()|image]]: the value is formatted as an image tag.
- [[yii\i18n\Formatter::asUrl()|url]] - the value is formatted as a hyperlink. - [[yii\i18n\Formatter::asUrl()|url]]: the value is formatted as a hyperlink.
- [[yii\i18n\Formatter::asBoolean()|boolean]] - the value is formatted as a boolean. By default `true` is rendered - [[yii\i18n\Formatter::asBoolean()|boolean]]: the value is formatted as a boolean. By default `true` is rendered
as `Yes` and `false` as `No`, translated to the current application language. You can adjust this by configuring as `Yes` and `false` as `No`, translated to the current application language. You can adjust this by configuring
the [[yii\i18n\Formatter::booleanFormat]] property. the [[yii\i18n\Formatter::booleanFormat]] property.
`null`-values <span id="null-values"></span>
-------------
For values that are `null` in PHP, the formatter class will print a placeholder instead of an empty string which ## Null Values <span id="null-values"></span>
defaults to `(not set)` translated to the current application language. You can configure the
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to set a custom placeholder. Null values are specially formatted. Instead of displaying an empty string, the formatter will convert it into a
If you do not want special handling for `null` values, you can set [[yii\i18n\Formatter::nullDisplay|nullDisplay]] to `null`. preset string which defaults to `(not set)` translated into the current application language. You can configure the
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to customize this string.
## Localizing Data Format <span id="localizing-data-format"></span> ## Localizing Data Format <span id="localizing-data-format"></span>
All output of the formatter is localized when the [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed. As aforementioned, the formatter may use the currently active [[yii\i18n\Formatter::locale|locale]] to determine how
You can configure the [[yii\i18n\Formatter::locale|locale]] property of the formatter for this. If not configured, the to format a value that is suitable in the target country/region. For example, the same date value may be formatted
application [[yii\base\Application::language|language]] is used as the locale. See the [section on internationalization](tutorial-i18n.md) for more details. differently for different locales:
The Formatter will then choose the correct format for dates and numbers according to the locale including names of month and
weekdays translated to the current language. Date formats are also affected by the [[yii\i18n\Formatter::timeZone|timeZone]]
which will also be taken from the application [[yii\base\Application::timeZone|timeZone]] if not configured explicitly.
For example the date format call will output different results for different locales:
```php ```php
Yii::$app->formatter->locale = 'en-US'; Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014 echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014
Yii::$app->formatter->locale = 'de-DE'; Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014 echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014
Yii::$app->formatter->locale = 'ru-RU'; Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г. echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г.
``` ```
> Note that formatting may differ between different versions of the ICU library compiled with PHP and also based on the fact whether the By default, the currently active [[yii\i18n\Formatter::locale|locale]] is determined by the value of
> [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed or not. So to ensure your website works with the same output [[yii\base\Application::language]]. You may override it by setting the [[yii\i18n\Formatter::locale]] property explicitly.
> in all environments it is recommended to install the PHP intl extension in all environments and verify that the version of the ICU library
> is the same. See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment). > Note: The Yii formatter relies on the [PHP intl extension](http://php.net/manual/en/book.intl.php) to support
> localized data formatting. Because different versions of the ICU library compiled with PHP may cause different
> formatting results, it is recommended that you use the same ICU version for all your environments. For more details,
> please refer to [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
> >
> Note also that even if the intl extension is installed, formatting date and time values for years >=2038 or <=1901 > If the intl extension is not installed, the data will not be localized.
> on 32bit systems will fall back to the PHP implementation, which does not provide localized month and day names, >
> because intl uses a 32bit UNIX timestamp internally. On a 64bit system the intl formatter is used in all cases if installed. > Note that for date values that are before year 1901 or after 2038, they will not be localized on 32-bit systems, even
> if the intl extension is installed. This is because in this case ICU is using 32-bit UNIX timestamps to date values.

2
docs/internals/translation-status.md
View File

@ -55,7 +55,7 @@ input-validation.md | Yes
input-file-upload.md | Yes input-file-upload.md | Yes
input-multiple-models.md | input-multiple-models.md |
input-tabular-input.md | input-tabular-input.md |
output-formatting.md | output-formatting.md | Yes
output-pagination.md | Yes output-pagination.md | Yes
output-sorting.md | Yes output-sorting.md | Yes
output-data-providers.md | Yes output-data-providers.md | Yes