CSort

Package system.web
Inheritance class CSort » CComponent
Source Code framework/web/CSort.php
CSort represents information relevant to sorting.

When data needs to be sorted according to one or several attributes, we can use CSort to represent the sorting information and generate appropriate hyperlinks that can lead to sort actions.

CSort is designed to be used together with CActiveRecord. When creating a CSort instance, you need to specify modelClass. You can use CSort to generate hyperlinks by calling link. You can also use CSort to modify a CDbCriteria instance by calling applyOrder so that it can cause the query results to be sorted according to the specified attributes.

In order to prevent SQL injection attacks, CSort ensures that only valid model attributes can be sorted. This is determined based on modelClass and attributes. When attributes is not set, all attributes belonging to modelClass can be sorted. When attributes is set, only those attributes declared in the property can be sorted.

By configuring attributes, one can perform more complex sorts that may consist of things like compound attributes (e.g. sort based on the combination of first name and last name of users).

The property attributes should be an array of key-value pairs, where the keys represent the attribute names, while the values represent the virtual attribute definitions. For more details, please check the documentation about attributes.

Public Properties

Property Type Description Defined By
attributes array list of attributes that are allowed to be sorted. CSort
defaultOrder mixed the default order that should be applied to the query criteria when the current request does not specify any sort. CSort
descTag string the tag appeared in the GET parameter that indicates the attribute should be sorted in descending order. CSort
directions array Returns the currently requested sort information. CSort
modelClass string the name of the model class whose attributes can be sorted. CSort
multiSort boolean whether the sorting can be applied to multiple attributes simultaneously. CSort
orderBy string the order-by columns represented by this sort object. CSort
params array the additional GET parameters (name=>value) that should be used when generating sort URLs. CSort
route string the route (controller ID and action ID) for generating the sorted contents. CSort
separators array separators used in the generated URL. CSort
sortVar string the name of the GET parameter that specifies which attributes to be sorted in which direction. CSort

Public Methods

Method Description Defined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CSort
__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
applyOrder() Modifies the query criteria by changing its CDbCriteria::order property. CSort
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
createUrl() Creates a URL that can lead to generating sorted data. CSort
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
getDirection() Returns the sort direction of the specified attribute in the current request. CSort
getDirections() Returns the currently requested sort information. CSort
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getOrderBy() Returns the order-by columns represented by this sort object. This can be put in the ORDER BY clause of a SQL statement. CSort
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
resolveAttribute() Returns the real definition of an attribute given its name. CSort
resolveLabel() Resolves the attribute label for the specified attribute. CSort

Protected Methods

Method Description Defined By
getModel() Given active record class name returns new model instance. CSort

Property Details

attributes property 

public array $attributes;

list of attributes that are allowed to be sorted. For example, array('user_id','create_time') would specify that only 'user_id' and 'create_time' of the model modelClass can be sorted. By default, this property is an empty array, which means all attributes in modelClass are allowed to be sorted.

This property can also be used to specify complex sorting. To do so, a virtual attribute can be declared in terms of a key-value pair in the array. The key refers to the name of the virtual attribute that may appear in the sort request, while the value specifies the definition of the virtual attribute.

In the simple case, a key-value pair can be like 'user'=>'user_id' where 'user' is the name of the virtual attribute while 'user_id' means the virtual attribute is the 'user_id' attribute in the modelClass.

A more flexible way is to specify the key-value pair as 

'user'=>array(
    'asc'=>'first_name, last_name',
    'desc'=>'first_name DESC, last_name DESC',
    'label'=>'Name'
)
where 'user' is the name of the virtual attribute that specifies the full name of user (a compound attribute consisting of first name and last name of user). In this case, we have to use an array to define the virtual attribute with three elements: 'asc', 'desc' and 'label'.

The above approach can also be used to declare virtual attributes that consist of relational attributes. For example, 
'price'=>array(
    'asc'=>'item.price',
    'desc'=>'item.price DESC',
    'label'=>'Item Price'
)


Note, the attribute name should not contain '-' or '.' characters because they are used as separators.

Starting from version 1.1.3, an additional option named 'default' can be used in the virtual attribute declaration. This option specifies whether an attribute should be sorted in ascending or descending order upon user clicking the corresponding sort hyperlink if it is not currently sorted. The valid option values include 'asc' (default) and 'desc'. For example, 
'price'=>array(
    'asc'=>'item.price',
    'desc'=>'item.price DESC',
    'label'=>'Item Price',
    'default'=>'desc',
)


Also starting from version 1.1.3, you can include a star ('*') element in this property so that all model attributes are available for sorting, in addition to those virtual attributes. For example, 
'attributes'=>array(
    'price'=>array(
        'asc'=>'item.price',
        'desc'=>'item.price DESC',
        'label'=>'Item Price',
        'default'=>'desc',
    ),
    '*',
)
Note that when a name appears as both a model attribute and a virtual attribute, the position of the star element in the array determines which one takes precedence. In particular, if the star element is the first element in the array, the model attribute takes precedence; and if the star element is the last one, the virtual attribute takes precedence.

defaultOrder property 

public mixed $defaultOrder;

the default order that should be applied to the query criteria when the current request does not specify any sort. For example, 'name, create_time DESC' or 'UPPER(name)'.

Starting from version 1.1.3, you can also specify the default order using an array. The array keys could be attribute names or virtual attribute names as declared in attributes, and the array values indicate whether the sorting of the corresponding attributes should be in descending order. For example, 

'defaultOrder'=>array(
    'price'=>CSort::SORT_DESC,
)
`SORT_DESC` and `SORT_ASC` are available since 1.1.10. In earlier Yii versions you should use `true` and `false` respectively.

Please note when using array to specify the default order, the corresponding attributes will be put into directions and thus affect how the sort links are rendered (e.g. an arrow may be displayed next to the currently active sort link).

descTag property 

public string $descTag;

the tag appeared in the GET parameter that indicates the attribute should be sorted in descending order. Defaults to 'desc'.

directions property read-only 

public array getDirections()

Returns the currently requested sort information.

modelClass property 

public string $modelClass;

the name of the model class whose attributes can be sorted. The model class must be a child class of CActiveRecord.

multiSort property 

public boolean $multiSort;

whether the sorting can be applied to multiple attributes simultaneously. Defaults to false, which means each time the data can only be sorted by one attribute.

orderBy property read-only (available since v1.1.0) 

public string getOrderBy(CDbCriteria $criteria=NULL)

the order-by columns represented by this sort object. This can be put in the ORDER BY clause of a SQL statement.

params property 

public array $params;

the additional GET parameters (name=>value) that should be used when generating sort URLs. Defaults to null, meaning using the currently available GET parameters.

route property 

public string $route;

the route (controller ID and action ID) for generating the sorted contents. Defaults to empty string, meaning using the currently requested route.

separators property 

public array $separators;

separators used in the generated URL. This must be an array consisting of two elements. The first element specifies the character separating different attributes, while the second element specifies the character separating attribute name and the corresponding sort direction. Defaults to array('-','.').

sortVar property 

public string $sortVar;

the name of the GET parameter that specifies which attributes to be sorted in which direction. Defaults to 'sort'.

Method Details

__construct() method 

public void __construct(string $modelClass=NULL)
$modelClass string the class name of data models that need to be sorted. This should be a child class of CActiveRecord.
Source Code: framework/web/CSort.php#203 (show) 
public function __construct($modelClass=null)
{
    $this->modelClass=$modelClass;
}

Constructor.

applyOrder() method 

public void applyOrder(CDbCriteria $criteria)
$criteria CDbCriteria the query criteria
Source Code: framework/web/CSort.php#215 (show) 
public function applyOrder($criteria)
{
    $order=$this->getOrderBy($criteria);
    if(!empty($order))
    {
        if(!empty($criteria->order))
            $criteria->order.=', ';
        $criteria->order.=$order;
    }
}

Modifies the query criteria by changing its CDbCriteria::order property. This method will use directions to determine which columns need to be sorted. They will be put in the ORDER BY clause. If the criteria already has non-empty CDbCriteria::order value, the new value will be appended to it.

protected string createLink(string $attribute, string $label, string $url, array $htmlOptions)
$attribute string the name of the attribute that this link is for
$label string the label of the hyperlink
$url string the URL
$htmlOptions array additional HTML options
{return} string the generated hyperlink
Source Code: framework/web/CSort.php#468 (show) 
protected function createLink($attribute,$label,$url,$htmlOptions)
{
    return CHtml::link($label,$url,$htmlOptions);
}

Creates a hyperlink based on the given label and URL. You may override this method to customize the link generation.

createUrl() method 

public string createUrl(CController $controller, array $directions)
$controller CController the controller that will be used to create the URL.
$directions array the sort directions indexed by attribute names. The sort direction can be either CSort::SORT_ASC for ascending order or CSort::SORT_DESC for descending order.
{return} string the URL for sorting
Source Code: framework/web/CSort.php#395 (show) 
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);
}

Creates a URL that can lead to generating sorted data.

getDirection() method 

public mixed getDirection(string $attribute)
$attribute string the attribute name
{return} mixed Sort direction of the attribute. Can be either CSort::SORT_ASC for ascending order or CSort::SORT_DESC for descending order. Value is null if the attribute doesn't need to be sorted.
Source Code: framework/web/CSort.php#381 (show) 
public function getDirection($attribute)
{
    $this->getDirections();
    return isset($this->_directions[$attribute]) ? $this->_directions[$attribute] : null;
}

Returns the sort direction of the specified attribute in the current request.

getDirections() method 

public array getDirections()
{return} array sort directions indexed by attribute names. Sort direction can be either CSort::SORT_ASC for ascending order or CSort::SORT_DESC for descending order.
Source Code: framework/web/CSort.php#341 (show) 
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;
}

Returns the currently requested sort information.

getModel() method (available since v1.1.14) 

protected CActiveRecord getModel(string $className)
$className string active record class name.
{return} CActiveRecord active record model instance.
Source Code: framework/web/CSort.php#454 (show) 
protected function getModel($className)
{
    return CActiveRecord::model($className);
}

Given active record class name returns new model instance.

getOrderBy() method (available since v1.1.0) 

public string getOrderBy(CDbCriteria $criteria=NULL)
$criteria CDbCriteria the query criteria
{return} string the order-by columns represented by this sort object. This can be put in the ORDER BY clause of a SQL statement.
Source Code: framework/web/CSort.php#232 (show) 
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);
    }
}
public string link(string $attribute, string $label=NULL, array $htmlOptions=array ( ))
$attribute string the attribute name. This must be the actual attribute name, not alias. If it is an attribute of a related AR object, the name should be prefixed with the relation name (e.g. 'author.name', where 'author' is the relation name).
$label string the link label. If null, the label will be determined according to the attribute (see resolveLabel).
$htmlOptions array additional HTML attributes for the hyperlink tag
{return} string the generated hyperlink
Source Code: framework/web/CSort.php#279 (show) 
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);
}

Generates a hyperlink that can be clicked to cause sorting.

resolveAttribute() method 

public mixed resolveAttribute(string $attribute)
$attribute string the attribute name that the user requests to sort on
{return} mixed the attribute name or the virtual attribute definition. False if the attribute cannot be sorted.
Source Code: framework/web/CSort.php#420 (show) 
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;
}

Returns the real definition of an attribute given its name.

The resolution is based on attributes and CActiveRecord::attributeNames.

  • When attributes is an empty array, if the name refers to an attribute of modelClass, then the name is returned back.
  • When attributes is not empty, if the name refers to an attribute declared in attributes, then the corresponding virtual attribute definition is returned. Starting from version 1.1.3, if attributes contains a star ('*') element, the name will also be used to match against all model attributes.
  • In all other cases, false is returned, meaning the name does not refer to a valid attribute.

resolveLabel() method 

public string resolveLabel(string $attribute)
$attribute string the attribute name.
{return} string the attribute label
Source Code: framework/web/CSort.php#319 (show) 
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;
}

Resolves the attribute label for the specified attribute. This will invoke CActiveRecord::getAttributeLabel to determine what label to use. If the attribute refers to a virtual attribute declared in attributes, then the label given in the attributes will be returned instead.

© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CSort