From 713f73e6ed8135f70b403749726805af63c87b83 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Mon, 9 Jun 2014 18:09:33 -0400 Subject: [PATCH] guide WIP [skip ci] --- docs/guide/structure-controllers.md | 13 ++-- docs/guide/structure-models.md | 16 ++--- docs/guide/structure-views.md | 100 ++++++++++++++++++++++++++-- 3 files changed, 109 insertions(+), 20 deletions(-) diff --git a/docs/guide/structure-controllers.md b/docs/guide/structure-controllers.md index 01f5798bd5..c4610465aa 100644 --- a/docs/guide/structure-controllers.md +++ b/docs/guide/structure-controllers.md @@ -2,7 +2,7 @@ Controllers =========== Controllers are part of the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture. -They contain the actual logic about processing requests and generating responses. In particular, after +They are objects responsible for processing requests and generating responses. In particular, after taking over the control from [applications](structure-applications.md), controllers will analyze incoming request data, pass them to [models](structure-models.md), inject model results into [views](structure-views.md), and finally generate outgoing responses. @@ -25,14 +25,13 @@ class PostController extends Controller public function actionView($id) { $model = Post::findOne($id); - - if ($model !== null) { - return $this->render('view', [ - 'model' => $model, - ]); - } else { + if ($model === null) { throw new NotFoundHttpException; } + + return $this->render('view', [ + 'model' => $model, + ]); } public function actionCreate() diff --git a/docs/guide/structure-models.md b/docs/guide/structure-models.md index dd029b060a..db6636f93b 100644 --- a/docs/guide/structure-models.md +++ b/docs/guide/structure-models.md @@ -1,8 +1,8 @@ Models ====== -Models are objects representing business data, rules and logic. They are part of -the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture. +Models are part of the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture. +They are objects representing business data, rules and logic. You can create model classes by extending [[yii\base\Model]] or its child classes. The base class [[yii\base\Model]] supports many useful features: @@ -11,7 +11,7 @@ You can create model classes by extending [[yii\base\Model]] or its child classe or array elements; * [Attribute labels](#attribute-labels): specify the display labels for attributes; * [Massive assignment](#massive-assignment): supports populating multiple attributes in a single step; -* [Validation](#validation): ensures input data based on the declared validation rules; +* [Validation rules](#validation-rules): ensures input data based on the declared validation rules; * [Data Exporting](#data-exporting): allows model data to be exported in terms of arrays with customizable formats. The `Model` class is also the base class for more advanced models, such as [Active Record](db-active-record.md). @@ -82,7 +82,7 @@ override the magic methods such as `__get()`, `__set()` so that the attributes c normal object properties. -## Attribute Labels +### Attribute Labels When displaying values or getting input for attributes, you often need to display some labels associated with attributes. For example, given an attribute named `firstName`, you may want to display a label `First Name` @@ -171,7 +171,7 @@ $model->scenario = 'login'; $model = new User(['scenario' => 'login']); ``` -By default, the scenarios supported by a model are determined by the [validation rules](#validation) declared +By default, the scenarios supported by a model are determined by the [validation rules](#validation-rules) declared in the model. However, you can customize this behavior by overriding the [[yii\base\Model::scenarios()]] method, like the following: @@ -197,7 +197,7 @@ class User extends ActiveRecord The `scenarios()` method returns an array whose keys are the scenario names and values the corresponding *active attributes*. An active attribute can be [massively assigned](#massive-assignment) and is subject -to [validation](#validation). In the above example, the `username` and `password` attributes are active +to [validation](#validation-rules). In the above example, the `username` and `password` attributes are active in the `login` scenario; while in the `register` scenario, `email` is also active besides `username` and `password`. The default implementation of `scenarios()` will return all scenarios found in the validation rule declaration @@ -221,12 +221,12 @@ class User extends ActiveRecord } ``` -The scenario feature is primarily used by [validation](#validation) and [massive attribute assignment](#massive-assignment). +The scenario feature is primarily used by [validation](#validation-rules) and [massive attribute assignment](#massive-assignment). You can, however, use it for other purposes. For example, you may declare [attribute labels](#attribute-labels) differently based on the current scenario. -## Validation +## Validation Rules When the data for a model is received from end users, it should be validated to make sure it satisfies certain rules (called *validation rules*, also known as *business rules*). For example, given a `ContactForm` model, diff --git a/docs/guide/structure-views.md b/docs/guide/structure-views.md index 93c250a7ec..488f27051f 100644 --- a/docs/guide/structure-views.md +++ b/docs/guide/structure-views.md @@ -1,10 +1,100 @@ -View -==== +Views +===== -> Note: This section is under development. +Views are part of the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture. +They are responsible for presenting data to end users. In a Yii application, the view layer is composed by +[view templates](#view-templates) and [view components](#view-components). The former contains presentational +code (e.g. HTML), while the latter provides common view-related features and is responsible for turning view +templates into response content. We often use "views" to refer to view templates. -The view component is an important part of MVC. The view acts as the interface to the application, making it responsible -for presenting data to end users, displaying forms, and so forth. + +## View Templates + +You turn a view template into response content by pushing [model](structure-models.md) data into +the template and rendering it. For example, in the `post/view` action below, the `view` template +is rendered with the `$model` data. The rendering result is a string which is returned by the action as the response content. + +```php +namespace app\controllers; + +use Yii; +use app\models\Post; +use yii\web\Controller; +use yii\web\NotFoundHttpException; + +class PostController extends Controller +{ + public function actionView($id) + { + $model = Post::findOne($id); + if ($model === null) { + throw new NotFoundHttpException; + } + + return $this->render('view', [ + 'model' => $model, + ]); + } +} +``` + +### Rendering Views in Controllers + +### Rendering Views in Widgets + +### Rendering Views in Views + +### View Names + +By default, a view template is simply a PHP script file (called *view file*). Like [models](structure-models.md) +and [controllers](structure-controllers.md), view files are usually organized under the so-called *view paths*. +For views rendered by controllers that directly belong to an application, they are located under the `@app/views` path. + +* applications: +* modules: +* controllers: +* widgets and other components: + +When rendering a view template, you can specify it using a view name, a view file path, +or an [alias](concept-aliases.md) to the view file path. + +If a view name is used, it will be resolved into a view file path according to the current +[[yii\base\View::context|view context]] using one of the following rules: + +* If the view name starts with double slashes `//`, the corresponding view file path is considered to be + `@app/views/ViewName`. For example, `//site/about` will be resolved into `@app/views/site/about`. +* If the view name starts with a single slash `/`, the view file path is formed by prefixing the view name + with the [[yii\base\Module::viewPath|view path]] of the currently active [module](structure-modules.md). + If there is no active module, `@app/views/ViewName` will be used. For example, `/user/create` will be resolved into + `@app/modules/user/views/user/create`, if the currently active module is `user`. If there is no active module, + the view file path would be `@app/views/user/create`. +* If the view is rendered with a [[yii\base\View::context|context]], the view file path will be prefixed with + the [[yii\base\ViewContextInterface::getViewPath()|view path]]. For example, `site/about` will be resolved + into `@app/views/site/about` if the context is the `SiteController`. +* If a view was previously rendered, the directory containing that view file will be prefixed to + the new view name. + + +## Layouts + +### Nested Layouts + + +### Accessing Data + +## View Components + +## Creating Views + +### Setting page title +### Adding meta tags +### Registering link tags +### Registering CSS +### Registering scripts +### Static Pages +### Assets + +## Alternative Template Engines Basics