Merge branch 'master' of github.com:yiisoft/yii2

docs/guide/debugger.md

@@ -1,8 +1,14 @@
 Debug toolbar and debugger
 ==========================
 
-Overview
+Yii2 includes a handy toolbar to aid faster development and debugging as well as debugger. Toolbar displays information
---------
+about currently opened page while using debugger you can analyze data collected before.
+
+Installing and configuring
+--------------------------
+
+How to use it
+-------------
 
 Creating your own panels
 ------------------------

docs/guide/error.md

@@ -1,3 +1,7 @@
 Error Handling
 ==============
 
+Error handling in Yii is different from plain PHP. First of all, all non-fatal errors are converted to exceptions so
+you can use `try`-`catch` to work with these. Second, even fatal errors are rendered in a nice way. In debug mode that
+means you have a trace and a piece of code where it happened so it takes less time to analyze and fix it.
+

docs/guide/form.md

@@ -0,0 +1,3 @@
+Working with forms
+==================
+

docs/guide/index.md

@@ -67,7 +67,7 @@ More
 ====
 
 - [Bootstrap widgets](bootstrap-widgets.md)
-- [Form](form.md)
+- [Working with forms](form.md)
 - [Model validation reference](validation.md)
 - [Caching](caching.md)
 - [Internationalization](i18n.md)

docs/guide/security.md

@@ -78,4 +78,10 @@ Securing Cookies
 ----------------
 
 - validation
-- httpOnly
+- httpOnly
+
+See also
+--------
+
+- [Views security](view.md#security)
+

docs/guide/upgrade-from-v1.md

@@ -149,11 +149,12 @@ $content = Yii::$app->view->renderFile($viewFile, $params);
 Also, there is no more `CClientScript` in Yii 2.0. The `View` class has taken over its role
 with significant improvements. For more details, please see the "assets" subsection.
 
-While Yii 2.0 continues to use PHP as its main template language, it comes with built-in
+While Yii 2.0 continues to use PHP as its main template language, it comes with two official extensions
-support for two popular template engines: Smarty and Twig. The Prado template engine is
+adding support for two popular template engines: Smarty and Twig. The Prado template engine is
 no longer supported. To use these template engines, you just need to use `tpl` as the file
 extension for your Smarty views, or `twig` for Twig views. You may also configure the
-`View::renderers` property to use other template engines.
+`View::renderers` property to use other template engines. See [Using template engines](template.md) section
+of the guide for more details.
 
 
 Models
@@ -209,6 +210,8 @@ Because of the above change, Yii 2.0 no longer has "safe" and "unsafe" validator
 If your model only has one scenario (very common), you do not have to overwrite `scenarios()`,
 and everything will still work like the 1.1 way.
 
+To learn more about Yii 2.0 models refer to [Models](model.md) section of the guide.
+
 
 Controllers
 -----------
@@ -216,6 +219,7 @@ Controllers
 The `render()` and `renderPartial()` methods now return the rendering results instead of directly
 sending them out. You have to `echo` them explicitly, e.g., `echo $this->render(...);`.
 
+To learn more about Yii 2.0 controllers refer to [Controller](controller.md) section of the guide.
 
 Widgets
 -------

docs/guide/view.md

@@ -37,6 +37,30 @@ Intead of just scalar values you can pass anything else such as arrays or object
 Widgets
 -------
 
+Widgets are a self-contained building blocks for your views. A widget may contain advanced logic, typically takes some
+configuration and data and returns HTML. There is a good number of widgets bundled with Yii such as [active form](form.md),
+breadcrumbs, menu or [wrappers around bootstrap component framework](boostrap-widgets.md). Additionally there are
+extensions providing additional widgets such as official one for jQueryUI components.
+
+In order to use widget you need to do the following:
+
+```php
+// Note that you have to "echo" the result to display it
+echo \yii\widgets\Menu::widget(array('items' => $items));
+
+// Passing an array to initialize the object properties
+$form = \yii\widgets\ActiveForm::begin(array(
+	'options' => array('class' => 'form-horizontal'),
+	'fieldConfig' => array('inputOptions' => array('class' => 'input-xlarge')),
+));
+... form inputs here ...
+\yii\widgets\ActiveForm::end();
+```
+
+In the code above `widget` method is used for a widget that just outputs content while `begin` and `end` are used for a
+widget that wraps content between method calls with its own output. In case of the form this output is the `<form>` tag
+with some properties set.
+
 Security
 --------
 
@@ -87,11 +111,11 @@ Alternative template languages
 There are offlicial extensions for [Smarty](http://www.smarty.net/) and [Twig](http://twig.sensiolabs.org/). In order
 to learn more refer to [Using template engines](template.md) section of the guide.
 
-Using View object
+Using View object in templates
------------------
+------------------------------
 
-An instance of `yii\base\View` is available in view templates as `$this` variable. Using it you can do many useful things
+An instance of `yii\base\View` component is available in view templates as `$this` variable. Using it in templates you
-including setting page title and meta, registering scripts and accessing the context.
+can do many useful things including setting page title and meta, registering scripts and accessing the context.
 
 ### Setting page title
 
@@ -123,8 +147,8 @@ $this->registerMetaTag(array('description' => 'This is my cool website made with
 $this->registerMetaTag(array('description' => 'This website is about funny raccoons.'), 'meta-description');
 ```
 
-If there are multiple calls with the same value of the second argument, the later will override the former and only
+If there are multiple calls with the same value of the second argument (`meta-description` in this case), the latter will
-a single tag will be rendered:
+override the former and only a single tag will be rendered:
 
 ```html
 <meta description="This website is about funny raccoons.">
@@ -155,7 +179,7 @@ Same as with meta tags you can specify additional argument to make sure there's
 ### Registering CSS
 
 You can register CSS using `registerCss` or `registerCssFile`. Former is for outputting code in `<style>` tags directly
-to the page which is not recommended in most cases (but still valid). Later is for registering CSS file. In Yii it's
+to the page which is not recommended in most cases (but still valid). Latter is for registering CSS file. In Yii it's
 much better to [use asset manager](assets.md) to deal with these since it provides extra features so `registerCssFile`
 is manly useful for external CSS files.
 
@@ -183,8 +207,32 @@ page. We're using third argument so one of the views could override it.
 
 ### Registering scripts
 
+With View object you can register scripts. There are two dedicated methods for it: `registerScript` for inline scripts
+and `registerJsFile` for external scripts. Inline scripts are useful for configuration and dynamically generated code.
+The method for adding these can be used as follows:
+
+```php
+$this->registerScript("var options = ".json_encode($options).";", View::POS_END, 'my-options');
+```
+
+First argument is the actual code where we're converting a PHP array of options to JavaScript one. Second argument
+determines where script should be in the page. Possible values are:
+
+- `View::POS_HEAD` for head section.
+- `View::POS_BEGIN` for right after opening `<body>`.
+- `View::POS_END` for right before closing `</body>`.
+- `View::POS_READY` for executing code on document `ready` event. This one registers jQuery automatically.
 
+The last argument is unique script ID that is used to identify code block and replace existing one with the same ID
+instead of adding a new one.
 
+External script can be added like the following:
+
+```php
+$this->registerJsFile('http://example.com/js/main.js');
+```
+
+Same as with external CSS it's preferred to use asset bundles for external scripts.
 
 ### Registering asset bundles
 
@@ -198,6 +246,40 @@ frontend\config\AppAsset::register($this);
 
 ### Layout
 
+A layout is a very convenient way to represent the part of the page that is common for all or at least for most pages
+generated by your application. Typically it includes `<head>` section, footer, main menu and alike elements.
+You can fine a fine example of the layout in a [basic application template](apps-basic.md). Here we'll review the very
+basic one without any widgets or extra markup.
+
+```php
+<?php
+use yii\helpers\Html;
+?>
+<?php $this->beginPage(); ?>
+<!DOCTYPE html>
+<html lang="<?php echo Yii::$app->charset; ?>">
+<head>
+	<meta charset="<?php echo Yii::$app->charset; ?>"/>
+	<title><?php echo Html::encode($this->title); ?></title>
+	<?php $this->head(); ?>
+</head>
+<body>
+<?php $this->beginBody(); ?>
+	<div class="container">
+		<?php echo $content; ?>
+	</div>
+	<footer class="footer">© 2013 me :)</footer>
+<?php $this->endBody(); ?>
+</body>
+</html>
+<?php $this->endPage(); ?>
+```
+
+In the markup above there's some code. First of all, `$content` is a variable that will contain result of views rendered
+with controller's `$this->render()` method.
+
+TBD
+
 ### Partials
 
 Often you need to reuse some HTML markup in many views and often it's too simple to create a full-featured widget for it.
@@ -255,4 +337,22 @@ echo $this->context->getRoute();
 
 ### Caching blocks
 
+To learn about caching of view fragments please refer to [caching](caching.md) section of the guide.
+
+Customizing View component
+--------------------------
 
+Since view is also an application component named `view` you can replace it with your own component that extends
+from `yii\base\View`. It can be done via application configuration file such as `config/web.php`:
+
+```php
+return array(
+	// ...
+	'components' => array(
+		'view' => array(
+			'class' => 'app\components\View',
+		),
+		// ...
+	),
+);
+```

framework/yii/base/View.php

@@ -654,7 +654,7 @@ class View extends Component
 	 * - [[POS_BEGIN]]: at the beginning of the body section
 	 * - [[POS_END]]: at the end of the body section
 	 * - [[POS_READY]]: enclosed within jQuery(document).ready(). This is the default value.
-	 *   Note that by using this position, the method will automatically register the jquery js file.
+	 *   Note that by using this position, the method will automatically register the jQuery js file.
 	 *
 	 * @param string $key the key that identifies the JS code block. If null, it will use
 	 * $js as the key. If two JS code blocks are registered with the same key, the latter