CSort
| 包 | system.web |
|---|---|
| 继承 | class CSort » CComponent |
| 可用自 | 1.0.1 |
| 版本 | $Id$ |
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 so that it can cause the query results to be sorted according to the specified attributes.
CSort is primarily used for active record involving a single DB table. In order to use it with relational active record, special care needs to be taken. We use an example to illustrate this use case. Assume 'Post' is the main active record class, and 'author' is one of its related attributes. We would like to sort by post's title as well as its author's name. First, we need to define aliases for the two attributes by setting the attributes property:
array(
'title',
'author.name'=>'authorName',
)
We also need to modify the 'author' relation in 'Post' class and explicitly specify the 'alias' option with value 'author':
'author'=>array(self::BELONGS_TO, 'User', 'alias'=>'author')
Finally, we can use the following code to generate hyperlinks:
echo CSort::link('title');
echo CSort::link('author.name');
公共属性
| 属性 | 类型 | 描述 | 被定义在 |
|---|---|---|---|
| attributes | array | list of attributes that are allowed to be sorted. | CSort |
| defaultOrder | string | the default order that should be applied to the query criteria when the current request does not specify any sort. | CSort |
| directions | array | Returns the currently requested sort information. | CSort |
| modelClass | string | the class name of data models that need to be sorted. | CSort |
| multiSort | boolean | whether the sorting can be applied to multiple attributes simultaneously. | 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 |
公共方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| __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 |
| getDirections() | Returns the currently requested sort information. | CSort |
| getEventHandlers() | Returns the list of attached event handlers for an event. | CComponent |
| 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 |
| link() | Generates a hyperlink that can be clicked to cause sorting. | CSort |
| raiseEvent() | Raises an event. | CComponent |
| resolveLabel() | Resolves the attribute label based on label definition in the AR class. | CSort |
| validateAttribute() | Validates an attribute that is requested to be sorted. | CSort |
属性详情
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' can be sorted. Defaults to null, meaning all attributes of the modelClass can be sorted. This property can also be used to specify attribute aliases that should appear in the 'sort' GET parameter in place of the original attribute names. In this case, the aliases should be array values while the attribute names should be the corresponding array keys. Do not use '-' and '.' in the aliases as they are used as separators.
the default order that should be applied to the query criteria when the current request does not specify any sort.
Returns the currently requested sort information.
the class name of data models that need to be sorted. This should be a child class of CActiveRecord.
whether the sorting can be applied to multiple attributes simultaneously. Defaults to true. If false, each time the data can only be sorted by one attribute.
the additional GET parameters (name=>value) that should be used when generating sort URLs. Defaults to null, meaning using the currently available GET parameters.
the route (controller ID and action ID) for generating the sorted contents. Defaults to empty string, meaning using the currently requested route.
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('-','.').
the name of the GET parameter that specifies which attributes to be sorted in which direction. Defaults to 'sort'.
方法详情
|
public void __construct(string $modelClass)
| ||
| $modelClass | string | the class name of data models that need to be sorted. This should be a child class of CActiveRecord. |
Constructor.
|
public void applyOrder(CDbCriteria $criteria)
| ||
| $criteria | CDbCriteria | the query criteria |
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 |
Creates a hyperlink based on the given label and URL. You may override this method to customize the link generation.
|
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 is true if the corresponding attribute should be sorted in descending order. |
| {return} | string | the URL for sorting |
Creates a URL that can lead to generating sorted data.
|
public array getDirections()
| ||
| {return} | array | sort directions indexed by attribute names. The sort direction is true if the corresponding attribute should be sorted in descending order. |
Returns the currently requested sort information.
|
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 |
Generates a hyperlink that can be clicked to cause sorting.
|
public string resolveLabel(string $attribute)
| ||
| $attribute | string | the attribute name. |
| {return} | string | the attribute label |
Resolves the attribute label based on label definition in the AR class. This will invoke CActiveRecord::getAttributeLabel to determine what label to use.
|
public string validateAttribute(string $attribute)
| ||
| $attribute | string | the attribute name (could be an alias) that the user requests to sort on |
| {return} | string | the real attribute name. False if the attribute cannot be sorted |
Validates an attribute that is requested to be sorted. The validation is based on attributes and CActiveRecord::attributeNames. False will be returned if the attribute is not allowed to be sorted. If the attribute is aliased via attributes, the original attribute name will be returned.