API Documentation for Yii 1.1
0 follower
CArrayDataProvider
| Package | system.web |
|---|---|
| Inheritance | class CArrayDataProvider » CDataProvider » CComponent |
| Implements | IDataProvider |
| Since | 1.1.4 |
| Source Code | framework/web/CArrayDataProvider.php |
CArrayDataProvider implements a data provider based on a raw data array.
The rawData property contains all data that may be sorted and/or paginated. CArrayDataProvider will supply the data after sorting and/or pagination. You may configure the sort and pagination properties to customize sorting and pagination behaviors.
Elements in the raw data array may be either objects (e.g. model objects) or associative arrays (e.g. query results of DAO). Make sure to set the keyField property to the name of the field that uniquely identifies a data record or false if you do not have such a field.
CArrayDataProvider may be used in the following way:
Note: if you want to use the sorting feature, you must configure sort property so that the provider knows which columns can be sorted.
The rawData property contains all data that may be sorted and/or paginated. CArrayDataProvider will supply the data after sorting and/or pagination. You may configure the sort and pagination properties to customize sorting and pagination behaviors.
Elements in the raw data array may be either objects (e.g. model objects) or associative arrays (e.g. query results of DAO). Make sure to set the keyField property to the name of the field that uniquely identifies a data record or false if you do not have such a field.
CArrayDataProvider may be used in the following way:
$rawData=Yii::app()->db->createCommand('SELECT * FROM tbl_user')->queryAll();
// or using: $rawData=User::model()->findAll();
$dataProvider=new CArrayDataProvider($rawData, array(
'id'=>'user',
'sort'=>array(
'attributes'=>array(
'id', 'username', 'email',
),
),
'pagination'=>array(
'pageSize'=>10,
),
));
// $dataProvider->getData() will return a list of arrays.
Note: if you want to use the sorting feature, you must configure sort property so that the provider knows which columns can be sorted.
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| caseSensitiveSort | boolean | controls how sorting works. | CArrayDataProvider |
| data | array | Returns the data items currently available. | CDataProvider |
| id | string | Returns the ID that uniquely identifies the data provider. | CDataProvider |
| itemCount | integer | Returns the number of data items in the current page. | CDataProvider |
| keyField | string | the name of the key field. | CArrayDataProvider |
| keys | array | Returns the key values associated with the data items. | CDataProvider |
| pagination | CPagination|false | Returns the pagination object. | CDataProvider |
| rawData | array | the data that is not paginated or sorted. | CArrayDataProvider |
| sort | CSort|false | Returns the sort object. | CDataProvider |
| totalItemCount | integer | Returns the total number of data items. | CDataProvider |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| __call() | Calls the named method which is not a class method. | CComponent |
| __construct() | Constructor. | CArrayDataProvider |
| __get() | Returns a property value, an event handler list or a behavior based on its name. | CComponent |
| __isset() | Checks if a property value is null. | CComponent |
| __set() | Sets value of a component property. | CComponent |
| __unset() | Sets a component property to be null. | CComponent |
| asa() | Returns the named behavior object. | CComponent |
| attachBehavior() | Attaches a behavior to this component. | CComponent |
| attachBehaviors() | Attaches a list of behaviors to the component. | CComponent |
| attachEventHandler() | Attaches an event handler to an event. | CComponent |
| canGetProperty() | Determines whether a property can be read. | CComponent |
| canSetProperty() | Determines whether a property can be set. | CComponent |
| detachBehavior() | Detaches a behavior from the component. | CComponent |
| detachBehaviors() | Detaches all behaviors from the component. | CComponent |
| detachEventHandler() | Detaches an existing event handler. | CComponent |
| disableBehavior() | Disables an attached behavior. | CComponent |
| disableBehaviors() | Disables all behaviors attached to this component. | CComponent |
| enableBehavior() | Enables an attached behavior. | CComponent |
| enableBehaviors() | Enables all behaviors attached to this component. | CComponent |
| evaluateExpression() | Evaluates a PHP expression or callback under the context of this component. | CComponent |
| getData() | Returns the data items currently available. | CDataProvider |
| getEventHandlers() | Returns the list of attached event handlers for an event. | CComponent |
| getId() | Returns the ID that uniquely identifies the data provider. | CDataProvider |
| getItemCount() | Returns the number of data items in the current page. | CDataProvider |
| getKeys() | Returns the key values associated with the data items. | CDataProvider |
| getPagination() | Returns the pagination object. | CDataProvider |
| getSort() | Returns the sort object. | CDataProvider |
| getTotalItemCount() | Returns the total number of data items. | CDataProvider |
| hasEvent() | Determines whether an event is defined. | CComponent |
| hasEventHandler() | Checks whether the named event has attached handlers. | CComponent |
| hasProperty() | Determines whether a property is defined. | CComponent |
| raiseEvent() | Raises an event. | CComponent |
| setData() | Sets the data items for this provider. | CDataProvider |
| setId() | Sets the provider ID. | CDataProvider |
| setKeys() | Sets the data item keys for this provider. | CDataProvider |
| setPagination() | Sets the pagination for this data provider. | CDataProvider |
| setSort() | Sets the sorting for this data provider. | CDataProvider |
| setTotalItemCount() | Sets the total number of data items. | CDataProvider |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| calculateTotalItemCount() | Calculates the total number of data items. | CArrayDataProvider |
| fetchData() | Fetches the data from the persistent data storage. | CArrayDataProvider |
| fetchKeys() | Fetches the data item keys from the persistent data storage. | CArrayDataProvider |
| getSortDirections() | Converts the "ORDER BY" clause into an array representing the sorting directions. | CArrayDataProvider |
| getSortingFieldValue() | Get field for sorting, using dot like delimiter in query. | CArrayDataProvider |
| sortData() | Sorts the raw data according to the specified sorting instructions. | CArrayDataProvider |
Property Details
caseSensitiveSort
property
(available since v1.1.13)
public boolean $caseSensitiveSort;
controls how sorting works. True value means that case will be taken into account. False value will lead to the case insensitive sort. Default value is true.
keyField
property
public string $keyField;
the name of the key field. This is a field that uniquely identifies a data record. In database this would be the primary key. Defaults to 'id'. If it's set to false, keys of rawData array are used.
rawData
property
public array $rawData;
the data that is not paginated or sorted. When pagination is enabled, this property usually contains more elements than data. The array elements must use zero-based integer keys.
Method Details
__construct()
method
|
public void __construct(array $rawData, array $config=array (
))
| ||
| $rawData | array | the data that is not paginated or sorted. The array elements must use zero-based integer keys. |
| $config | array | configuration (name=>value) to be applied as the initial property values of this class. |
Source Code: framework/web/CArrayDataProvider.php#76 (show)
public function __construct($rawData,$config=array())
{
$this->rawData=$rawData;
foreach($config as $key=>$value)
$this->$key=$value;
}
Constructor.
calculateTotalItemCount()
method
|
protected integer calculateTotalItemCount()
| ||
| {return} | integer | the total number of data items. |
Source Code: framework/web/CArrayDataProvider.php#120 (show)
protected function calculateTotalItemCount()
{
return count($this->rawData);
}
Calculates the total number of data items. This method simply returns the number of elements in rawData.
fetchData()
method
|
protected array fetchData()
| ||
| {return} | array | list of data items |
Source Code: framework/web/CArrayDataProvider.php#87 (show)
protected function fetchData()
{
if(($sort=$this->getSort())!==false && ($order=$sort->getOrderBy())!='')
$this->sortData($this->getSortDirections($order));
if(($pagination=$this->getPagination())!==false)
{
$pagination->setItemCount($this->getTotalItemCount());
return array_slice($this->rawData, $pagination->getOffset(), $pagination->getLimit());
}
else
return $this->rawData;
}
Fetches the data from the persistent data storage.
fetchKeys()
method
|
protected array fetchKeys()
| ||
| {return} | array | list of data item keys. |
Source Code: framework/web/CArrayDataProvider.php#105 (show)
protected function fetchKeys()
{
if($this->keyField===false)
return array_keys($this->rawData);
$keys=array();
foreach($this->getData() as $i=>$data)
$keys[$i]=is_object($data) ? $data->{$this->keyField} : $data[$this->keyField];
return $keys;
}
Fetches the data item keys from the persistent data storage.
getSortDirections()
method
|
protected array getSortDirections(string $order)
| ||
| $order | string | the "ORDER BY" clause. |
| {return} | array | the sorting directions (field name => whether it is descending sort) |
Source Code: framework/web/CArrayDataProvider.php#187 (show)
protected function getSortDirections($order)
{
$segs=explode(',',$order);
$directions=array();
foreach($segs as $seg)
{
if(preg_match('/(.*?)(\s+(desc|asc))?$/i',trim($seg),$matches))
$directions[$matches[1]]=isset($matches[3]) && !strcasecmp($matches[3],'desc');
else
$directions[trim($seg)]=false;
}
return $directions;
}
Converts the "ORDER BY" clause into an array representing the sorting directions.
getSortingFieldValue()
method
|
protected mixed getSortingFieldValue(mixed $data, array $fields)
| ||
| $data | mixed | array or object |
| $fields | array | sorting fields in $data |
| {return} | mixed | $data sorting field value |
Source Code: framework/web/CArrayDataProvider.php#167 (show)
protected function getSortingFieldValue($data, $fields)
{
if(is_object($data))
{
foreach($fields as $field)
$data=isset($data->$field) ? $data->$field : null;
}
else
{
foreach($fields as $field)
$data=isset($data[$field]) ? $data[$field] : null;
}
return $this->caseSensitiveSort ? $data : mb_strtolower($data,Yii::app()->charset);
}
Get field for sorting, using dot like delimiter in query.
sortData()
method
|
protected void sortData(array $directions)
| ||
| $directions | array | the sorting directions (field name => whether it is descending sort) |
Source Code: framework/web/CArrayDataProvider.php#130 (show)
protected function sortData($directions)
{
if(empty($directions) || empty($this->rawData))
return;
$args=array();
$dummy=array();
foreach($directions as $name=>$descending)
{
$column=array();
$fields_array=preg_split('/\.+/',$name,-1,PREG_SPLIT_NO_EMPTY);
foreach($this->rawData as $index=>$data)
$column[$index]=$this->getSortingFieldValue($data, $fields_array);
$args[]=&$column;
$dummy[]=&$column;
unset($column);
$direction=$descending ? SORT_DESC : SORT_ASC;
$args[]=&$direction;
$dummy[]=&$direction;
unset($direction);
}
// This fix is used for cases when main sorting specified by columns has equal values
// Without it it will lead to Fatal Error: Nesting level too deep - recursive dependency?
$args[]=range(1,count($this->rawData));
$args[]=SORT_ASC;
$args[]=SORT_NUMERIC;
$args[]=&$this->rawData;
call_user_func_array('array_multisort', $args);
}
Sorts the raw data according to the specified sorting instructions. After calling this method, rawData will be modified.
rawData must be regular array, not a hash
If the rawData parameter is a hash, this widget will fail with an "Undefined offset: 0" error in CGridColumn.php.
Use array_values($a) to get just the values, effectively turning it into a regular, number-indexed array.
"id" is not "keyField"
CArrayDataProviderneeds to know which attribute of objects passed in the array in order to do pagination and sorting properly, and by default it assumes$object->idis the primary key. Otherwise, thekeyFieldattribute must be passed in the constructor array to tell provide the name of the key attribute.Confusingly, CADP also takes an
'id' => '...'attribute which is used to provide an ID for the data provider itself (to distinguish itself from other data providers), and this has nothing to do with the primary key of the objects:$dp = new CArrayDataProvider($list, array( 'keyField' => 'some_id', // PRIMARY KEY attribute of $list member objects 'id' => 'foo' // ID of the data provider itself ));Error "Model.id" not defined
If you get error "Model.id" not defined than keyField property is required, like in example:
new CArrayDataProvider($users, array('keyField' => 'user_id'));Signup or Login in order to comment.