Finished components guide. [skip ci]

docs/guide/basic-components.md

@@ -1,19 +1,50 @@
 Components
 ==========
 
-> Note: This chapter is under development.
+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](basic-properties.md), [events](basic-events.md) and
+[behaviors](basic-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)
+to generate an interactive date picker:
 
+```php
+use yii\jui\DatePicker;
+
+echo DatePicker::widget([
+    'language' => 'ru',
+    'name'  => 'country',
+    'clientOptions' => [
+        'dateFormat' => 'yy-mm-dd',
+    ],
+]);
+```
 
-Object Configuration
---------------------
+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](basic-events.md) and [behaviors](basic-behaviors.md).
+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](basic-properties.md).
 
-The [[yii\base\Object|Object]] class introduces a uniform way of configuring objects. Any descendant class
-of [[yii\base\Object|Object]] should declare its constructor (if needed) in the following way so that
-it can be properly configured:
+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
+  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.
+
+For example,
 
 ```php
-class MyClass extends \yii\base\Object
+namespace yii\components\MyClass;
+
+use yii\base\Object;
+
+class MyClass extends Object
 {
+    public $prop1;
+    public $prop2;
+
     public function __construct($param1, $param2, $config = [])
     {
         // ... initialization before configuration is applied
@@ -30,17 +61,25 @@ class MyClass extends \yii\base\Object
 }
 ```
 
-In the above example, the last parameter of the constructor must take a configuration array
-which contains name-value pairs that will be used to initialize the object's properties at the end of the constructor.
-You can override the `init()` method to do initialization work after the configuration is applied.
-
-By following this convention, you will be able to create and configure new objects
-using a configuration array like the following:
+This will make your components [configurable](basic-configurations.md) when they are being created. For example,
 
 ```php
-$object = Yii::createObject([
-    'class' => 'MyClass',
-    'property1' => 'abc',
-    'property2' => 'cde',
-], [$param1, $param2]);
+$component = new MyClass(1, 2, ['prop1' => 3, 'prop2' => 4]);
+// alternatively
+$component = \Yii::createObject([
+    'class' => MyClass::className(),
+    'prop1' => 3,
+    'prop2' => 4,
+], [1, 2]);
 ```
+
+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.
+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.