ソート ¶

複数のデータ行を表示する場合、エンドユーザーが指定した列に従ってデータをソートする必要があることがよくあります。Yii は、ソートスキーマに関する情報を表すために yii\data\Sort オブジェクトを使用します。特に、

• attributes は、データのソートに使用できる属性を指定します。属性は、モデル属性のように単純なものにすることができます。また、複数のモデル属性や DB 列を組み合わせることで複合的なものにすることもできます。詳細については、以下で説明します。
• attributeOrders は、各属性に対して現在リクエストされている並び順の方向を提供します。
• orders は、低レベルの列の観点から並び順の方向を提供します。

yii\data\Sort を使用するには、まずソート可能な属性を宣言します。次に、attributeOrders または orders から現在リクエストされている順序情報を取得し、それらを使用してデータクエリをカスタマイズします。例えば、

use yii\data\Sort;

$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',
        ],
    ],
]);

$articles = Article::find()
    ->where(['status' => 1])
    ->orderBy($sort->orders)
    ->all();

上記の例では、Sort オブジェクトに対して age および name の 2 つの属性が宣言されています。

age 属性は、Article アクティブレコードクラスの age 属性に対応する単純な属性です。次の宣言と同等です。

'age' => [
    'asc' => ['age' => SORT_ASC],
    'desc' => ['age' => SORT_DESC],
    'default' => SORT_ASC,
    'label' => Inflector::camel2words('age'),
]

name 属性は、Article の first_name および last_name によって定義される複合属性です。これは、次の配列構造を使用して宣言されます。

• asc および desc 要素は、それぞれ昇順および降順で属性をソートする方法を指定します。それらの値は、データがソートされる実際の列と方向を表します。単純な順序付けまたは複合的な順序付けを示すために、1つまたは複数の列を指定できます。
• default 要素は、最初にリクエストされたときに属性をソートする方向を指定します。デフォルトでは昇順になります。つまり、以前にソートされておらず、この属性でソートするようにリクエストした場合、データはこの属性で昇順にソートされます。
• label 要素は、yii\data\Sort::link() を呼び出してソートリンクを作成するときに使用するラベルを指定します。設定されていない場合、yii\helpers\Inflector::camel2words() が呼び出され、属性名からラベルが生成されます。HTML エンコードされないことに注意してください。

情報: orders の値をデータベースクエリに直接フィードして、ORDER BY 句を作成できます。attributeOrders は、一部の属性が複合属性で、データベースクエリで認識されない可能性があるため、使用しないでください。

yii\data\Sort::link() を呼び出して、エンドユーザーがクリックして指定された属性でデータをソートするようにリクエストできるハイパーリンクを生成できます。yii\data\Sort::createUrl() を呼び出して、ソート可能な URL を作成することもできます。例えば、

// specifies the route that the URL to be created should use
// If you do not specify this, the currently requested route will be used
$sort->route = 'article/index';

// display links leading to sort by name and age, respectively
echo $sort->link('name') . ' | ' . $sort->link('age');

// displays: /index.php?r=article%2Findex&sort=age
echo $sort->createUrl('age');

yii\data\Sort は、sort クエリパラメータを調べて、どの属性がソートのために要求されているかを判断します。クエリパラメータが存在しない場合、yii\data\Sort::$defaultOrder を介してデフォルトの順序を指定できます。また、sortParam プロパティを設定することで、クエリパラメータの名前をカスタマイズすることもできます。