Commit cc9c57e1 by Qiang Xue

guide WIP [skip ci]

parent e2a6acaf
......@@ -41,7 +41,7 @@ Application Structure
* [Filters](structure-filters.md)
* [Widgets](structure-widgets.md)
* [Asset Bundles](structure-assets.md)
* **TBD** [Extensions](structure-extensions.md)
* [Extensions](structure-extensions.md)
Handling Requests
......
......@@ -47,7 +47,8 @@ class EntryForm extends Model
The class extends from [[yii\base\Model]], a base class provided by Yii, commonly used to
represent form data.
> Info: [[yii\base\Model]] is used as a parent for model classes *not* associated with database tables. [[yii\db\ActiveRecord]] is normally the parent for model classes that do correspond to database tables.
> Info: [[yii\base\Model]] is used as a parent for model classes *not* associated with database tables.
[[yii\db\ActiveRecord]] is normally the parent for model classes that do correspond to database tables.
The `EntryForm` class contains two public members, `name` and `email`, which are used to store
the data entered by the user. It also contains a method named `rules()`, which returns a set
......@@ -117,18 +118,19 @@ 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 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 no data was submitted or the data contained errors, the `entry` view will
be rendered, wherein the HTML form will be shown, along with any validation error messages.
> Info: The expression `Yii::$app` represents the [application](structure-applications.md) instance,
which is a globally accessible singleton. It is also a [service locator](concept-service-locator.md) that
provides components such as `request`, `response`, `db`, etc. to support specific functionality.
In the above code, the `request` component of the application instance is used to access the `$_POST` data.
> Note: In this very simple example we just render the confirmation page, however when you process POST data you
should better use [[yii\web\Controller::refresh()|refresh()]] or [[yii\web\Controller::redirect()|redirect()]]
to avoid [resubmitting](http://en.wikipedia.org/wiki/Post/Redirect/Get) forms.
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 no data is submitted or the data contains errors, the `entry` view will
be rendered, wherein the HTML form will be shown, along with any validation error messages.
> Note: In this very simple example we just render the confirmation page upon valid data submission. In practice,
you should consider using [[yii\web\Controller::refresh()|refresh()]] or [[yii\web\Controller::redirect()|redirect()]]
to avoid [form resubmission problems](http://en.wikipedia.org/wiki/Post/Redirect/Get).
Creating Views <a name="creating-views"></a>
--------------
......
Extensions
==========
> Note: This section is under development.
Extensions are redistributable software packages that extend Yii by providing extra features. For example,
the [yii2-debug](tool-debugger.md) extension adds a handy debug toolbar to every page in your application
to help you more easily grasp how the pages are generated. You can install and use extensions in your
applications to accelerate your development process. You can also package your code in terms of extensions
to share with other people your great work.
## Getting Extensions
The easiest way of getting extensions is using [Composer](https://getcomposer.org/). The name "extension"
is also known as "package" in Composer's terminology. To do so, you will need to
1. install [Composer](https://getcomposer.org/), which you probably have already done when
[installing Yii](start-installation.md).
2. [specify which repositories](https://getcomposer.org/doc/05-repositories.md#repository) you would like
to get extensions from. In most cases you can skip this if you only want to install open source extensions
hosted on [Packagist](https://packagist.org/) - the default and biggest Composer repository.
3. modify the `composer.json` file of your application and specify which extensions you want to use.
4. run `php composer.phar install` to install the specified extensions.
You usually only need to do Step 1 and 2 once. You may need to do Step 3 and 4 multiple times depending on your
evolving requirements for extensions.
By default, extensions installed by Composer are stored under the `BasePath/vendor` directory, where `BasePath`
refers to the application's [base path](structure-applications.md#basePath).
For example, to get the `yii2-imagine` extension maintained officially by Yii, modify your `composer.json` like the following:
```json
{
// ...
"require": {
// ... other dependencies
"yiisoft/yii2-imagine": "*"
}
}
```
The installed extension will be located in the `vendor/yiisoft/yii2-imagine` directory.
> Info: All extensions officially maintained by Yii are named as `yiisoft/yii2-xyz`, where `xyz` varies for different
extensions.
## Using Extensions
In order for your applications to use extensions, you will need to install Composer's class autoloader. This is
necessary such that PHP classes in extensions can be properly autoloaded when you reference them in the application code.
To do so, use the following lines in the [entry script](concept-entry-scripts.md) of your application:
```php
// install Composer's class autoloader
require(__DIR__ . '/../vendor/autoload.php');
// include Yii class file
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
```
> Info: If you are using the [basic application template](start-installation.md) or
[advanced application template](tutorial-advanced-app.md), you do not need to do anything because the application templates
already contain the above code.
Now you can enjoy using the installed extensions. For example, to use the `yii2-imagine` extension shown in the last
subsection, you can write code like the following in your application, where `Image` is the class provided by
the extension:
```php
use Yii;
use yii\imagine\Image;
// generate a thumbnail image
Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
```
## Creating Extensions
## Core Extensions
......@@ -13,11 +13,9 @@ namespace yii\imagine;
* Example of use:
*
* ~~~php
* // thumb - saved on runtime path
* $imagePath = Yii::$app->getBasePath() . '/web/img/test-image.jpg';
* $runtimePath = Yii::$app->getRuntimePath();
* Image::thumbnail('@app/web/img/test-image.jpg', 120, 120)
* ->save('thumb-test-image.jpg', ['quality' => 50]);
* // generate a thumbnail image
* Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
* ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
* ~~~
*
* @author Antonio Ramirez <amigo.cobos@gmail.com>
......
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