PHP Class yii\data\Sort

When data needs to be sorted according to one or several attributes, we can use Sort to represent the sorting information and generate appropriate hyperlinks that can lead to sort actions. A typical usage example is as follows, ~~~ function actionIndex() { $sort = new Sort([ 'attributes' => [ 'age', 'name' => [ 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC], 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC], 'default' => SORT_DESC, 'label' => 'Name', ], ], ]); $models = Article::find() ->where(['status' => 1]) ->orderBy($sort->orders) ->all(); return $this->render('index', [ 'models' => $models, 'sort' => $sort, ]); } ~~~ View: ~~~ display links leading to sort actions echo $sort->link('name') . ' | ' . $sort->link('age'); foreach ($models as $model) { display $model here } ~~~ In the above, we declare two [[attributes]] that support sorting: name and age. We pass the sort information to the Article query so that the query results are sorted by the orders specified by the Sort object. In the view, we show two hyperlinks that can lead to pages with the data sorted by the corresponding attributes.
Since: 2.0
Author: Qiang Xue ([email protected])
Inheritance: extends yii\base\Object
Exibir arquivo Open project: yiisoft/yii2 Class Usage Examples

Public Properties

Property Type Description
$attributes list of attributes that are allowed to be sorted. Its syntax can be described using the following example: php [ 'age', 'name' => [ 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC], 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC], 'default' => SORT_DESC, 'label' => 'Name', ], ] In the above, two attributes are declared: age and name. The age attribute is a simple attribute which is equivalent to the following: php 'age' => [ 'asc' => ['age' => SORT_ASC], 'desc' => ['age' => SORT_DESC], 'default' => SORT_ASC, 'label' => Inflector::camel2words('age'), ] The name attribute is a composite attribute: - The name key represents the attribute name which will appear in the URLs leading to sort actions. - The asc and desc elements specify how to sort by the attribute in ascending and descending orders, respectively. Their values represent the actual columns and the directions by which the data should be sorted by. - The default element specifies by which direction the attribute should be sorted if it is not currently sorted (the default value is ascending order). - The label element specifies what label should be used when calling Sort::link to create a sort link. If not set, [[Inflector::camel2words()]] will be called to get a label. Note that it will not be HTML-encoded. Note that if the Sort object is already created, you can only use the full format to configure every attribute. Each attribute must include these elements: asc and desc.
$defaultOrder the order that should be used when the current request does not specify any order. The array keys are attribute names and the array values are the corresponding sort directions. For example, php [ 'name' => SORT_ASC, 'created_at' => SORT_DESC, ]
$enableMultiSort 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.
$params parameters (name => value) that should be used to obtain the current sort directions and to create new sort URLs. If not set, $_GET will be used instead. In order to add hash to all links use array_merge($_GET, ['#' => 'my-hash']). The array element indexed by [[sortParam]] is considered to be the current sort directions. If the element does not exist, the [[defaultOrder|default order]] will be used.
$route the route of the controller action for displaying the sorted contents. If not set, it means using the currently requested route.
$separator the character used to separate different attributes that need to be sorted by.
$sortParam the name of the parameter that specifies which attributes to be sorted in which direction. Defaults to sort.
$urlManager the URL manager used for creating sort URLs. If not set, the urlManager application component will be used.

Public Methods

Method Description
createSortParam ( string $attribute ) : string Creates the sort variable for the specified attribute.
createUrl ( string $attribute, boolean $absolute = false ) : string Creates a URL for sorting the data by the specified attribute.
getAttributeOrder ( string $attribute ) : boolean | null Returns the sort direction of the specified attribute in the current request.
getAttributeOrders ( boolean $recalculate = false ) : array Returns the currently requested sort information.
getOrders ( boolean $recalculate = false ) : array Returns the columns and their corresponding sort directions.
hasAttribute ( string $name ) : boolean Returns a value indicating whether the sort definition supports sorting by the named attribute.
init ( ) Normalizes the [[attributes]] property.
link ( string $attribute, array $options = [] ) : string Generates a hyperlink that links to the sort action to sort by the specified attribute.
setAttributeOrders ( array | null $attributeOrders, boolean $validate = true ) Sets up the currently sort information.

Method Details

createSortParam() public method

The newly created sort variable can be used to create a URL that will lead to sorting by the specified attribute.
public createSortParam ( string $attribute ) : string
$attribute string the attribute name
return string the value of the sort variable

createUrl() public method

This method will consider the current sorting status given by [[attributeOrders]]. For example, if the current page already sorts the data by the specified attribute in ascending order, then the URL created will lead to a page that sorts the data by the specified attribute in descending order.
See also: attributeOrders
See also: params
public createUrl ( string $attribute, boolean $absolute = false ) : string
$attribute string the attribute name
$absolute boolean whether to create an absolute URL. Defaults to `false`.
return string the URL for sorting. False if the attribute is invalid.

getAttributeOrder() public method

Returns the sort direction of the specified attribute in the current request.
public getAttributeOrder ( string $attribute ) : boolean | null
$attribute string the attribute name
return boolean | null Sort direction of the attribute. Can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order. Null is returned if the attribute is invalid or does not need to be sorted.

getAttributeOrders() public method

Returns the currently requested sort information.
public getAttributeOrders ( boolean $recalculate = false ) : array
$recalculate boolean whether to recalculate the sort directions
return array sort directions indexed by attribute names. Sort direction can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order.

getOrders() public method

Returns the columns and their corresponding sort directions.
public getOrders ( boolean $recalculate = false ) : array
$recalculate boolean whether to recalculate the sort directions
return array the columns (keys) and their corresponding sort directions (values). This can be passed to [[\yii\db\Query::orderBy()]] to construct a DB query.

hasAttribute() public method

Returns a value indicating whether the sort definition supports sorting by the named attribute.
public hasAttribute ( string $name ) : boolean
$name string the attribute name
return boolean whether the sort definition supports sorting by the named attribute.

init() public method

Normalizes the [[attributes]] property.
public init ( )

setAttributeOrders() public method

Sets up the currently sort information.
Since: 2.0.10
public setAttributeOrders ( array | null $attributeOrders, boolean $validate = true )
$attributeOrders array | null sort directions indexed by attribute names. Sort direction can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order.
$validate boolean whether to validate given attribute orders against [[attributes]] and [[enableMultiSort]]. If validation is enabled incorrect entries will be removed.

Property Details

$attributes public_oe property

list of attributes that are allowed to be sorted. Its syntax can be described using the following example: php [ 'age', 'name' => [ 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC], 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC], 'default' => SORT_DESC, 'label' => 'Name', ], ] In the above, two attributes are declared: age and name. The age attribute is a simple attribute which is equivalent to the following: php 'age' => [ 'asc' => ['age' => SORT_ASC], 'desc' => ['age' => SORT_DESC], 'default' => SORT_ASC, 'label' => Inflector::camel2words('age'), ] The name attribute is a composite attribute: - The name key represents the attribute name which will appear in the URLs leading to sort actions. - The asc and desc elements specify how to sort by the attribute in ascending and descending orders, respectively. Their values represent the actual columns and the directions by which the data should be sorted by. - The default element specifies by which direction the attribute should be sorted if it is not currently sorted (the default value is ascending order). - The label element specifies what label should be used when calling Sort::link to create a sort link. If not set, [[Inflector::camel2words()]] will be called to get a label. Note that it will not be HTML-encoded. Note that if the Sort object is already created, you can only use the full format to configure every attribute. Each attribute must include these elements: asc and desc.
public $attributes

$defaultOrder public_oe property

the order that should be used when the current request does not specify any order. The array keys are attribute names and the array values are the corresponding sort directions. For example, php [ 'name' => SORT_ASC, 'created_at' => SORT_DESC, ]
See also: attributeOrders
public $defaultOrder

$enableMultiSort public_oe property

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.
public $enableMultiSort

$params public_oe property

parameters (name => value) that should be used to obtain the current sort directions and to create new sort URLs. If not set, $_GET will be used instead. In order to add hash to all links use array_merge($_GET, ['#' => 'my-hash']). The array element indexed by [[sortParam]] is considered to be the current sort directions. If the element does not exist, the [[defaultOrder|default order]] will be used.
See also: sortParam
See also: defaultOrder
public $params

$route public_oe property

the route of the controller action for displaying the sorted contents. If not set, it means using the currently requested route.
public $route

$separator public_oe property

the character used to separate different attributes that need to be sorted by.
public $separator

$sortParam public_oe property

the name of the parameter that specifies which attributes to be sorted in which direction. Defaults to sort.
See also: params
public $sortParam

$urlManager public_oe property

the URL manager used for creating sort URLs. If not set, the urlManager application component will be used.
public $urlManager