diff --git a/docs/guide/concept-components.md b/docs/guide/concept-components.md index 92a2362035..03df6501b8 100644 --- a/docs/guide/concept-components.md +++ b/docs/guide/concept-components.md @@ -1,10 +1,14 @@ Components ========== -Components are the main building blocks in Yii applications. Components are instances of [[yii\base\Component]] -or it child class. They support features such as [properties](concept-properties.md), [events](concept-events.md) and -[behaviors](concept-behaviors.md), which makes them more customizable and easier to use. For example, you may use -the included [[yii\jui\DatePicker|date picker widget]], a user interface component, in a [view](structure-view.md) +Components are the main building blocks of Yii applications. Components are instances of [[yii\base\Component]] +or an extended class. The three main features that components provide to other classes are: + +* [Properties](concept-properties.md) +* [Events](concept-events.md) +* [Behaviors](concept-behaviors.md), + +Separately and combined, these features make Yii classes much more customizable and easier to use. For example, the included [[yii\jui\DatePicker|date picker widget]], a user interface component, can be used in a [view](structure-view.md) to generate an interactive date picker: ```php @@ -19,21 +23,23 @@ echo DatePicker::widget([ ]); ``` -While components are very powerful, they are a bit heavier compared to normal objects, due to the fact that -it takes extra memory and CPU time in order to support [events](concept-events.md) and [behaviors](concept-behaviors.md). +The widget's properties are easily writable because the class extends [[yii\base\Component]]. + +While components are very powerful, they are a bit heavier than normal objects, due to the fact that +it takes extra memory and CPU time to support [events](concept-events.md) and [behaviors](concept-behaviors.md) in particular. If your components do not need these two features, you may consider extending your component class from -[[yii\base\Object]] instead of [[yii\base\Component]], which will make your components as efficient as normal objects, -but with the extra support for [properties](concept-properties.md). +[[yii\base\Object]] instead of [[yii\base\Component]]. Doing so will make your components as efficient as normal PHP objects, +but with the added support for [properties](concept-properties.md). When extending your class from [[yii\base\Component]] or [[yii\base\Object]], it is recommended that you follow these conventions: -- If you override the constructor, specify a `$config` parameter as its *last* parameter and pass this parameter +- If you override the constructor, specify a `$config` parameter as the constructor's *last* parameter, and then pass this parameter to the parent constructor. -- Call parent constructor at the end of the constructor. -- If you override the [[yii\base\Object::init()]] method, make sure you call the parent implementation. +- Always call the parent constructor *at the end* of your overriding constructor. +- If you override the [[yii\base\Object::init()]] method, make sure you call the parent implementation of `init` *at the beginning* of your `init` method. -For example, +For example: ```php namespace yii\components\MyClass; @@ -61,7 +67,7 @@ class MyClass extends Object } ``` -This will make your components [configurable](concept-configurations.md) when they are being created. For example, +Following these guideliness will make your components [configurable](concept-configurations.md) when they are created. For example: ```php $component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]); @@ -73,17 +79,16 @@ $component = \Yii::createObject([ ], [1, 2]); ``` -> Info: While the call of [[Yii::createObject()]] looks more complicated, it is more powerful due to +> Info: While the approach of calling [[Yii::createObject()]] looks more complicated, it is more powerful due to the fact that it is implemented on top of a [dependency injection container](concept-di-container.md). The [[yii\base\Object]] class enforces the following object lifecycle: -1. Pre-initialization within constructor. You can set default property values here. -2. Configuring object with `$config`. The configuration may overwrite the default values set above. -3. Post-initialization within [[yii\base\Object::init()|init()]]. You may override this method - and do sanity check and normalization of the properties. +1. Pre-initialization within the constructor. You can set default property values here. +2. Object configuration via `$config`. The configuration may overwrite the default values set within the constructor. +3. Post-initialization within [[yii\base\Object::init()|init()]]. You may override this method to perform sanity checks and normalization of the properties. 4. Object method calls. -The first three steps all happen within the object constructor. This means, once you get an object instance, -it has already been initialized to a proper state that you can work on. +The first three steps all happen within the object's constructor. This means that once you get an object instance, +it has already been initialized to a proper state that you can reliably work with.