CSort
| Пакет | system.web |
|---|---|
| Наследование | класс CSort » CComponent |
| Исходный код | framework/web/CSort.php |
Когда данные необходимо отсортировать по одному или нескольким атрибутам, мы можем использовать CSort для представления информации о сортировке и генерации соответствующих гиперссылок, которые могут привести к действиям сортировки.
CSort предназначен для совместного использования с CActiveRecord. При создании экземпляра CSort необходимо указать modelClass. Вы можете использовать CSort для генерации гиперссылок, вызвав метод link. Вы также можете использовать CSort для изменения экземпляра CDbCriteria, вызвав метод applyOrder, чтобы результаты запроса сортировались по указанным атрибутам.
Для предотвращения атак с использованием SQL-инъекций CSort гарантирует, что сортируются только допустимые атрибуты модели. Это определяется на основе modelClass и attributes. Если attributes не задано, можно сортировать все атрибуты, принадлежащие modelClass. Если attributes задано, можно сортировать только те атрибуты, которые объявлены в свойстве.
Настроив свойство attributes, можно выполнять более сложные сортировки, которые могут включать такие вещи, как составные атрибуты (например, сортировка по сочетанию имени и фамилии пользователей).
Свойство attributes должно быть массивом пар ключ-значение, где ключи представляют имена атрибутов, а значения — определения виртуальных атрибутов. Для получения более подробной информации, пожалуйста, ознакомьтесь с документацией по attributes.
Свойства
| Свойство | Тип | Описание | Определено |
|---|---|---|---|
| attributes | массив | список атрибутов, которые разрешено сортировать. | CSort |
| defaultOrder | смешанный тип | по умолчанию порядок, который должен быть применён к критериям запроса, когда текущий запрос не задаёт сортировку. | CSort |
| descTag | строка | метка, появляющаяся в параметре GET, которая указывает, что атрибут должен быть отсортирован по убыванию. | CSort |
| directions | массив | возвращает текущую запрошенную информацию о сортировке. | CSort |
| modelClass | строка | имя класса модели, атрибуты которой можно сортировать. | CSort |
| multiSort | булево | указывает, может ли сортировка применяться к нескольким атрибутам одновременно. | CSort |
| orderBy | строка | столбцы сортировки, представленные этим объектом. | CSort |
| params | массив | дополнительные параметры GET (имя=>значение), которые следует использовать при генерации URL-адресов сортировки. | CSort |
| route | строка | маршрут (идентификатор контроллера и идентификатор действия) для генерации отсортированного содержимого. | CSort |
| separators | массив | разделители, используемые в сгенерированном URL-адресе. | CSort |
| sortVar | строка | имя параметра GET, указывающее, какие атрибуты должны быть отсортированы и в каком направлении. | CSort |
Методы
| Метод | Описание | Определено |
|---|---|---|
| __call() | Вызывает именованный метод, который не является методом класса. | CComponent |
| __construct() | Конструктор. | CSort |
| __get() | Возвращает значение свойства, список обработчиков событий или поведение, основываясь на его имени. | CComponent |
| __isset() | Проверяет, является ли значение свойства null. | CComponent |
| __set() | Устанавливает значение свойства компонента. | CComponent |
| __unset() | Устанавливает свойство компонента в значение null. | CComponent |
| applyOrder() | Изменяет критерии запроса, изменив свойство CDbCriteria::order. | CSort |
| asa() | Возвращает объект поведения по имени. | CComponent |
| attachBehavior() | Прикрепляет поведение к этому компоненту. | CComponent |
| attachBehaviors() | Прикрепляет список поведений к компоненту. | CComponent |
| attachEventHandler() | Прикрепляет обработчик событий к событию. | CComponent |
| canGetProperty() | Определяет, можно ли прочитать свойство. | CComponent |
| canSetProperty() | Определяет, можно ли установить свойство. | CComponent |
| createUrl() | Создаёт URL-адрес, который может привести к генерации отсортированных данных. | CSort |
| detachBehavior() | Отсоединяет поведение от компонента. | CComponent |
| detachBehaviors() | Отсоединяет все поведения от компонента. | CComponent |
| detachEventHandler() | Отсоединяет существующий обработчик событий. | CComponent |
| disableBehavior() | Отключает присоединённое поведение. | CComponent |
| disableBehaviors() | Отключает все присоединённые поведения к этому компоненту. | CComponent |
| enableBehavior() | Включает присоединённое поведение. | CComponent |
| enableBehaviors() | Включает все присоединённые к этому компоненту поведения. | CComponent |
| evaluateExpression() | Вычисляет PHP-выражение или обратный вызов в контексте этого компонента. | CComponent |
| getDirection() | Возвращает направление сортировки указанного атрибута в текущем запросе. | CSort |
| getDirections() | Возвращает текущую запрошенную информацию о сортировке. | CSort |
| getEventHandlers() | Возвращает список прикреплённых обработчиков событий для события. | CComponent |
| getOrderBy() | Возвращает столбцы сортировки, представленные этим объектом. Это можно поместить в предложение ORDER BY SQL-запроса. | CSort |
| hasEvent() | Определяет, задано ли событие. | CComponent |
| hasEventHandler() | Проверяет, есть ли прикреплённые обработчики для именованного события. | CComponent |
| hasProperty() | Определяет, задано ли свойство. | CComponent |
| link() | Генерирует гиперссылку, по которой можно нажать для сортировки. | CSort |
| raiseEvent() | Вызывает событие. | CComponent |
| resolveAttribute() | Возвращает фактическое определение атрибута, учитывая его имя. | CSort |
| resolveLabel() | Решает метку атрибута для указанного атрибута. | CSort |
Защищенные методы
| Метод | Описание | Определено в |
|---|---|---|
| createLink() | Создаёт гиперссылку на основе заданного метки и URL. | CSort |
| getModel() | Принимает имя класса активной записи и возвращает новый экземпляр модели. | CSort |
Подробное описание свойств
attributes свойство
public array $attributes;
Список атрибутов, которые разрешено сортировать. Например, массив ('user_id', 'create_time') укажет, что сортировать можно только 'user_id' и 'create_time' модели modelClass. По умолчанию это пустой массив, что означает, что сортировать можно все атрибуты в modelClass.
Это свойство также может использоваться для указания сложной сортировки. Для этого можно объявить виртуальный атрибут в виде пары ключ-значение в массиве. Ключ относится к имени виртуального атрибута, который может появиться в запросе сортировки, а значение определяет определение виртуального атрибута.
В простом случае пара ключ-значение может быть такой: 'user'=>'user_id' где 'user' — имя виртуального атрибута, а 'user_id' — означает, что виртуальный атрибут является атрибутом 'user_id' в modelClass.
Более гибкий способ — указать пару ключ-значение как
'user'=>array(
'asc'=>'first_name, last_name',
'desc'=>'first_name DESC, last_name DESC',
'label'=>'Name'
)
где 'user' — имя виртуального атрибута, определяющего полное имя пользователя (составной атрибут, состоящий из имени и фамилии пользователя). В этом случае для определения виртуального атрибута нужно использовать массив с тремя элементами: 'asc', 'desc' и 'label'. Данный подход также можно использовать для объявления виртуальных атрибутов, состоящих из реляционных атрибутов. Например,
'price'=>array(
'asc'=>'item.price',
'desc'=>'item.price DESC',
'label'=>'Item Price'
)
Обратите внимание, что имя атрибута не должно содержать символов '-' или '.' из-за их использования в качестве разделителей.
Начиная с версии 1.1.3, можно использовать дополнительный параметр 'default' в объявлении виртуального атрибута. Этот параметр указывает, следует ли сортировать атрибут по возрастанию или убыванию при нажатии на соответствующую гиперссылку сортировки, если он не отсортирован в данный момент. Допустимые значения параметров включают 'asc' (по умолчанию) и 'desc'. Например,
'price'=>array(
'asc'=>'item.price',
'desc'=>'item.price DESC',
'label'=>'Item Price',
'default'=>'desc',
)
Также, начиная с версии 1.1.3, вы можете включить элемент звёздочку ('*') в это свойство, чтобы все атрибуты модели были доступны для сортировки, помимо виртуальных атрибутов. Например,
'attributes'=>array(
'price'=>array(
'asc'=>'item.price',
'desc'=>'item.price DESC',
'label'=>'Item Price',
'default'=>'desc',
),
'*',
)
Обратите внимание, что когда имя присутствует как в атрибуте модели, так и в виртуальном атрибуте, положение элемента звёздочки в массиве определяет, какой из них имеет приоритет. В частности, если элемент звёздочки является первым элементом в массиве, приоритет имеет атрибут модели; а если он последний — приоритет имеет виртуальный атрибут. defaultOrder свойство
public mixed $defaultOrder;
порядок по умолчанию, который должен применяться к критериям запроса, когда текущий запрос не указывает никакой сортировки. Например, 'name, create_time DESC' или 'UPPER(name)'.
Начиная с версии 1.1.3, вы также можете указать порядок по умолчанию, используя массив. Ключи массива могут быть именами атрибутов или именами виртуальных атрибутов, как объявленные в attributes, а значения массива указывают, должна ли сортировка соответствующих атрибутов быть по убыванию. Например,
'defaultOrder'=>array(
'price'=>CSort::SORT_DESC,
)
`SORT_DESC` и `SORT_ASC` доступны с 1.1.10. В более ранних версиях Yii следует использовать `true` и `false` соответственно. Обратите внимание, что при использовании массива для указания порядка по умолчанию соответствующие атрибуты будут помещены в directions, и это повлияет на то, как отображаются ссылки сортировки (например, рядом с текущей активной ссылкой сортировки может отображаться стрелка).
descTag свойство
public string $descTag;
тег, который появляется в параметре GET и указывает, что атрибут должен быть отсортирован по убыванию. По умолчанию — 'desc'.
directions свойство только для чтения
public array getDirections()
Возвращает текущую запрошенную информацию о сортировке.
modelClass свойство
public string $modelClass;
имя класса модели, атрибуты которой могут быть отсортированы. Класс модели должен быть дочерним классом CActiveRecord.
multiSort свойство
public boolean $multiSort;
указывает, можно ли одновременно применять сортировку к нескольким атрибутам. По умолчанию — false, что означает, что каждый раз данные можно сортировать только по одному атрибуту.
orderBy свойство только для чтения (доступно с версии v1.1.0)
public string getOrderBy(CDbCriteria $criteria=NULL)
Столбцы ORDER BY, представленные этим объектом сортировки. Это можно поместить в предложение ORDER BY SQL-запроса.
params свойство
public array $params;
дополнительные параметры GET (имя=>значение), которые следует использовать при формировании URL сортировки. По умолчанию — null, что означает использование текущих доступных параметров GET.
route свойство
public string $route;
маршрут (идентификатор контроллера и идентификатор действия) для генерации отсортированного содержимого. По умолчанию — пустая строка, что означает использование текущего запрошенного маршрута.
separators свойство
public array $separators;
разделители, используемые в сгенерированном URL. Это должен быть массив, состоящий из двух элементов. Первый элемент определяет символ, разделяющий различные атрибуты, а второй — символ, разделяющий имя атрибута и соответствующее направление сортировки. По умолчанию — массив ('-', '.').
sortVar свойство
public string $sortVar;
имя параметра GET, указывающего, какие атрибуты и в каком направлении сортировать. По умолчанию — 'sort'.
Подробное описание методов
__construct() метод
public void __construct(string $modelClass=NULL) | ||
| $modelClass | строка | имя класса моделей данных, которые необходимо отсортировать. Это должен быть дочерний класс CActiveRecord. |
public function __construct($modelClass=null)
{
$this->modelClass=$modelClass;
}
Конструктор.
applyOrder() метод
public void applyOrder(CDbCriteria $criteria) | ||
| $criteria | CDbCriteria | критерии запроса |
public function applyOrder($criteria)
{
$order=$this->getOrderBy($criteria);
if(!empty($order))
{
if(!empty($criteria->order))
$criteria->order.=', ';
$criteria->order.=$order;
}
}
Изменяет критерии запроса, изменяя свойство CDbCriteria::order. Этот метод будет использовать directions для определения столбцов, которые нужно отсортировать. Они будут включены в предложение ORDER BY. Если у критериев уже есть ненулевое значение CDbCriteria::order, новое значение будет добавлен к нему.
createLink() метод
protected string createLink(string $attribute, string $label, string $url, array $htmlOptions) | ||
| $attribute | строка | имя атрибута, для которого предназначена эта ссылка |
| $label | строка | метка гиперссылки |
| $url | строка | URL |
| $htmlOptions | массив | дополнительные параметры HTML |
| {возвращаемое значение} | строка | сгенерированная гиперссылка |
protected function createLink($attribute,$label,$url,$htmlOptions)
{
return CHtml::link($label,$url,$htmlOptions);
}
Создаёт гиперссылку на основе заданной метки и URL. Вы можете переопределить этот метод, чтобы настроить генерацию ссылки.
createUrl() метод
public string createUrl(CController $controller, array $directions) | ||
| $controller | CController | контроллер, который будет использоваться для создания URL. |
| $directions | массив | направления сортировки, индексированные по именам атрибутов. Направление сортировки может быть либо CSort::SORT_ASC для возрастающей сортировки, либо CSort::SORT_DESC для убывающей сортировки. |
| {возвращаемое значение} | строка | URL для сортировки |
public function createUrl($controller,$directions)
{
$sorts=array();
foreach($directions as $attribute=>$descending)
$sorts[]=$descending ? $attribute.$this->separators[1].$this->descTag : $attribute;
$params=$this->params===null ? $_GET : $this->params;
$params[$this->sortVar]=implode($this->separators[0],$sorts);
return $controller->createUrl($this->route,$params);
}
Создаёт URL, который может привести к генерации отсортированных данных.
getDirection() метод
public mixed getDirection(string $attribute) | ||
| $attribute | строка | имя атрибута |
| {возвращаемое значение} | смешанное | Направление сортировки атрибута. Может быть либо CSort::SORT_ASC для возрастающей сортировки, либо CSort::SORT_DESC для убывающей сортировки. Значение null, если атрибут не нуждается в сортировке. |
public function getDirection($attribute)
{
$this->getDirections();
return isset($this->_directions[$attribute]) ? $this->_directions[$attribute] : null;
}
Возвращает направление сортировки указанного атрибута в текущем запросе.
getDirections() метод
public array getDirections() | ||
| {return} | массив | направления сортировки, индексированные по именам атрибутов. Направление сортировки может быть либо CSort::SORT_ASC для возрастающей сортировки, либо CSort::SORT_DESC для убывающей сортировки. |
public function getDirections()
{
if($this->_directions===null)
{
$this->_directions=array();
if(isset($_GET[$this->sortVar]) && is_string($_GET[$this->sortVar]))
{
$attributes=explode($this->separators[0],$_GET[$this->sortVar]);
foreach($attributes as $attribute)
{
if(($pos=strrpos($attribute,$this->separators[1]))!==false)
{
$descending=substr($attribute,$pos+1)===$this->descTag;
if($descending)
$attribute=substr($attribute,0,$pos);
}
else
$descending=false;
if(($this->resolveAttribute($attribute))!==false)
{
$this->_directions[$attribute]=$descending;
if(!$this->multiSort)
return $this->_directions;
}
}
}
if($this->_directions===array() && is_array($this->defaultOrder))
$this->_directions=$this->defaultOrder;
}
return $this->_directions;
}
Возвращает текущую информацию о сортировке.
getModel() метод (доступен начиная с v1.1.14)
protected CActiveRecord getModel(string $className) | ||
| $className | строка | имя класса активной записи. |
| {return} | CActiveRecord | экземпляр модели активной записи. |
protected function getModel($className)
{
return CActiveRecord::model($className);
}
Возвращает новый экземпляр модели, заданной по имени класса активной записи.
getOrderBy() метод (доступен начиная с v1.1.0)
public string getOrderBy(CDbCriteria $criteria=NULL) | ||
| $criteria | CDbCriteria | критерии запроса. |
| {return} | строка | столбцы сортировки, представленные этим объектом сортировки. Это может быть использовано в части ORDER BY SQL-запроса. |
public function getOrderBy($criteria=null)
{
$directions=$this->getDirections();
if(empty($directions))
return is_string($this->defaultOrder) ? $this->defaultOrder : '';
else
{
if($this->modelClass!==null)
$schema=$this->getModel($this->modelClass)->getDbConnection()->getSchema();
$orders=array();
foreach($directions as $attribute=>$descending)
{
$definition=$this->resolveAttribute($attribute);
if(is_array($definition))
{
if($descending)
$orders[]=isset($definition['desc']) ? (is_array($definition['desc']) ? implode(', ',$definition['desc']) : $definition['desc']) : $attribute.' DESC';
else
$orders[]=isset($definition['asc']) ? (is_array($definition['asc']) ? implode(', ',$definition['asc']) : $definition['asc']) : $attribute;
}
elseif($definition!==false)
{
$attribute=$definition;
if(isset($schema))
{
if(($pos=strpos($attribute,'.'))!==false)
$attribute=$schema->quoteTableName(substr($attribute,0,$pos)).'.'.$schema->quoteColumnName(substr($attribute,$pos+1));
else
$attribute=($criteria===null || $criteria->alias===null ? $this->getModel($this->modelClass)->getTableAlias(true) : $schema->quoteTableName($criteria->alias)).'.'.$schema->quoteColumnName($attribute);
}
$orders[]=$descending?$attribute.' DESC':$attribute;
}
}
return implode(', ',$orders);
}
}
link() метод
public string link(string $attribute, string $label=NULL, array $htmlOptions=array ( )) | ||
| $attribute | строка | имя атрибута. Должно быть реальное имя атрибута, а не псевдоним. Если это атрибут связанного объекта AR, имя должно быть префиксным с именем связи (например, 'author.name', где 'author' - имя связи). |
| $label | строка | метка ссылки. Если null, метка будет определена согласно атрибуту (см. resolveLabel). |
| $htmlOptions | массив | дополнительные атрибуты HTML для тега гиперссылки |
| {return} | строка | сгенерированная гиперссылка |
public function link($attribute,$label=null,$htmlOptions=array())
{
if($label===null)
$label=$this->resolveLabel($attribute);
if(($definition=$this->resolveAttribute($attribute))===false)
return $label;
$directions=$this->getDirections();
if(isset($directions[$attribute]))
{
$class=$directions[$attribute] ? 'desc' : 'asc';
if(isset($htmlOptions['class']))
$htmlOptions['class'].=' '.$class;
else
$htmlOptions['class']=$class;
$descending=!$directions[$attribute];
unset($directions[$attribute]);
}
elseif(is_array($definition) && isset($definition['default']))
$descending=$definition['default']==='desc';
else
$descending=false;
if($this->multiSort)
$directions=array_merge(array($attribute=>$descending),$directions);
else
$directions=array($attribute=>$descending);
$url=$this->createUrl(Yii::app()->getController(),$directions);
return $this->createLink($attribute,$label,$url,$htmlOptions);
}
Генерирует гиперссылку, нажатие на которую вызывает сортировку.
resolveAttribute() метод
public mixed resolveAttribute(string $attribute) | ||
| $attribute | строка | имя атрибута, по которому пользователь запрашивает сортировку |
| {return} | смешанный тип | имя атрибута или определение виртуального атрибута. Ложь, если атрибут нельзя отсортировать. |
public function resolveAttribute($attribute)
{
if($this->attributes!==array())
$attributes=$this->attributes;
elseif($this->modelClass!==null)
$attributes=$this->getModel($this->modelClass)->attributeNames();
else
return false;
foreach($attributes as $name=>$definition)
{
if(is_string($name))
{
if($name===$attribute)
return $definition;
}
elseif($definition==='*')
{
if($this->modelClass!==null && $this->getModel($this->modelClass)->hasAttribute($attribute))
return $attribute;
}
elseif($definition===$attribute)
return $attribute;
}
return false;
}
Возвращает реальное определение атрибута по его имени.
Разрешение основано на attributes и CActiveRecord::attributeNames.
- Когда attributes является пустым массивом, если имя относится к атрибуту modelClass, то имя возвращается обратно.
- Когда attributes не пуст, если имя относится к атрибуту, объявленному в attributes, то возвращается соответствующее определение виртуального атрибута. Начиная с версии 1.1.3, если attributes содержит элемент '*' (звездочку), имя также будет использоваться для соответствия всем атрибутам модели.
- Во всех остальных случаях возвращается ложь, что означает, что имя не относится к валидному атрибуту.
resolveLabel() метод
public string resolveLabel(string $attribute) | ||
| $attribute | строка | имя атрибута. |
| {return} | строка | метка атрибута |
public function resolveLabel($attribute)
{
$definition=$this->resolveAttribute($attribute);
if(is_array($definition))
{
if(isset($definition['label']))
return $definition['label'];
}
elseif(is_string($definition))
$attribute=$definition;
if($this->modelClass!==null)
return $this->getModel($this->modelClass)->getAttributeLabel($attribute);
else
return $attribute;
}
Определяет метку атрибута для указанного атрибута. Это вызовет CActiveRecord::getAttributeLabel, чтобы определить используемую метку. Если атрибут относится к виртуальному атрибуту, объявленному в attributes, то вместо этого будет возвращена метка из attributes.
© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CSort