From 04cf5373941074963d52c62e3cb1e48941dab8e0 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Tue, 8 Jan 2013 10:52:35 -0500 Subject: [PATCH] move back api docs. --- docs/api/base/Component.md | 79 ++++++++++++++++++++++++++++++++++++++++ docs/api/base/Object.md | 36 ++++++++++++++++++ framework/base/Component.php | 2 +- framework/base/Object.php | 2 +- framework/docs/base-Component.md | 79 ---------------------------------------- framework/docs/base-Object.md | 36 ------------------ 6 files changed, 117 insertions(+), 117 deletions(-) create mode 100644 docs/api/base/Component.md create mode 100644 docs/api/base/Object.md delete mode 100644 framework/docs/base-Component.md delete mode 100644 framework/docs/base-Object.md diff --git a/docs/api/base/Component.md b/docs/api/base/Component.md new file mode 100644 index 0000000..3dbf2cb --- /dev/null +++ b/docs/api/base/Component.md @@ -0,0 +1,79 @@ +Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in +its parent class [[Object]]. + +Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger +an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event +is triggered, our custom code will be executed. + +An event is identified by a name (unique within the class it is defined). Event names are *case-sensitive*. + +An event can be attached with one or multiple PHP callbacks, called *event handlers*. One can call [[trigger()]] to +raise an event. When an event is raised, the attached event handlers will be invoked automatically in the order they are +attached to the event. + +To attach an event handler to an event, call [[on()]]. For example, + +~~~ +$comment->on('add', function($event) { + // send email notification +}); +~~~ + +In the above, we attach an anonymous function to the "add" event of the comment. Valid event handlers include: + +- anonymous function: `function($event) { ... }` +- object method: `array($object, 'handleAdd')` +- static method: `array('Page', 'handleAdd')` +- global function: `'handleAdd'` + +The signature of an event handler should be like the following: + +~~~ +function foo($event) +~~~ + +where `$event` is an [[Event]] object which includes parameters associated with the event. + +One can also attach an event handler to an event when configuring a component with a configuration array. The syntax is +like the following: + +~~~ +array( + 'on add' => function($event) { ... } +) +~~~ + +where `on add` stands for attaching an event to the `add` event. + +One can call [[getEventHandlers()]] to retrieve all event handlers that are attached to a specified event. Because this +method returns a [[Vector]] object, we can manipulate this object to attach/detach event handlers, or adjust their +relative orders. + +~~~ +$handlers = $comment->getEventHandlers('add'); +$handlers->insertAt(0, $callback); // attach a handler as the first one +$handlers[] = $callback; // attach a handler as the last one +unset($handlers[0]); // detach the first handler +~~~ + + +A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple +behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the +component directly, as if the component owns those properties and methods. + +To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors +declared in [[behaviors()]] are automatically attached to the corresponding component. + +One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the +following: + +~~~ +array( + 'as tree' => array( + 'class' => 'Tree', + ), +) +~~~ + +where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]] +to create the behavior object. \ No newline at end of file diff --git a/docs/api/base/Object.md b/docs/api/base/Object.md new file mode 100644 index 0000000..6764504 --- /dev/null +++ b/docs/api/base/Object.md @@ -0,0 +1,36 @@ +A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example, +the following getter and setter methods define a property named `label`: + +~~~ +private $_label; + +public function getLabel() +{ + return $this->_label; +} + +public function setLabel($value) +{ + $this->_label = $value; +} +~~~ + +Property names are *case-insensitive*. + +A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation +of the corresponding getter or setter method. For example, + +~~~ +// equivalent to $label = $object->getLabel(); +$label = $object->label; +// equivalent to $object->setLabel('abc'); +$object->label = 'abc'; +~~~ + +If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying +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/framework/base/Component.php b/framework/base/Component.php index e7cf72a..9c97894 100644 --- a/framework/base/Component.php +++ b/framework/base/Component.php @@ -12,7 +12,7 @@ namespace yii\base; /** * Component is the base class that provides the *property*, *event* and *behavior* features. * - * @include @yii/docs/base-Component.md + * @include @yii/base/Component.md * * @property Behavior[] behaviors list of behaviors currently attached to this component * diff --git a/framework/base/Object.php b/framework/base/Object.php index 15723dc..113cce3 100644 --- a/framework/base/Object.php +++ b/framework/base/Object.php @@ -12,7 +12,7 @@ namespace yii\base; /** * Object is the base class that provides the *property* feature. * - * @include @yii/docs/base-Object.md + * @include @yii/base/Object.md * * @author Qiang Xue * @since 2.0 diff --git a/framework/docs/base-Component.md b/framework/docs/base-Component.md deleted file mode 100644 index 3dbf2cb..0000000 --- a/framework/docs/base-Component.md +++ /dev/null @@ -1,79 +0,0 @@ -Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in -its parent class [[Object]]. - -Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger -an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event -is triggered, our custom code will be executed. - -An event is identified by a name (unique within the class it is defined). Event names are *case-sensitive*. - -An event can be attached with one or multiple PHP callbacks, called *event handlers*. One can call [[trigger()]] to -raise an event. When an event is raised, the attached event handlers will be invoked automatically in the order they are -attached to the event. - -To attach an event handler to an event, call [[on()]]. For example, - -~~~ -$comment->on('add', function($event) { - // send email notification -}); -~~~ - -In the above, we attach an anonymous function to the "add" event of the comment. Valid event handlers include: - -- anonymous function: `function($event) { ... }` -- object method: `array($object, 'handleAdd')` -- static method: `array('Page', 'handleAdd')` -- global function: `'handleAdd'` - -The signature of an event handler should be like the following: - -~~~ -function foo($event) -~~~ - -where `$event` is an [[Event]] object which includes parameters associated with the event. - -One can also attach an event handler to an event when configuring a component with a configuration array. The syntax is -like the following: - -~~~ -array( - 'on add' => function($event) { ... } -) -~~~ - -where `on add` stands for attaching an event to the `add` event. - -One can call [[getEventHandlers()]] to retrieve all event handlers that are attached to a specified event. Because this -method returns a [[Vector]] object, we can manipulate this object to attach/detach event handlers, or adjust their -relative orders. - -~~~ -$handlers = $comment->getEventHandlers('add'); -$handlers->insertAt(0, $callback); // attach a handler as the first one -$handlers[] = $callback; // attach a handler as the last one -unset($handlers[0]); // detach the first handler -~~~ - - -A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple -behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the -component directly, as if the component owns those properties and methods. - -To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors -declared in [[behaviors()]] are automatically attached to the corresponding component. - -One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the -following: - -~~~ -array( - 'as tree' => array( - 'class' => 'Tree', - ), -) -~~~ - -where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]] -to create the behavior object. \ No newline at end of file diff --git a/framework/docs/base-Object.md b/framework/docs/base-Object.md deleted file mode 100644 index 6764504..0000000 --- a/framework/docs/base-Object.md +++ /dev/null @@ -1,36 +0,0 @@ -A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example, -the following getter and setter methods define a property named `label`: - -~~~ -private $_label; - -public function getLabel() -{ - return $this->_label; -} - -public function setLabel($value) -{ - $this->_label = $value; -} -~~~ - -Property names are *case-insensitive*. - -A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation -of the corresponding getter or setter method. For example, - -~~~ -// equivalent to $label = $object->getLabel(); -$label = $object->label; -// equivalent to $object->setLabel('abc'); -$object->label = 'abc'; -~~~ - -If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying -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.