finished guide on formatting

docs/guide/caching-data.md

@@ -29,7 +29,8 @@ if ($data === false) {
 Data caching relies on the so-called *cache components* which represent various cache storage,
 such as memory, files, databases.
 
-Cache components are usually registered as application components so that they can be globally configurable
+Cache components are usually registered as [application components](structure-application-components.md) so
+that they can be globally configurable
 and accessible. The following code shows how to configure the `cache` application component to use
 [memcached](http://memcached.org/) with two cache servers:
 

docs/guide/db-active-record.md

@@ -97,7 +97,7 @@ Connecting to Database
 ----------------------
 
 Active Record uses a [[yii\db\Connection|DB connection]] to exchange data with database. By default,
-it uses the `db` application component as the connection. As explained in [Database basics](db-dao.md),
+it uses the `db` [application component](structure-application-components.md) as the connection. As explained in [Database basics](db-dao.md),
 you may configure the `db` component in the application configuration file like follows,
 
 ```php

docs/guide/db-dao.md

@@ -76,7 +76,7 @@ $primaryConnection = \Yii::$app->db;
 $secondaryConnection = \Yii::$app->secondDb;
 ```
 
-If you don't want to define the connection as an application component you can instantiate it directly:
+If you don't want to define the connection as an [application component](structure-application-components.md) you can instantiate it directly:
 
 ```php
 $connection = new \yii\db\Connection([

docs/guide/db-migrations.md

@@ -178,7 +178,7 @@ After applying a migration, the migration tool will keep a record in a database
 table named `migration`. This allows the tool to identify which migrations
 have been applied and which are not. If the `migration` table does not exist,
 the tool will automatically create it in the database specified by the `db`
-application component.
+[application component](structure-application-components.md).
 
 Sometimes, we may only want to apply one or a few new migrations. We can use the
 following command:
@@ -293,7 +293,7 @@ line:
   migration history information. It defaults to `migration`. The table
   structure is `version varchar(255) primary key, apply_time integer`.
 
-* `db`: string, specifies the ID of the database application component.
+* `db`: string, specifies the ID of the database [application component](structure-application-components.md).
   Defaults to 'db'.
 
 * `templateFile`: string, specifies the path of the file to be served as the code
@@ -341,7 +341,7 @@ can be also configured this way.
 
 ### Migrating with Multiple Databases
 
-By default, migrations will be applied to the database specified by the `db` application component.
+By default, migrations will be applied to the database specified by the `db` [application component](structure-application-components.md).
 You may change it by specifying the `--db` option, for example,
 
 ```

docs/guide/output-data-widgets.md

@@ -135,13 +135,13 @@ You may specify various container HTML options passing arrays to:
 - `footerOptions`
 - `filterOptions`
 
-#### Data column
+#### Data column <a name="data-column"></a>
 
 Data column is for displaying and sorting data. It is default column type so specifying class could be omitted when
 using it.
 
 The main setting of the data column is its format. It could be specified via `format` attribute. Its values are
-corresponding to methods in `format` application component that is [[\yii\i18n\Formatter|Formatter]] by default:
+corresponding to methods in `formatter` [application component](structure-application-components.md) that is [[\yii\i18n\Formatter|Formatter]] by default:
 
 ```php
 <?= GridView::widget([

docs/guide/output-formatter.md

@@ -2,7 +2,7 @@ Data Formatter
 ==============
 
 For formatting of outputs Yii provides a formatter class to make data more readable for users.
-[[yii\i18n\Formatter]] is a helper class that is registered as an [application component](concept-components.md) named `formatter` by default.
+[[yii\i18n\Formatter]] is a helper class that is registered as an [application component](structure-application-components.md) named `formatter` by default.
 
 It provides a set of methods for data formatting purpose such as date/time values, numbers and other commonly used formats in a localized way.
 The formatter can be used in two different ways.
@@ -31,7 +31,7 @@ The formatter can be used in two different ways.
 
 All output of the formatter is localized when the [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed.
 You can configure the [[yii\i18n\Formatter::locale|locale]] property of the formatter for this. If not configured, the
-application [[yii\base\Application::language|language]] is used as the locale. See the [Section on internationaization](tutorial-i18n.md) for more details.
+application [[yii\base\Application::language|language]] is used as the locale. See the [section on internationalization](tutorial-i18n.md) for more details.
 The Formatter will then choose the correct format for dates and numbers according to the locale including names of month and
 week days translated to the current language. Date formats are also affected by the [[yii\i18n\Formatter::timeZone|timeZone]]
 which will also be taken [[yii\base\Application::timeZone|from the application]] if not configured explicitly.
@@ -53,13 +53,13 @@ echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014
 > is the same. See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
 
 
-Configuring the format
-----------------------
+Configuring the formatter <a name="configuring-format"></a>
+-------------------------
 
-The default format of the Formatter class can be adjusted using the properties of the formatter class.
+The default formats used by the formatter methods can be adjusted using the properties of the [[yii\i18n\Formatter|formatter class]].
 You can adjust these values application wide by configuring the `formatter` component in your [application config](concept-configurations.md#application-configurations).
 An example configuration is shown in the following.
-For more details about the available properties check out the [[yii\i18n\Formatter|API documentation of the Formatter class]].
+For more details about the available properties check out the [[yii\i18n\Formatter|API documentation of the Formatter class]] and the following subsections.
 
 ```php
 'components' => [
@@ -72,63 +72,112 @@ For more details about the available properties check out the [[yii\i18n\Formatt
 ],
 ```
 
-Formatting Dates
-----------------
+Formatting Date and Time values <a name="date-and-time"></a>
+-------------------------------
 
-> Note: This section is under development.
+The formatter class provides different methods for formatting date and time values. These are:
 
-TDB
+- [[yii\i18n\Formatter::asDate()|date]] - the value is formatted as a date e.g. `January, 01 2014`.
+- [[yii\i18n\Formatter::asTime()|time]] - the value is formatted as a time e.g. `14:23`.
+- [[yii\i18n\Formatter::asDatetime()|datetime]] - the value is formatted as date and time e.g. `January, 01 2014 14:23`.
+- [[yii\i18n\Formatter::asTimestamp()|timestamp]] - the value is formatted as a [unix timestamp](http://en.wikipedia.org/wiki/Unix_time) e.g. `1412609982`.
+- [[yii\i18n\Formatter::asRelativeTime()|relativeTime]] - the value is formatted as the time interval between a date
+  and now in human readable form e.g. `1 hour ago`.
 
-See http://site.icu-project.org/ for the format.
+The date and time format for the [[yii\i18n\Formatter::asDate()|date]], [[yii\i18n\Formatter::asTime()|time]], and
+[[yii\i18n\Formatter::asDatetime()|datetime]] method can be specified globally by configuring the formatters
+properties [[yii\i18n\Formatter::$dateFormat|$dateFormat]], [[yii\i18n\Formatter::$timeFormat|$timeFormat]], and
+[[yii\i18n\Formatter::$datetimeFormat()|$datetimeFormat]].
 
-- [[\yii\i18n\Formatter::asDate()|date]] - the value is formatted as date.
-- [[\yii\i18n\Formatter::asTime()|time]] - the value is formatted as time.
-- [[\yii\i18n\Formatter::asDatetime()|datetime]] - the value is formatted as datetime.
-- [[\yii\i18n\Formatter::asTimestamp()|timestamp]] - the value is formatted as a unix timestamp.
-- [[\yii\i18n\Formatter::asRelativeTime()|relativeTime]] - the value is formatted as the time interval between a date
-  and now in human readable form.
+By default the formatter uses a shortcut format that is interpreted differently according to the currently active locale
+so that dates and times are formatted in a way that is common for the users country and language.
+There are four different shortcut formats available:
 
+- `short` in `en_GB` locale will print for example `06/10/2014` for date and `15:58` for time, while
+- `medium` will print `6 Oct 2014` and `15:58:42`,
+- `long` will print `6 October 2014` and `15:58:42 GMT`,
+- and `full` will print `Monday, 6 October 2014` and `15:58:42 GMT`.
 
-The input value for date and time formatting is assumed to be in UTC unless a timezone is explicitly given.
+Additionally you can specify custom formats using the syntax defined by the
+[ICU Project](http://site.icu-project.org/) which is described in the ICU manual under the following URL:
+<http://userguide.icu-project.org/formatparse/datetime>. Alternatively you can use the syntax that can be recognized by the
+PHP [date()](http://php.net/manual/de/function.date.php)-function using a string that is prefixed with `php:`.
 
-Formatting Numbers
-------------------
+```php
+// ICU format
+echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
+// PHP date()-format
+echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06
+```
 
-> Note: This section is under development.
+### Time zones <a name="time-zones"></a>
 
-TDB
+When formatting date and time values, Yii will convert them to the [[yii\i18n\Formatter::timeZone|configured time zone]].
+Therefor the input value is assumed to be in UTC unless a time zone is explicitly given. For this reason
+it is recommended to store all date and time values in UTC preferably as a UNIX timestamp, which is always UTC by definition.
+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:
 
-See http://site.icu-project.org/ for the format.
+```php
+// assuming Yii::$app->timeZone = 'Europe/Berlin';
+echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
+echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
+echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
+```
 
-- [[\yii\i18n\Formatter::asInteger()|integer]] - the value is formatted as an integer.
-- [[\yii\i18n\Formatter::asDecimal()|decimal]] - the value is formatted as a number with decimal and thousand separators.
-- [[\yii\i18n\Formatter::asPercent()|percent]] - the value is formatted as a percent number.
-- [[\yii\i18n\Formatter::asScientific()|scientific]] - the value is formatted as a number in scientific format.
-- [[\yii\i18n\Formatter::asCurrency()|currency]] - the value is formatted as a currency value.
-- [[\yii\i18n\Formatter::asSize()|size]] - the value that is a number of bytes is formatted as a human readable size.
-- [[\yii\i18n\Formatter::asShortSize()|shortSize]] - the value that is a number of bytes is formatted as a human readable size.
+Formatting Numbers <a name="numbers"></a>
+------------------
 
+For formatting numeric values the formatter class provides the following methods:
 
-Other formatters
-----------------
+- [[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 separators e.g. `42.123`.
+- [[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::asCurrency()|currency]] - the value is formatted as a currency value e.g. `£420.00`.
+- [[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`.
+
+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.
+
+For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]]
+can be used to configure the interally used [Numberformatter class](http://php.net/manual/en/class.numberformatter.php)
 
-> Note: This section is under development.
+For example to adjust the maximum and minimum value of fraction digits you can configure this property like the following:
 
-TDB
+```php
+[
+    NumberFormatter::MIN_FRACTION_DIGITS => 0,
+    NumberFormatter::MAX_FRACTION_DIGITS => 2,
+]
+```
 
+Other formatters  <a name="other"></a>
+----------------
 
-Here's the bundled formatters list:
+Additional to date, time and number formatting, Yii provides a set of other useful formatters for different purposes:
 
-- [[\yii\i18n\Formatter::asRaw()|raw]] - the value is outputted as is.
-- [[\yii\i18n\Formatter::asText()|text]] - the value is HTML-encoded. This format is used by default.
-- [[\yii\i18n\Formatter::asNtext()|ntext]] - the value is formatted as an HTML-encoded plain text with newlines converted
+- [[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]].
+- [[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).
+- [[yii\i18n\Formatter::asNtext()|ntext]] - the value is formatted as an HTML-encoded plain text with newlines converted
   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.
-- [[\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']]]`.
-- [[\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::asUrl()|url]] - the value is formatted as a hyperlink.
-- [[\yii\i18n\Formatter::asBoolean()|boolean]] - the value is formatted as a boolean. You can set what's rendered for
-  true and false values by calling `Yii::$app->formatter->booleanFormat = ['No', 'Yes'];` before outputting GridView.
+- [[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::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
+  as `Yes` and `false` as `No`, translated to the application language. You adjust this by configuring
+  the [[yii\i18n\Formatter::booleanFormat]]-property.
+
+`null`-values <a name="null-values"></a>
+-------------
+
+For values that are `null` in PHP, the formatter class will print a placeholder instead of and empty string which
+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.
+If you want no special handling for `null` values, you can set [[yii\i18n\Formatter::nullDisplay|nullDisplay]] to `null`.

docs/guide/runtime-handling-errors.md

@@ -16,7 +16,7 @@ The [[yii\web\ErrorHandler|error handler]] is enabled by default. You may disabl
 
 ## Using Error Handler <a name="using-error-handler"></a>
 
-The [[yii\web\ErrorHandler|error handler]] is registered as an application component named `errorHandler`.
+The [[yii\web\ErrorHandler|error handler]] is registered as an [application component](structure-application-components.md) named `errorHandler`.
 You may configure it in the application configuration like the following:
 
 ```php

docs/guide/runtime-logging.md

@@ -63,7 +63,7 @@ severity levels and categories and then exports them to some medium. For example
 exports the filtered log messages to a database table, while a [[yii\log\EmailTarget|email target]] exports
 the log messages to specified email addresses.
 
-You can register multiple log targets in an application by configuring them through the `log` application component 
+You can register multiple log targets in an application by configuring them through the `log` [application component](structure-application-components.md)
 in the application configuration, like the following:
 
 ```php

docs/guide/security-authorization.md

@@ -154,7 +154,7 @@ the [Wiki article](http://en.wikipedia.org/wiki/Role-based_access_control) for d
 with other more traditional access control schemes.
 
 Yii implements a General Hierarchical RBAC, following the [NIST RBAC model](http://csrc.nist.gov/rbac/sandhu-ferraiolo-kuhn-00.pdf).
-It provides the RBAC functionality through the [[yii\rbac\ManagerInterface|authManager]] application component.
+It provides the RBAC functionality through the [[yii\rbac\ManagerInterface|authManager]] [application component](structure-application-components.md).
 
 Using RBAC involves two parts of work. The first part is to build up the RBAC authorization data, and the second
 part is to use the authorization data to perform access check in places where it is needed.

docs/guide/structure-applications.md

@@ -195,7 +195,7 @@ The rest of the array elements (key-value pairs) specify the parameters to be bo
 #### [[yii\base\Application::components|components]] <a name="components"></a>
 
 This is the single most important property. It allows you to register a list of named components
-called [application components](#structure-application-components.md) that you can use in other places. For example,
+called [application components](structure-application-components.md) that you can use in other places. For example,
 
 ```php
 [

docs/guide/structure-views.md

@@ -4,7 +4,7 @@ Views
 Views are part of the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture.
 They are code responsible for presenting data to end users. In a Web application, views are usually created
 in terms of *view templates* which are PHP script files containing mainly HTML code and presentational PHP code.
-They are managed by the [[yii\web\View|view]] application component which provides commonly used methods
+They are managed by the [[yii\web\View|view]] [application component](structure-application-components.md) which provides commonly used methods
 to facilitate view composition and rendering. For simplicity, we often call view templates or view template files
 as views.
 

docs/guide/tutorial-console.md

@@ -63,7 +63,7 @@ Configuration
 -------------
 
 As can be seen in the code above, the console application uses its own configuration file, named `console.php`. In this file
-you should configure various application components and properties for the console application in particular.
+you should configure various [application components](structure-application-components.md) and properties for the console application in particular.
 
 If your web application and the console application share a lot of configuration parameters and values, you may consider moving the common
 parts into a separate file, and including this file in both of the application configurations (web and console). You can see an example of this in the "advanced" application template.

docs/guide/tutorial-i18n.md

@@ -71,7 +71,7 @@ echo \Yii::t('app', 'This is a string to translate!');
 ```
 
 Yii tries to load an appropriate translation according to the current [[yii\base\Application::$language|application language]]
-from one of the message sources defined in the `i18n` [application component](concept-components.md).
+from one of the message sources defined in the `i18n` [application component](structure-application-components.md).
 A message source is a set of files or a database that provides translation messages.
 The following configuration example defines a messages source that takes the messages from PHP files:
 
@@ -408,7 +408,7 @@ Instead of using `fileMap` you can simply use convention of category mapping to
 
 Yii comes with default translation messages for validation errors and some other strings. These messages are all
 in the category `yii`. Sometimes you want to correct default framework message translation for your application.
-In order to do so configure the `i18n` [application component](concept-components.md) like the following:
+In order to do so configure the `i18n` [application component](structure-application-components.md) like the following:
 
 ```php
 'i18n' => [

docs/guide/tutorial-performance-tuning.md

@@ -78,7 +78,7 @@ return [
 ];
 ```
 
-Note that `cache` application component should be configured.
+Note that the `cache` [application component](structure-application-components.md) should be configured.
 
 ### Combining and Minimizing Assets
 

docs/guide/tutorial-yii-integration.md

@@ -106,7 +106,7 @@ which is not needed in this case and already handled by the existing application
 
 Like in a Yii application, you should configure the application instance based on the environment running
 the third-party system. For example, to use the [Active Record](db-active-record.md) feature, you need to configure
-the `db` application component with the DB connection setting used by the third-party system.
+the `db` [application component](structure-application-components.md) with the DB connection setting used by the third-party system.
 
 Now you can use most features provided by Yii. For example, you can create Active Record classes and use them
 to work with databases.

docs/guide/widget-bootstrap.md

@@ -57,7 +57,7 @@ Using the .less files of Bootstrap directly
 If you want to include the [Bootstrap css directly in your less files](http://getbootstrap.com/getting-started/#customizing)
 you may need to disable the original bootstrap css files to be loaded.
 You can do this by setting the css property of the [[yii\bootstrap\BootstrapAsset|BootstrapAsset]] to be empty.
-For this you need to configure the `assetManager` application component as follows:
+For this you need to configure the `assetManager` [application component](structure-application-components.md) as follows:
 
 ```php
     'assetManager' => [

framework/i18n/Formatter.php

@@ -258,6 +258,7 @@ class Formatter extends Component
     /**
      * Formats the value as is without any formatting.
      * This method simply returns back the parameter without any format.
+     * The only exception is a `null` value which will be formatted using [[nullDisplay]].
      * @param mixed $value the value to be formatted.
      * @return string the formatted result.
      */
@@ -342,14 +343,15 @@ class Formatter extends Component
     /**
      * Formats the value as an image tag.
      * @param mixed $value the value to be formatted.
+     * @param string $altText an optional `alt`-tag to be added to the image.
      * @return string the formatted result.
      */
-    public function asImage($value)
+    public function asImage($value, $altText = '')
     {
         if ($value === null) {
             return $this->nullDisplay;
         }
-        return Html::img($value);
+        return Html::img($value, ['alt' => $altText]);
     }
 
     /**