Skip to content

Y
yii2
Commit a58eb8e2 by Qiang Xue
Options

guide WIP [skip ci]

parent d68e7ead
Showing with 173 additions and 9 deletions
docs/guide/README.md
......@@ -37,9 +37,9 @@ Application Structure
* [Controllers](structure-controllers.md)
* [Models](structure-models.md)
* [Views](structure-views.md)
* **TBD** [Filters](structure-filters.md)
* **TBD** [Widgets](structure-widgets.md)
* **TBD** [Modules](structure-modules.md)
* [Modules](structure-modules.md)
* [Filters](structure-filters.md)
* [Widgets](structure-widgets.md)
* [Asset Bundles](structure-assets.md)
* **TBD** [Extensions](structure-extensions.md)
......
docs/guide/start-forms.md
......@@ -58,15 +58,18 @@ of rules for validating the data. The validation rules declared above state that
If you have an `EntryForm` object populated with the data entered by a user, you may call
its [[yii\base\Model::validate()|validate()]] to trigger the data validation routines. A data validation
failure will set the [[yii\base\Model::hasErrors|hasErrors]] property to true, and you may learn what validation errors occurred through [[yii\base\Model::getErrors|errors]].
failure will set the [[yii\base\Model::hasErrors|hasErrors]] property to true, and you may learn what validation
errors occurred through [[yii\base\Model::getErrors|errors]].
```php
<?php
$model = new EntryForm();
$model->name = 'Qiang';
$model->email = 'bad';
if ($model->validate()) { // Good!
} else { // Failure!
if ($model->validate()) {
// Good!
} else {
// Failure!
// Use $model->getErrors()
}
```
......@@ -75,7 +78,8 @@ if ($model->validate()) { // Good!
Creating an Action <a name="creating-action"></a>
------------------
Next, you'll need to create an `entry` action in the `site` controller that will use the new model. The process of creating and using actions was explained in the [Saying Hello](start-hello.md) section.
Next, you'll need to create an `entry` action in the `site` controller that will use the new model. The process
of creating and using actions was explained in the [Saying Hello](start-hello.md) section.
```php
<?php
......@@ -110,7 +114,8 @@ class SiteController extends Controller
The action first creates an `EntryForm` object. It then tries to populate the model
with the data from `$_POST`, provided in Yii by [[yii\web\Request::post()]].
If the model is successfully populated (i.e., if the user has submitted the HTML form), the action will call [[yii\base\Model::validate()|validate()]] to make sure the values entered are valid.
If the model is successfully populated (i.e., if the user has submitted the HTML form), the action will call
[[yii\base\Model::validate()|validate()]] to make sure the values entered are valid.
If everything is fine, the action will render a view named `entry-confirm` to confirm the data entered
with the user that the data entered. If a problem occurred, the `entry` view will
......@@ -203,7 +208,8 @@ turn them into executable JavaScript code, and use the JavaScript to perform dat
JavaScript on your browser, the validation will still be performed on the server side, as shown in
the `actionEntry()` method. This ensures data validity in all circumstances.
> Warning: Client-side validation is a conveniences that provides for a better user experience. Server-side validation is always required, whether or not client-side validation is in place.
> Warning: Client-side validation is a convenience that provides for a better user experience. Server-side validation
is always required, whether or not client-side validation is in place.
The labels for input fields are generated by the `field()` method, using the property names from the model.
For example, the label `Name` will be generated for the `name` property.
......
docs/guide/structure-modules.md 0 → 100644
Modules
=======
> Note: This section is under development.
Modules are self-contained software units that consist of [models](structure-models.md), [views](structure-views.md),
[controllers](structure-controllers.md), and other supporting components. End users can access the controllers
of a module when it is installed in [application](structure-applications.md). Modules differ from
[applications](structure-applications.md) in that the former cannot be deployed alone and must reside within the latter.
## Creating Modules
A module is organized as a directory which is called the [[yii\base\Module::basePath|base path]] of the module.
The content in this directory is like the following:
```
forum/
Module.php the module class file
controllers/ containing controller class files
DefaultController.php the default controller class file
models/ containing model class files
views/ containing controller view and layout files
layouts/ containing layout view files
default/ containing view files for DefaultController
index.php the index view file
```
As you can see, within the module's [[yii\base\Module::basePath|base path]], you can create sub-directories,
such as `controllers`, `models`, `views`, to hold controllers, models, views that belong to the module.
### Module Classes
Each module should have a module class which extends from [[yii\base\Module]] and is located directly under
the module's [[yii\base\Module::basePath|base path]]. When a module is being accessed, a single instance
of the corresponding module class will be created and made accessible by the code within the module.
Like [application instances](structure-applications.md), module instances are mainly used to share data and components
for code within modules.
The following is an example of a module class:
```php
namespace app\modules\forum;
class Module extends \yii\base\Module
{
public function init()
{
parent::init();
$this->params['foo'] = 'bar';
// ... other initialization code ...
}
}
```
If the code in `init()` deals with a lot of module property initialization, you may also save them in terms
of a [configuration](concept-configurations.md) and load it with the following code in `init()`:
```php
public function init()
{
parent::init();
// initialize the module with the configuration loaded from config.php
\Yii::configure($this, require(__DIR__ . '/config.php'));
}
```
where the configuration file `config.php` may contain the following content, similar to that in an
[application configuration](structure-applications.md#application-configurations).
```php
<?php
return [
'components' => [
// list of component configurations
],
'params' => [
// list of parameters
],
];
```
> Note: Make sure that module classes are named in a way such that they are [autoloadable](concept-autoloading.md).
### Controllers in Modules
You may create a module class
Like [application instances](structure-applications.md) are used to
The module class serves as the central place for storing information shared among the module code. For example,
we can use [CWebModule::params] to store module parameters, and use [CWebModule::components] to share
[application components](/doc/guide/basics.application#application-component) at the module level.
### Views in Modules
## Using Modules
To use a module, first place the module directory under `modules` of the [application base directory](/doc/guide/basics.application#application-base-directory). Then declare the module ID in the [modules|CWebApplication::modules] property of the application. For example, in order to use the above `forum` module, we can use the following [application configuration](/doc/guide/basics.application#application-configuration):
~~~
[php]
return array(
......
'modules'=>array('forum',...),
......
);
~~~
A module can also be configured with initial property values. The usage is very similar to configuring [application components](/doc/guide/basics.application#application-component). For example, the `forum` module may have a property named `postPerPage` in its module class which can be configured in the [application configuration](/doc/guide/basics.application#application-configuration) as follows:
~~~
[php]
return array(
......
'modules'=>array(
'forum'=>array(
'postPerPage'=>20,
),
),
......
);
~~~
The module instance may be accessed via the [module|CController::module] property of the currently active controller. Through the module instance, we can then access information that are shared at the module level. For example, in order to access the above `postPerPage` information, we can use the following expression:
~~~
[php]
$postPerPage=Yii::app()->controller->module->postPerPage;
// or the following if $this refers to the controller instance
// $postPerPage=$this->module->postPerPage;
~~~
A controller action in a module can be accessed using the [route](/doc/guide/basics.controller#route) `moduleID/controllerID/actionID`. For example, assuming the above `forum` module has a controller named `PostController`, we can use the [route](/doc/guide/basics.controller#route) `forum/post/create` to refer to the `create` action in this controller. The corresponding URL for this route would be `http://www.example.com/index.php?r=forum/post/create`.
> Tip: If a controller is in a sub-directory of `controllers`, we can still use the above [route](/doc/guide/basics.controller#route) format. For example, assuming `PostController` is under `forum/controllers/admin`, we can refer to the `create` action using `forum/admin/post/create`.
## Nested Modules
Modules can be nested in unlimited levels. That is, a module can contain another module which can contain yet another module. We call the former *parent module* while the latter *child module*. Child modules must be declared in the [modules|CWebModule::modules] property of their parent module, like we declare modules in the application configuration shown as above.
To access a controller action in a child module, we should use the route `parentModuleID/childModuleID/controllerID/actionID`.
## Best Practices
Users can access the controllers in a module like they do with normal application controllers.
Modules are useful in several scenarios. For a large-scale application, we may divide it into several modules,
each being developed and maintained separately. Some commonly used features, such as user management,
comment management, may be developed in terms of modules so that they can be reused easily in future projects.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment