From da0ef127b57758f645b76c9f7c8ed6c93d0240aa Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Fri, 1 Feb 2013 18:06:21 +0100 Subject: [PATCH] proof reading docs, fixed event order in AR --- docs/api/base/Component.md | 4 ++-- docs/api/base/Object.md | 3 --- docs/api/db/ActiveRecord.md | 14 +++++++------- docs/model.md | 4 ++-- framework/db/ActiveRecord.php | 20 ++++++++++---------- 5 files changed, 21 insertions(+), 24 deletions(-) diff --git a/docs/api/base/Component.md b/docs/api/base/Component.md index 98c5213..89b8c0b 100644 --- a/docs/api/base/Component.md +++ b/docs/api/base/Component.md @@ -7,7 +7,7 @@ is triggered (i.e. comment will be added), our custom code will be executed. An event is identified by a name that should be unique within the class it is defined at. Event names are *case-sensitive*. -One or multiple PHP callbacks, called *event handlers*, could be attached to event. You can call [[trigger()]] to +One or multiple PHP callbacks, called *event handlers*, could be attached to an event. You can call [[trigger()]] to raise an event. When an event is raised, the event handlers will be invoked automatically in the order they were attached. @@ -24,7 +24,7 @@ Valid event handlers include: - anonymous function: `function($event) { ... }` - object method: `array($object, 'handleAdd')` -- static method: `array('Page', 'handleAdd')` +- static class method: `array('Page', 'handleAdd')` - global function: `'handleAdd'` The signature of an event handler should be like the following: diff --git a/docs/api/base/Object.md b/docs/api/base/Object.md index 6764504..a2cea6c 100644 --- a/docs/api/base/Object.md +++ b/docs/api/base/Object.md @@ -31,6 +31,3 @@ If a property has only a getter method and has no setter method, it is considere to modify the property value will cause an exception. One can call [[hasProperty]], [[canGetProperty]] and/or [[canSetProperty]] to check the existence of a property. - -Besides the property feature, the Object class defines a static method [[create]] which provides a convenient -alternative way of creating a new object instance. diff --git a/docs/api/db/ActiveRecord.md b/docs/api/db/ActiveRecord.md index 945a349..da281d8 100644 --- a/docs/api/db/ActiveRecord.md +++ b/docs/api/db/ActiveRecord.md @@ -1,5 +1,5 @@ ActiveRecord implements the [Active Record design pattern](http://en.wikipedia.org/wiki/Active_record). -The idea is that ActiveRecord object is associated with a row in a database table +The idea is that an ActiveRecord object is associated with a row in a database table so object properties are mapped to colums of the corresponding database row. For example, a `Customer` object is associated with a row in the `tbl_customer` table. Instead of writing raw SQL statements to access the data in the table, @@ -62,7 +62,7 @@ There are two ActiveRecord methods for getting data: - [[find()]] - [[findBySql()]] -They all return an [[ActiveQuery]] instance. Coupled with the various customization and query methods +They both return an [[ActiveQuery]] instance. Coupled with the various customization and query methods provided by [[ActiveQuery]], ActiveRecord supports very flexible and powerful data retrieval approaches. The followings are some examples, @@ -158,7 +158,7 @@ $customer = Customer::find($id); $customer->delete(); // to increment the age of all customers by 1 -Customer::updateAllCounters(array('age' => +1)); +Customer::updateAllCounters(array('age' => 1)); ~~~ @@ -386,10 +386,10 @@ When getting an ActiveRecord instance through the [[find()]] method, we will hav When calling [[save()]] to insert or update an ActiveRecord, we will have the following life cycles: 1. [[beforeValidate()]]: will trigger an [[EVENT_BEFORE_VALIDATE]] event -2. [[beforeSave()]]: will trigger an [[EVENT_BEFORE_INSERT]] or [[EVENT_BEFORE_UPDATE]] event -3. perform the actual data insertion or updating -4. [[afterSave()]]: will trigger an [[EVENT_AFTER_INSERT]] or [[EVENT_AFTER_UPDATE]] event -5. [[afterValidate()]]: will trigger an [[EVENT_AFTER_VALIDATE]] event +2. [[afterValidate()]]: will trigger an [[EVENT_AFTER_VALIDATE]] event +3. [[beforeSave()]]: will trigger an [[EVENT_BEFORE_INSERT]] or [[EVENT_BEFORE_UPDATE]] event +4. perform the actual data insertion or updating +5. [[afterSave()]]: will trigger an [[EVENT_AFTER_INSERT]] or [[EVENT_AFTER_UPDATE]] event Finally when calling [[delete()]] to delete an ActiveRecord, we will have the following life cycles: diff --git a/docs/model.md b/docs/model.md index 1c34dd2..4c39a5b 100644 --- a/docs/model.md +++ b/docs/model.md @@ -7,7 +7,7 @@ Attributes Attributes store the actual data represented by a model and can be accessed like object member variables. For example, a `Post` model may contain a `title` attribute and a `content` attribute which may be -accessed as follows, +accessed as follows: ~~~php $post->title = 'Hello, world'; @@ -51,7 +51,7 @@ Scenarios A model may be used in different scenarios. For example, a `User` model may be used to collect user login inputs, and it may also be used for user registration purpose. For this reason, each model has a property named `scenario` which stores -the name of the scenario that the model is currently being used. As we will explain +the name of the scenario that the model is currently being used in. As we will explain in the next few sections, the concept of scenario is mainly used in validation and massive attribute assignment. diff --git a/framework/db/ActiveRecord.php b/framework/db/ActiveRecord.php index e13799b..c6d3d81 100644 --- a/framework/db/ActiveRecord.php +++ b/framework/db/ActiveRecord.php @@ -602,13 +602,13 @@ class ActiveRecord extends Model * * 1. call [[beforeValidate()]] when `$runValidation` is true. If validation * fails, it will skip the rest of the steps; - * 2. call [[beforeSave()]]. If the method returns false, it will skip the + * 2. call [[afterValidate()]] when `$runValidation` is true. + * 3. call [[beforeSave()]]. If the method returns false, it will skip the * rest of the steps; - * 3. insert the record into database. If this fails, it will skip the rest of the steps; - * 4. call [[afterSave()]]; - * 5. call [[afterValidate()]] when `$runValidation` is true. + * 4. insert the record into database. If this fails, it will skip the rest of the steps; + * 5. call [[afterSave()]]; * - * In the above step 1, 2, 4 and 5, events [[EVENT_BEFORE_VALIDATE]], + * In the above step 1, 2, 3 and 5, events [[EVENT_BEFORE_VALIDATE]], * [[EVENT_BEFORE_INSERT]], [[EVENT_AFTER_INSERT]] and [[EVENT_AFTER_VALIDATE]] * will be raised by the corresponding methods. * @@ -673,13 +673,13 @@ class ActiveRecord extends Model * * 1. call [[beforeValidate()]] when `$runValidation` is true. If validation * fails, it will skip the rest of the steps; - * 2. call [[beforeSave()]]. If the method returns false, it will skip the + * 2. call [[afterValidate()]] when `$runValidation` is true. + * 3. call [[beforeSave()]]. If the method returns false, it will skip the * rest of the steps; - * 3. save the record into database. If this fails, it will skip the rest of the steps; - * 4. call [[afterSave()]]; - * 5. call [[afterValidate()]] when `$runValidation` is true. + * 4. save the record into database. If this fails, it will skip the rest of the steps; + * 5. call [[afterSave()]]; * - * In the above step 1, 2, 4 and 5, events [[EVENT_BEFORE_VALIDATE]], + * In the above step 1, 2, 3 and 5, events [[EVENT_BEFORE_VALIDATE]], * [[EVENT_BEFORE_UPDATE]], [[EVENT_AFTER_UPDATE]] and [[EVENT_AFTER_VALIDATE]] * will be raised by the corresponding methods. *