Permalink
Browse files

(Fixes issue 1265)

  • Loading branch information...
1 parent 939fb62 commit 9cdb11f02a2c93c505906ed968e388df5f40b1fd qiang.xue committed Jul 3, 2010
Showing with 76 additions and 38 deletions.
  1. +76 −38 docs/blog/prototype.scaffold.txt
@@ -1,56 +1,80 @@
Scaffolding
===========
-Create, read, update and delete (CRUD) are the four basic operations of data objects in an application. Because the task of implementing the CRUD operations is so common when developing Web applications, Yii provides a tool to automate this process (also known as *scaffolding*). In this section, we will describe how to use the tool to implement CRUD for posts and comments.
+Create, read, update and delete (CRUD) are the four basic operations of data objects in an application. Because the task of implementing the CRUD operations is so common when developing Web applications, Yii provides some code generation tools under the name of *Gii* that can automate this process (also known as *scaffolding*) for us.
-Open a command window and run the following commands:
+> Note: Gii has been available since version 1.1.2. Before that, you would have to use the [yiic shell tool](http://www.yiiframework.com/doc/guide/quickstart.first-app-yiic) to achieve the same task.
-~~~
-% /wwwroot/yii/framework/yiic shell /wwwroot/blog/index.php
-Yii Interactive Tool v1.1
-Please type 'help' for help. Type 'exit' to quit.
->> model *
-......
->> crud Post
-......
->> crud Comment
-......
->> exit
-~~~
+In the following, we will describe how to use this tool to implement CRUD operations for posts and comments in our blog application.
-> Info: Some PHP installations may use a different `php.ini` file for command line (CLI) PHP parser. As a result, when running the above `yiic` commands, you may encounter errors like "YiiBase::include(PDO.php): failed to open stream..." or "...could not find driver". Please double check your CLI PHP configuration by executing the following command:
->
-> ~~~
-> php -i
-> ~~~
->
-> The result of the above command will show which `php.ini` file is being used and which extensions are loaded. If a wrong `php.ini` file is used, you may use the following command to explicitly specify the correct `php.ini` to use:
->
-> ~~~
-> php -c php.ini /wwwroot/yii/framework/yiic.php shell /wwwroot/blog/index.php
-> ~~~
+Installing Gii
+--------------
-The commands above accomplish two tasks. First, the `model` command generates a [model](http://www.yiiframework.com/doc/guide/basics.model) class file for each table in the `blog` database. Second, the `crud` commands generate the code needed by the CRUD operations for the `Post` and `Comment` models.
+We first need to install Gii. Open the file `/wwwroot/blog/protected/config/main.php` and add the following code:
-> Tip: The command `model *` generates a model class for *every* table in the database. Sometimes, we probably don't want to do so (e.g. the database contains some irrelevant tables). In this case, we can create model classes one by one. For example, to create the `User` model, we can use the command `model User`. The `model` command also has some more advanced usages. For more details, execute `help model` command.
+~~~
+[php]
+return array(
+ ......
+ 'import'=>array(
+ 'application.models.*',
+ 'application.components.*',
+ ),
+
+ 'modules'=>array(
+ 'gii'=>array(
+ 'class'=>'system.gii.GiiModule',
+ 'password'=>'pick up a password here',
+ ),
+ ),
+);
+~~~
-We can test the generated code by accessing the following URLs:
+The above code installs the a module named `gii`, which enables us to access the Gii module by visiting the following URL in browser:
~~~
-http://www.example.com/blog/index.php?r=post
-http://www.example.com/blog/index.php?r=comment
+http://www.example.com/blog/index.php?r=gii
~~~
-Notice that the post and comment features implemented by the generated code are completely independent of each other. Also, when creating a new post or comment, we are required to enter information, such as `author_id` and `create_time`, which in real application should be set by the program. Don't worry. We will fix these problems in the next milestones. For now, we should be fairly satisfied as this prototype already contains most features that we need to implement for the blog application.
+We will be prompted to enter a password. Enter the password that we set in `/wwwroot/blog/protected/config/main.php` previously, and we should see a page listing all available code generation tools.
+
+> Note: The above code should be removed when running on the production machine. Code generation tools should only be used on development machines.
+
+
+Creating Models
+---------------
+
+We first need to create a [model](http://www.yiiframework.com/doc/guide/basics.model) class for each of our database tables. The model classes will allow us to access the database in an intuitive object-oriented fashion, as we will see later in this tutorial.
+
+Click on the `Model Generator` link to start using the model generation tool.
+
+On the `Model Generator` page, enter `tbl_user` (the post table name) in the `Table Name` field, and then press the `Preview` button. A preview table will show up. We can click on the link in the table to preview the code to be generated. If everything is ok, we can press the `Generate` button to generate the code and save it into a file.
+
+> Info: Because the code generator needs to save the generated code into files, it is required that the Web process have the permission to create and modify the corresponding files. For simplicity, we may give the Web process the write permission to the whole `/wwwroot/blog` directory. Note that this is only needed on development machines when using `Gii`.
+
+Repeat the same procedure for the rest of the database tables, including `table_post`, `tbl_comment`, `tbl_tag` and `tbl_lookup`.
+
+> Tip: We can also enter an asterisk character '*' in the `Table Name` field. This will generate a model class for *every* database table in a single shot.
+
+At this stage, we will have the following newly created files:
-To prepare for the next milestones, let's take a closer look at the files generated by the above commands. All the files are generated under `/wwwroot/blog/protected`. For convenience, we group them into [model](http://www.yiiframework.com/doc/guide/basics.model) files, [controller](http://www.yiiframework.com/doc/guide/basics.controller) files and [view](http://www.yiiframework.com/doc/guide/basics.view) files:
+ * `models/User.php` contains the `User` class that extends from [CActiveRecord] and can be used to access the `tbl_user` database table;
+ * `models/Post.php` contains the `Post` class that extends from [CActiveRecord] and can be used to access the `tbl_post` database table;
+ * `models/Tag.php` contains the `Tag` class that extends from [CActiveRecord] and can be used to access the `tbl_tag` database table;
+ * `models/Comment.php` contains the `Comment` class that extends from [CActiveRecord] and can be used to access the `tbl_comment` database table;
+ * `models/Lookup.php` contains the `Lookup` class that extends from [CActiveRecord] and can be used to access the `tbl_lookup` database table.
- - model files:
- * `models/User.php` contains the `User` class that extends from [CActiveRecord] and can be used to access the `tbl_user` database table;
- * `models/Post.php` contains the `Post` class that extends from [CActiveRecord] and can be used to access the `tbl_post` database table;
- * `models/Tag.php` contains the `Tag` class that extends from [CActiveRecord] and can be used to access the `tbl_tag` database table;
- * `models/Comment.php` contains the `Comment` class that extends from [CActiveRecord] and can be used to access the `tbl_comment` database table;
- * `models/Lookup.php` contains the `Lookup` class that extends from [CActiveRecord] and can be used to access the `tbl_lookup` database table;
+
+Implementing CRUD Operations
+----------------------------
+
+After the model classes are created, we can use the `Crud Generator` to generate the code implementing the CRUD operations for these models. We will do this for the `Post` and `Comment` models.
+
+On the `Crud Generator` page, enter `Post` (the name of the post model class we just created) in the `Model Class` field, and then press the `Preview` button. We will see a lot more files will be generated. Press the `Generate` button to generate them.
+
+Repeat the same procedure for the `Comment` model.
+
+Let's take a look at the files generated by the CRUD generator. All the files are generated under `/wwwroot/blog/protected`. For convenience, we group them into [controller](http://www.yiiframework.com/doc/guide/basics.controller) files and [view](http://www.yiiframework.com/doc/guide/basics.view) files:
- controller file:
* `controllers/PostController.php` contains the `PostController` class which is the controller in charge of all CRUD operations about posts;
@@ -67,6 +91,20 @@ To prepare for the next milestones, let's take a closer look at the files genera
* `views/post/_search.php` is the partial view file used by `views/post/admin.php`. It displays a search form.
* a similar set of view files are also generated for comment.
+
+Testing
+-------
+
+We can test the features implemented by the code we just generated by accessing the following URLs:
+
+~~~
+http://www.example.com/blog/index.php?r=post
+http://www.example.com/blog/index.php?r=comment
+~~~
+
+Notice that the post and comment features implemented by the generated code are completely independent of each other. Also, when creating a new post or comment, we are required to enter information, such as `author_id` and `create_time`, which in real application should be set by the program. Don't worry. We will fix these problems in the next milestones. For now, we should be fairly satisfied as this prototype already contains most features that we need to implement for the blog application.
+
+
In order to understand better how the above files are used, we show in the following the workflow that occurs in the blog application when displaying a list of posts:
0. The user requests the URL `http://www.example.com/blog/index.php?r=post`;

0 comments on commit 9cdb11f

Please sign in to comment.