start-gii.md 5.22 KB
Newer Older
1 2 3
Generating Code with Gii
========================

Larry Ullman committed
4 5
This section will describe how to use [Gii](tool-gii.md) to automatically generate  code
that implements some common Web site features. Using Gii to auto-generate code is simply a matter of entering the right information per to the instructions shown on the Gii Web pages.
Qiang Xue committed
6

Larry Ullman committed
7
Through this tutorial, you will learn how to:
Qiang Xue committed
8

Larry Ullman committed
9 10 11 12
* Enable Gii in your application
* Use Gii to generate an Active Record class
* Use Gii to generate the code implementing the CRUD operations for a DB table
* Customize the code generated by Gii
Qiang Xue committed
13 14


Qiang Xue committed
15
Starting Gii <a name="starting-gii"></a>
Qiang Xue committed
16 17
------------

Larry Ullman committed
18 19
[Gii](tool-gii.md) is provided in Yii as a [module](structure-modules.md). You can enable Gii
by configuring it in the [[yii\base\Application::modules|modules]] property of the application. Depending upon how you created your application, you may find the following code is already provided in the `config/web.php` configuration file:
Qiang Xue committed
20 21 22 23 24 25 26 27 28 29 30

```php
$config = [ ... ];

if (YII_ENV_DEV) {
    $config['bootstrap'][] = 'gii';
    $config['modules']['gii'] = 'yii\gii\Module';
}
```

The above configuration states that when in [development environment](concept-configurations.md#environment-constants),
Larry Ullman committed
31
the application should include a module named `gii`, which is of class [[yii\gii\Module]].
Qiang Xue committed
32 33

If you check the [entry script](structure-entry-scripts.md) `web/index.php` of your application, you will
Larry Ullman committed
34
find the following line, which essentially makes `YII_ENV_DEV` to be true.
Qiang Xue committed
35 36 37 38 39

```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```

Larry Ullman committed
40
Thanks to that line, your application is in development mode, and will have already enabled Gii, per the above configuration. You can now access Gii via the following URL:
Qiang Xue committed
41 42 43 44 45

```
http://hostname/index.php?r=gii
```

46 47
![Gii](images/start-gii.png)

Qiang Xue committed
48

Qiang Xue committed
49
Generating an Active Record Class <a name="generating-ar"></a>
Qiang Xue committed
50 51
---------------------------------

Larry Ullman committed
52
To use Gii to generate an Active Record class, select the "Model Generator" (by clicking the link on the Gii index page). Then fill out the form as follows:
Qiang Xue committed
53 54 55 56

* Table Name: `country`
* Model Class: `Country`

57 58
![Model Generator](images/start-gii-model.png)

Larry Ullman committed
59
Next, click on the "Preview" button. You will see `models/Country.php` is listed in the resulting class file to be created. You may click on the name of the class file to preview its content.
Qiang Xue committed
60

Larry Ullman committed
61 62 63
When using Gii, if you have already created the same file and would be overwriting it, click
the `diff` button next to the file name to see the differences between the code to be generated
and the existing version.
Qiang Xue committed
64

65 66
![Model Generator Preview](images/start-gii-model-preview.png)

Larry Ullman committed
67 68 69 70
When overwriting an existing file, check the box next to "overwrite" and then click  the "Generate" button. If creating a new file, you can just click "Generate". 

Next, you will see
a confirmation page indicating the code has been successfully generated. If you had an existing file, you'll also see a message indicating that it was overwritten with the newly generated code.
Qiang Xue committed
71 72


Qiang Xue committed
73
Generating CRUD Code <a name="generating-crud"></a>
Qiang Xue committed
74 75
--------------------

Larry Ullman committed
76
CRUD stands for Create, Read, Update, and Delete, representing the four common tasks taken with data on most Web sites. To create CRUD functionality using Gii, select the "CRUD Generator" (by clicking the link on the Gii index page). For the "country" example, fill out the resulting form as follows:
Qiang Xue committed
77 78 79 80 81

* Model Class: `app\models\Country`
* Search Model Class: `app\models\CountrySearch`
* Controller Class: `app\controllers\CountryController`

82
![CRUD Generator](images/start-gii-crud.png)
Qiang Xue committed
83

Larry Ullman committed
84 85 86
Next, click on the "Preview" button. You will see a list of files to be generated, as shown below.

[[NEED THE IMAGE HERE]]
Qiang Xue committed
87

Larry Ullman committed
88 89
If you previously created the `controllers/CountryController.php` and
`views/country/index.php` files (in the databases section of the guide), check the "overwrite" box to replace them. (The previous versions did not have full CRUD support.)
Qiang Xue committed
90 91


Qiang Xue committed
92 93
Trying it Out <a name="trying-it-out"></a>
-------------
Qiang Xue committed
94 95 96 97 98 99 100

To see how it works, use your browser to access the following URL:

```
http://hostname/index.php?r=country/index
```

Larry Ullman committed
101
You will see a data grid showing the countries from the database table. You may sort the grid,
Qiang Xue committed
102 103
or filter it by entering filter conditions in the column headers.

Larry Ullman committed
104 105
For each country displayed in the grid, you may choose to view its details, update it, or delete it.
You may also click on the "Create Country" button on top of the grid to be provided with a form for creating a new country.
Qiang Xue committed
106

107 108 109 110
![Data Grid of Countries](images/start-gii-country-grid.png)

![Updating a Country](images/start-gii-country-update.png)

Larry Ullman committed
111 112
The following is the list of the files generated by Gii, in case you want to investigate how these features are implemented,
or to customize them:
Qiang Xue committed
113 114 115 116 117 118 119 120 121 122

* Controller: `controllers/CountryController.php`
* Models: `models/Country.php` and `models/CountrySearch.php`
* Views: `views/country/*.php`

> Info: Gii is designed to be a highly customizable and extensible code generation tool. Using it wisely
  can greatly accelerate your application development speed. For more details, please refer to
  the [Gii](tool-gii.md) section.


Qiang Xue committed
123
Summary <a name="summary"></a>
Qiang Xue committed
124 125
-------

Larry Ullman committed
126 127
In this section, you have learned how to use Gii to generate the code that implements complete
CRUD functionality for content stored in a database table.