From b05442d368e08c999d018fec538eaf1f63f1ba76 Mon Sep 17 00:00:00 2001 From: Larry Ullman Date: Fri, 13 Sep 2013 11:23:56 -0400 Subject: [PATCH] Doing that editing thing --- docs/guide/active-record.md | 64 +++++++++++++++++++++-------------------- docs/guide/bootstrap-widgets.md | 9 +++--- docs/guide/overview.md | 18 ++++++------ docs/guide/template.md | 3 +- 4 files changed, 46 insertions(+), 48 deletions(-) diff --git a/docs/guide/active-record.md b/docs/guide/active-record.md index 0c93fad..fc98f98 100644 --- a/docs/guide/active-record.md +++ b/docs/guide/active-record.md @@ -2,12 +2,12 @@ Active Record ============= Active Record implements the [Active Record design pattern](http://en.wikipedia.org/wiki/Active_record). -The premise behind Active Record is that an individual [[ActiveRecord]] object is associated with a specific row in a database table. The object's attributes are mapped to the columns of the corresponding table. Therefore, referencing an Active Record attribute is equivalent to accessing +The premise behind Active Record is that an individual [[ActiveRecord]] object is associated with a specific row in a database table. The object's attributes are mapped to the columns of the corresponding table. Referencing an Active Record attribute is equivalent to accessing the corresponding table column for that record. -For example, say that the `Customer` ActiveRecord class is associated with the +As an example, say that the `Customer` ActiveRecord class is associated with the `tbl_customer` table. This would mean that the class's `name` attribute is automatically mapped to the `name` column in `tbl_customer`. -Thanks to Active Record, assuming the variable `$customer` is an object of type `Customer`, to get the value of the `name` column for the table row, you can simply use the expression `$customer->name`. In this example, Active Record is providing an object-oriented way to access data stored in the database, just as you would access any object property. But Active Record provides much more functionality than this. +Thanks to Active Record, assuming the variable `$customer` is an object of type `Customer`, to get the value of the `name` column for the table row, you can use the expression `$customer->name`. In this example, Active Record is providing an object-oriented interface for accessing data stored in the database. But Active Record provides much more functionality than this. With Active Record, instead of writing raw SQL statements to perform database queries, you can call intuitive methods to achieve the same goals. For example, calling [[ActiveRecord::save()|save()]] would perform an INSERT or UPDATE query, creating or updating a row in the associated table of the ActiveRecord class: @@ -39,6 +39,13 @@ class Customer extends ActiveRecord } ``` +The `tableName` method only has to return the name of the database table associated with the class. + +Class instances are obtained in one of two ways: + +* Using the `new` operator to create a new, empty object +* Using a method to fetch an existing record (or records) from the database + Connecting to the Database ---------------------- @@ -59,11 +66,7 @@ return array( ); ``` -Please read the [Database basics](database-basics.md) section to learn more on how to configure -and use database connections. - -> Tip: To use a different database connection, you need to override the [[ActiveRecord::getDb()]] method. To do that, create a base class that extends ActiveRecord. In the base class, override the [[ActiveRecord::getDb()]] method. Then extend your new base class for all of your ActiveRecord classes that need to use the same alternative database connection. - +Please read the [Database basics](database-basics.md) section to learn more on how to configure and use database connections. Querying Data from the Database --------------------------- @@ -73,8 +76,8 @@ There are two ActiveRecord methods for querying data from database: - [[ActiveRecord::find()]] - [[ActiveRecord::findBySql()]] -Both methods return an [[ActiveQuery]] instance, which extends from [[Query]] thus supporting -the same set of flexible and powerful DB query methods. The followings examples demonstrate some of the possibilities. +Both methods return an [[ActiveQuery]] instance, which extends [[Query]], and thus supports +the same set of flexible and powerful DB query methods. The following examples demonstrate some of the possibilities. ```php // to retrieve all *active* customers and order them by their ID: @@ -115,25 +118,24 @@ $customers = Customer::find()->indexBy('id')->all(); Accessing Column Data --------------------- -ActiveRecord maps each column of the corresponding database table row to an *attribute* in the ActiveRecord +ActiveRecord maps each column of the corresponding database table row to an attribute in the ActiveRecord object. The attribute behaves like any regular object public property. The attribute's name will be the same as the corresponding column name, and is case-sensitive. To read the value of a column, you can use the following syntax: ```php -// "id" is the name of a column in the table associated with $customer ActiveRecord object +// "id" and "email" are the names of columns in the table associated with $customer ActiveRecord object $id = $customer->id; -// or alternatively, -$id = $customer->getAttribute('id'); +$email = $customer->email; ``` -You can get all column values through the [[ActiveRecord::attributes]] property: +To change the value of a column, assign a new value to the associated property and save the object: -```php -$values = $customer->attributes; ``` - +$customer->email = 'jane@example.com'; +$customer->save(); +``` Manipulating Data in the Database ----------------------------- @@ -150,8 +152,8 @@ ActiveRecord provides the following methods to insert, update and delete data in - [[ActiveRecord::deleteAll()|deleteAll()]] Note that [[ActiveRecord::updateAll()|updateAll()]], [[ActiveRecord::updateAllCounters()|updateAllCounters()]] -and [[ActiveRecord::deleteAll()|deleteAll()]] are static methods and apply to the whole database -table, while the other methods only apply to the row associated with the ActiveRecord object through which the method is being called. +and [[ActiveRecord::deleteAll()|deleteAll()]] are static methods that apply to the whole database +table. The other methods only apply to the row associated with the ActiveRecord object through which the method is being called. ```php // to insert a new customer record @@ -173,12 +175,21 @@ $customer->delete(); Customer::updateAllCounters(array('age' => 1)); ``` +Notice that you can always use the `save` method, and ActiveRecord will automatically perform an INSERT for new records and an UPDATE for existing ones. + +Data Input and Validation +------------------------- + +ActiveRecord inherits data validation and data input features from [[\yii\base\Model]]. Data validation is called +automatically when `save()` is performed. If data validation fails, the saving operation will be cancelled. + +For more details refer to the [Model](model.md) section of this guide. Querying Relational Data ------------------------ -You can use ActiveRecord to query the relational data of a table. The relational data returned can -be accessed like a property of the ActiveRecord object associated with the primary table. +You can use ActiveRecord to also query a table's relational data (i.e., selection of data from Table A can also pull in related data from Table B). Thanks to ActiveRecord, the relational data returned can be accessed like a property of the ActiveRecord object associated with the primary table. + For example, with an appropriate relation declaration, by accessing `$customer->orders` you may obtain an array of `Order` objects which represent the orders placed by the specified customer. @@ -397,15 +408,6 @@ The [[link()]] call above will set the `customer_id` of the order to be the prim value of `$customer` and then call [[save()]] to save the order into database. -Data Input and Validation -------------------------- - -ActiveRecord inherits data validation and data input features from [[\yii\base\Model]]. Data validation is called -automatically when `save()` is performed. If data validation fails, the saving operation will be cancelled. - -For more details refer to the [Model](model.md) section of this guide. - - Life Cycles of an ActiveRecord Object ------------------------------------- diff --git a/docs/guide/bootstrap-widgets.md b/docs/guide/bootstrap-widgets.md index 0739847..3f56839 100644 --- a/docs/guide/bootstrap-widgets.md +++ b/docs/guide/bootstrap-widgets.md @@ -1,13 +1,12 @@ Bootstrap widgets ================= -Yii includes support of [Bootstrap 3](http://getbootstrap.com/) markup and components framework out of the box. It is an -excellent framework that allows you to speed up development a lot. +Yii includes support for the [Bootstrap 3](http://getbootstrap.com/) markup and components framework out of the box. Bootstrap is an excellent, responsive framework that can greatly speed up your development process. -Bootstrap is generally about two parts: +The core of Bootstrap is represented by two parts: -- Basics such as grid system, typography, helper classes and responsive utilities. -- Ready to use components such as menus, pagination, modal boxes, tabs etc. +- CSS basics, such as grid layout system, typography, helper classes, and responsive utilities. +- Ready to use components, such as menus, pagination, modal boxes, tabs etc. Basics ------ diff --git a/docs/guide/overview.md b/docs/guide/overview.md index d2ccb19..ef71aa0 100644 --- a/docs/guide/overview.md +++ b/docs/guide/overview.md @@ -1,8 +1,7 @@ What is Yii =========== -Yii is a high-performance, component-based PHP framework for developing -large-scale Web applications rapidly. It enables maximum reusability in Web +Yii is a high-performance, component-based PHP framework for rapidly developing large-scale Web applications. Yii enables maximum reusability in Web programming and can significantly accelerate your Web application development process. The name Yii (pronounced `Yee` or `[ji:]`) is an acronym for **Yes It Is!**. @@ -12,7 +11,7 @@ Requirements ------------ To run a Yii-powered Web application, you need a Web server that supports -PHP 5.3.?. +PHP 5.3.? or greater. For developers who want to use Yii, understanding object-oriented programming (OOP) is very helpful, because Yii is a pure OOP framework. @@ -31,10 +30,9 @@ management systems (CMS), e-commerce systems, etc. How does Yii Compare with Other Frameworks? ------------------------------------------- -- Like most PHP frameworks, Yii is an MVC (Model-View-Controller) framework. -- It is a fullstack framework providing many solutions and components such as logging, session management, caching etc. -- It has a good balance of simplicity and features. -- Syntax and overall development usability are taken seriously. -- Performance is one of the key goals. -- We are constantly watching other web frameworks out there and getting the best ideas in. Initial Yii release was heavily - influenced by Ruby on Rails. Still, we aren't blindly copying anything. +- Like most PHP frameworks, Yii is uses the MVC (Model-View-Controller) design approach. +- Yii is a fullstack framework providing many solutions and components, such as logging, session management, caching etc. +- Yii strikes a good balance between simplicity and features. +- Syntax and overall development usability are taken seriously by the Yii development team. +- Performance is one of the key goals for the Yii framework. +- The Yii development team is constantly watching what other Web frameworks are doing to see what best practices and features should be incorporated into Yii. The initial Yii release was heavily influenced by Ruby on Rails. Still, no framework or feature is being blindly copied into Yii; all decisions are based upon what's best for Web developers and in keeping with Yii's philosophy. diff --git a/docs/guide/template.md b/docs/guide/template.md index f2a6fc4..6d2db88 100644 --- a/docs/guide/template.md +++ b/docs/guide/template.md @@ -1,8 +1,7 @@ Using template engines ====================== -By default Yii uses PHP as template language but you can configure it to be able -to render templates with special engines such as Twig or Smarty. +By default Yii uses PHP as template language, but you can configure it to support other rendering engines, such as [Twig](http://twig.sensiolabs.org/) or [Smarty](http://www.smarty.net/). The component responsible for rendering a view is called `view`. You can add a custom template engines as follows: