Spec-Zone.ru › Yii 1.1

CSort

Пакет system.web
Наследование класс CSort » CComponent
Исходный код framework/web/CSort.php
CSort представляет информацию, относящуюся к сортировке.

Когда данные необходимо отсортировать по одному или нескольким атрибутам, мы можем использовать 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.
Исходный код: framework/web/CSort.php#203 (показать)
public function __construct($modelClass=null)
{
    
$this->modelClass=$modelClass;
}

Конструктор.

applyOrder() метод

public void applyOrder(CDbCriteria $criteria)
$criteria CDbCriteria критерии запроса
Исходный код: framework/web/CSort.php#215 (показать)
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
{возвращаемое значение} строка сгенерированная гиперссылка
Исходный код: framework/web/CSort.php#468 (показать)
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 для сортировки
Исходный код: framework/web/CSort.php#395 (показать)
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, если атрибут не нуждается в сортировке.
Исходный код: framework/web/CSort.php#381 (показать)
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 для убывающей сортировки.
Исходный код: framework/web/CSort.php#341 (показать)
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 экземпляр модели активной записи.
Исходный код: framework/web/CSort.php#454 (показать)
protected function getModel($className)
{
    return 
CActiveRecord::model($className);
}

Возвращает новый экземпляр модели, заданной по имени класса активной записи.

getOrderBy() метод (доступен начиная с v1.1.0)

public string getOrderBy(CDbCriteria $criteria=NULL)
$criteria CDbCriteria критерии запроса.
{return} строка столбцы сортировки, представленные этим объектом сортировки. Это может быть использовано в части ORDER BY SQL-запроса.
Исходный код: framework/web/CSort.php#232 (показать)
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} строка сгенерированная гиперссылка
Исходный код: framework/web/CSort.php#279 (показать)
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} смешанный тип имя атрибута или определение виртуального атрибута. Ложь, если атрибут нельзя отсортировать.
Исходный код: framework/web/CSort.php#420 (показать)
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} строка метка атрибута
Исходный код: framework/web/CSort.php#319 (показать)
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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API