Merge pull request #809 from cebe/autoconfig-sorting

Gridview and DataProviders: Autoconfig sorting

framework/yii/data/ActiveDataProvider.php

@@ -9,6 +9,8 @@ namespace yii\data;
 
 use Yii;
 use yii\base\InvalidConfigException;
+use yii\base\InvalidParamException;
+use yii\base\Model;
 use yii\db\Query;
 use yii\db\ActiveQuery;
 use yii\db\Connection;
@@ -214,4 +216,25 @@ class ActiveDataProvider extends DataProvider
 		$this->_totalCount = null;
 		$this->_keys = null;
 	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function setSort($value)
+	{
+		parent::setSort($value);
+		if (($sort = $this->getSort()) !== false && empty($sort->attributes) &&
+			$this->query instanceof ActiveQuery) {
+
+			/** @var Model $model */
+			$model = new $this->query->modelClass;
+			foreach($model->attributes() as $attribute) {
+				$sort->attributes[$attribute] = array(
+					'asc' => array($attribute => Sort::ASC),
+					'desc' => array($attribute => Sort::DESC),
+					'label' => $model->getAttributeLabel($attribute),
+				);
+			}
+		}
+	}
 }

framework/yii/data/Sort.php

@@ -125,9 +125,10 @@ class Sort extends Object
 	 *   if it is not currently sorted (the default value is ascending order).
 	 * - The "label" element specifies what label should be used when calling [[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, desc and label.
+	 * to configure every attribute. Each attribute must include these elements: asc and desc.
 	 */
 	public $attributes = array();
 	/**
@@ -195,13 +196,11 @@ class Sort extends Object
 				$attributes[$attribute] = array(
 					'asc' => array($attribute => self::ASC),
 					'desc' => array($attribute => self::DESC),
-					'label' => Inflector::camel2words($attribute),
 				);
-			} elseif (!isset($attribute['asc'], $attribute['desc'], $attribute['label'])) {
+			} elseif (!isset($attribute['asc'], $attribute['desc'])) {
 				$attributes[$name] = array_merge(array(
 					'asc' => array($name => self::ASC),
 					'desc' => array($name => self::DESC),
-					'label' => Inflector::camel2words($name),
 				), $attribute);
 			} else {
 				$attributes[$name] = $attribute;
@@ -287,7 +286,11 @@ class Sort extends Object
 	 * Based on the sort direction, the CSS class of the generated hyperlink will be appended
 	 * with "asc" or "desc".
 	 * @param string $attribute the attribute name by which the data should be sorted by.
-	 * @param array $options additional HTML attributes for the hyperlink tag
+	 * @param array $options additional HTML attributes for the hyperlink tag.
+	 * There is one special attribute `label` which will be used as the label of the hyperlink.
+	 * If this is not set, the label defined in [[attributes]] will be used.
+	 * If no label is defined, [[yii\helpers\Inflector::camel2words()]] will be called to get a label.
+	 * Note that it will not be HTML-encoded.
 	 * @return string the generated hyperlink
 	 * @throws InvalidConfigException if the attribute is unknown
 	 */
@@ -304,7 +307,18 @@ class Sort extends Object
 
 		$url = $this->createUrl($attribute);
 		$options['data-sort'] = $this->createSortVar($attribute);
-		return Html::a($this->attributes[$attribute]['label'], $url, $options);
+
+		if (isset($options['label'])) {
+			$label = $options['label'];
+			unset($options['label']);
+		} else {
+			if (isset($this->attributes[$attribute]['label'])) {
+				$label = $this->attributes[$attribute]['label'];
+			} else {
+				$label = Inflector::camel2words($attribute);
+			}
+		}
+		return Html::a($label, $url, $options);
 	}
 
 	/**

framework/yii/grid/DataColumn.php

@@ -28,6 +28,14 @@ class DataColumn extends Column
 	 */
 	public $attribute;
 	/**
+	 * @var string label to be displayed in the [[header|header cell]] and also to be used as the sorting
+	 * link label when sorting is enabled for this column.
+	 * If it is not set and the models provided by the GridViews data provider are instances
+	 * of [[yii\db\ActiveRecord]], the label will be determined using [[yii\db\ActiveRecord::getAttributeLabel()]].
+	 * Otherwise [[yii\helpers\Inflector::camel2words()]] will be used to get a label.
+	 */
+	public $label;
+	/**
 	 * @var \Closure an anonymous function that returns the value to be displayed for every data model.
 	 * If this is not set, `$model[$attribute]` will be used to obtain the value.
 	 */
@@ -46,6 +54,11 @@ class DataColumn extends Column
 	 */
 	public $enableSorting = true;
 	/**
+	 * @var array the HTML attributes for the link tag in the header cell
+	 * generated by [[Sort::link]] when sorting is enabled for this column.
+	 */
+	public $sortLinkOptions = array();
+	/**
 	 * @var string|array|boolean the HTML code representing a filter input (e.g. a text field, a dropdown list)
 	 * that is used for this data column. This property is effective only when [[GridView::filterModel]] is set.
 	 *
@@ -59,25 +72,36 @@ class DataColumn extends Column
 
 	protected function renderHeaderCellContent()
 	{
-		if ($this->attribute !== null && $this->header === null) {
-			$provider = $this->grid->dataProvider;
-			if ($this->enableSorting && ($sort = $provider->getSort()) !== false && $sort->hasAttribute($this->attribute)) {
-				return $sort->link($this->attribute);
+		if ($this->header !== null || $this->label === null && $this->attribute === null) {
+			return parent::renderHeaderCellContent();
 		}
+
+		$provider = $this->grid->dataProvider;
+
+		if ($this->label === null) {
+			if ($provider instanceof ActiveDataProvider && $provider->query instanceof ActiveQuery) {
+				/** @var Model $model */
+				$model = new $provider->query->modelClass;
+				$label = $model->getAttributeLabel($this->attribute);
+			} else {
 				$models = $provider->getModels();
 				if (($model = reset($models)) instanceof Model) {
 					/** @var Model $model */
-				return $model->getAttributeLabel($this->attribute);
-			} elseif ($provider instanceof ActiveDataProvider) {
-				if ($provider->query instanceof ActiveQuery) {
-					/** @var Model $model */
-					$model = new $provider->query->modelClass;
-					return $model->getAttributeLabel($this->attribute);
+					$label = $model->getAttributeLabel($this->attribute);
+				} else {
+					$label = Inflector::camel2words($this->attribute);
 				}
 			}
-			return Inflector::camel2words($this->attribute);
 		} else {
-			return parent::renderHeaderCellContent();
+			$label = $this->label;
+		}
+
+		if ($this->attribute !== null && $this->enableSorting &&
+			($sort = $provider->getSort()) !== false && $sort->hasAttribute($this->attribute)) {
+
+			return $sort->link($this->attribute, array_merge($this->sortLinkOptions, array('label' => Html::encode($label))));
+		} else {
+			return Html::encode($label);
 		}
 	}
 

framework/yii/grid/GridView.php

@@ -108,7 +108,7 @@ class GridView extends ListViewBase
 	 *         'class' => DataColumn::className(),
 	 *         'attribute' => 'name',
 	 *         'format' => 'text',
-	 *         'header' => 'Name',
+	 *         'label' => 'Name',
 	 *     ),
 	 *     array(
 	 *         'class' => CheckboxColumn::className(),
@@ -119,9 +119,9 @@ class GridView extends ListViewBase
 	 * If a column is of class [[DataColumn]], the "class" element can be omitted.
 	 *
 	 * As a shortcut format, a string may be used to specify the configuration of a data column
-	 * which only contains "attribute", "format", and/or "header" options: `"attribute:format:header"`.
+	 * which only contains "attribute", "format", and/or "label" options: `"attribute:format:label"`.
 	 * For example, the above "name" column can also be specified as: `"name:text:Name"`.
-	 * Both "format" and "header" are optional. They will take default values if absent.
+	 * Both "format" and "label" are optional. They will take default values if absent.
 	 */
 	public $columns = array();
 	/**
@@ -372,7 +372,7 @@ class GridView extends ListViewBase
 	}
 
 	/**
-	 * Creates a [[DataColumn]] object based on a string in the format of "attribute:format:header".
+	 * Creates a [[DataColumn]] object based on a string in the format of "attribute:format:label".
 	 * @param string $text the column specification string
 	 * @return DataColumn the column instance
 	 * @throws InvalidConfigException if the column specification is invalid
@@ -380,14 +380,14 @@ class GridView extends ListViewBase
 	protected function createDataColumn($text)
 	{
 		if (!preg_match('/^([\w\.]+)(:(\w*))?(:(.*))?$/', $text, $matches)) {
-			throw new InvalidConfigException('The column must be specified in the format of "attribute", "attribute:format" or "attribute:format:header');
+			throw new InvalidConfigException('The column must be specified in the format of "attribute", "attribute:format" or "attribute:format:label');
 		}
 		return Yii::createObject(array(
 			'class' => $this->dataColumnClass ?: DataColumn::className(),
 			'grid' => $this,
 			'attribute' => $matches[1],
 			'format' => isset($matches[3]) ? $matches[3] : 'text',
-			'header' => isset($matches[5]) ? $matches[5] : null,
+			'label' => isset($matches[5]) ? $matches[5] : null,
 		));
 	}