From ea6f29dd194145c8d30b144910f9ebbf61697557 Mon Sep 17 00:00:00 2001
From: Alexander Makarov <sam@rmcreative.ru>
Date: Wed, 26 Feb 2014 00:04:31 +0400
Subject: [PATCH] Started data components documentation
---
docs/guide/data-grid.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
docs/guide/data-overview.md | 14 ++++++++++++++
docs/guide/data-providers.md | 21 +++++++++++++++++++++
docs/guide/data-widgets.md | 2 ++
docs/guide/index.md | 8 ++++----
5 files changed, 110 insertions(+), 4 deletions(-)
create mode 100644 docs/guide/data-grid.md
create mode 100644 docs/guide/data-overview.md
create mode 100644 docs/guide/data-providers.md
create mode 100644 docs/guide/data-widgets.md
diff --git a/docs/guide/data-grid.md b/docs/guide/data-grid.md
new file mode 100644
index 0000000..ddea504
--- /dev/null
+++ b/docs/guide/data-grid.md
@@ -0,0 +1,69 @@
+Data grid
+=========
+
+Data grid or GridView is one of the most powerful Yii widgets. It is extremely useful if you need to quickly build admin
+section of the system. It takes data from [data provider](data-provider.md) and renders each row using a set of columns
+presenting data in a form of a table.
+
+Each row of the table represents the data of a single data item, and a column usually represents an attribute of
+the item (some columns may correspond to complex expression of attributes or static text).
+
+Grid view supports both sorting and pagination of the data items. The sorting and pagination can be done in AJAX mode
+or normal page request. A benefit of using GridView is that when the user disables JavaScript, the sorting and pagination
+automatically degrade to normal page requests and are still functioning as expected.
+
+The minimal code needed to use CGridView is as follows:
+
+```php
+sdf
+```
+
+The above code first creates a data provider and then uses GridView to display every attribute in every row taken from
+data provider. The displayed table is equiped with sorting and pagination functionality.
+
+Grid columns
+------------
+
+Yii grid consists of a number of columns. Depending on column type and settings these are able to present data differently.
+
+These are defined in the columns part of GridView config like the following:
+
+```php
+$this->widget('zii.widgets.grid.CGridView', array(
+ 'dataProvider'=>$dataProvider,
+ 'columns'=>array(
+ // A simple column defined by the data contained in $dataProvider.
+ // Data from model's column1 will be used.
+ 'column1',
+ // More complex one.
+ array(
+ 'class' => 'CDataColumn', // can be omitted, default
+ 'name'=>'column1',
+ 'value'=>function($data,$row){
+ return $data->name;
+ },
+ 'type'=>'raw',
+ ),
+ ),
+));
+```
+
+Note: If columns part of config isn't specified, Yii tries to show all possible data provider model columns.
+
+
+### Column classes
+
+TODO: rewrite these:
+
+- https://github.com/samdark/a-guide-to-yii-grids-lists-and-data-providers/blob/master/grid-columns.md
+- https://github.com/samdark/a-guide-to-yii-grids-lists-and-data-providers/pull/1
+
+Sorting data
+------------
+
+- https://github.com/yiisoft/yii2/issues/1576
+
+Filtering data
+--------------
+
+- https://github.com/yiisoft/yii2/issues/1581
\ No newline at end of file
diff --git a/docs/guide/data-overview.md b/docs/guide/data-overview.md
new file mode 100644
index 0000000..6318d18
--- /dev/null
+++ b/docs/guide/data-overview.md
@@ -0,0 +1,14 @@
+Data and widgets for it
+=======================
+
+One of the most powerful aspects of Yii is how it works with data. One may output data directly and that's a good approach
+for website frontend but when it comes to backend data components and widgets may save you weeks.
+
+Typically, you would take the following steps when working with one of these data components:
+
+1. Configure data provider. It may take its data from array, SQL, AR query etc.
+2. Pass data provider to one of the widgets such as list view or grid view.
+3. Customize the widget to reflect the presentational style that you are after.
+
+That's it. After doing these simple steps you can get a full featured data grid supporting pagination, sorting and
+filtering that is ideal for admin part of your project.
\ No newline at end of file
diff --git a/docs/guide/data-providers.md b/docs/guide/data-providers.md
new file mode 100644
index 0000000..76c19be
--- /dev/null
+++ b/docs/guide/data-providers.md
@@ -0,0 +1,21 @@
+Data providers
+==============
+
+Data provider abstracts data set via [[yii\data\DataProviderInterface]] and handles pagination and sorting.
+It can be used by [grids](data-grid.md), [lists and other data widgets](data-widgets.md).
+
+In Yii there are three built-in data providers: [[yii\data\ActiveDataProvider]], [[yii\data\ArrayDataProvider]] and
+[[yii\data\SqlDataProvider]].
+
+Active data provider
+--------------------
+
+Array data provider
+-------------------
+
+SQL data provider
+-----------------
+
+
+Implementing your own custom data provider
+------------------------------------------
diff --git a/docs/guide/data-widgets.md b/docs/guide/data-widgets.md
new file mode 100644
index 0000000..d445fcd
--- /dev/null
+++ b/docs/guide/data-widgets.md
@@ -0,0 +1,2 @@
+Data widgets
+============
\ No newline at end of file
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 349caa5..3d5305f 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -72,10 +72,10 @@ Security and access control
Data providers, lists and grids
-------------------------------
-- Overview
-- Data providers
-- Grids
-- Lists
+- [Overview](data-overview.md)
+- [Data providers](data-providers.md)
+- [Data widgets](data-widgets.md)
+- [Grid](data-grid.md)
Advanced Topics
---------------
--
libgit2 0.27.1