Yii предоставляет набор виджетов, которые могут быть использованы для отображения данных. В то время как виджет DetailView может быть использован для отображения данных по одной записи, то виджеты ListView и GridView могут быть использованы для показа данных в виде списка или таблицы с возможностью сортировки, фильтрации и разбивки данных постранично.
Виджет DetailView отображает детали по данным для одной model.
Этот виджет лучше использовать для отображения данных модели в обычном формате(т.е. каждый атрибут модели будет представлен в виде строки в таблице). Модель может быть либо объектом класса yii\base\Model или его наследником, таких как active record , либо ассоциативным массивом.
DetailView использует свойство $attributes для определений, какие атрибуты модели должны быть показаны и в каком формате. Обратитесь к разделу Форматирование данных за возможными настройками форматирования.
Обычное использование DetailView сводится к следующему коду:
echo DetailView::widget([
'model' => $model,
'attributes' => [
'title', // title свойство (обычный текст)
'description:html', // description свойство, как HTML
[ // name свойство зависимой модели owner
'label' => 'Owner',
'value' => $model->owner->name,
'contentOptions' => ['class' => 'bg-red'], // настройка HTML атрибутов для тега, соответсвующего value
'captionOptions' => ['tooltip' => 'Tooltip'], // настройка HTML атрибутов для тега, соответсвующего label
],
'created_at:datetime', // дата создания в формате datetime
],
]);
Виджет ListView использует для отображения информации провайдера данных. Каждая модель отображается, используя определённый вид. Поскольку провайдер включает в себя разбивку на страницы, сортировку и фильтрацию, то его использование удобно для отображения информации конечному пользователю и создания интерфейса управления данными.
Обычное использование сводится к следующему коду:
use yii\widgets\ListView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
]);
_post
файл вид, который может содержать следующее:
<?php
use yii\helpers\Html;
use yii\helpers\HtmlPurifier;
?>
<div class="post">
<h2><?= Html::encode($model->title) ?></h2>
<?= HtmlPurifier::process($model->text) ?>
</div>
В вышеописанном коде текущая модель доступна как $model
. Кроме этого доступны дополнительные переменные:
$key
: mixed, значение ключа в соответствии с данными.$index
: integer, индекс элемента данных в массиве элементов, возвращенных поставщику данных, который начинается с 0.$widget
: ListView, это экземпляр виджета.Если необходимо послать дополнительные данные в каждый вид, то можно использовать свойство $viewParams как ключ-значение, например:
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
'viewParams' => [
'fullView' => true,
'context' => 'main-page',
// ...
],
]);
Они также станут доступны в виде в качестве переменных.
Таблица данных или GridView - это один из сверхмощных Yii виджетов. Он может быть полезен, если необходимо быстро создать административный раздел системы. GridView использует данные, как провайдер данных и отображает каждую строку используя columns для предоставления данных в таблице.
Каждая строка из таблицы представлена данными из одиночной записи и колонка, как правило, представляет собой атрибут записи (некоторые столбцы могут соответствовать сложным выражениям атрибутов или статическому тексту).
Минимальный код, который необходим для использования GridView:
use yii\grid\GridView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo GridView::widget([
'dataProvider' => $dataProvider,
]);
В вышеприведённом коде сначала создаётся провайдер данных и затем используется GridView для отображения атрибутов для каждого элемента из провайдера данных. Отображенная таблица оснащена функционалом сортировки и разбивки на страницы из коробки.
Колонки таблицы настраиваются с помощью определённых yii\grid\Column классов, которые настраиваются в свойстве columns виджета GridView. В зависимости от типа колонки и их настроек, данные отображаются по разному. По умолчанию это класс yii\grid\DataColumn, который представляет атрибут модели с возможностью сортировки и фильтрации по нему.
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'],
// Обычные поля определенные данными содержащимися в $dataProvider.
// Будут использованы данные из полей модели.
'id',
'username',
// Более сложный пример.
[
'class' => 'yii\grid\DataColumn', // может быть опущено, поскольку является значением по умолчанию
'value' => function ($data) {
return $data->name; // $data['name'] для массивов, например, при использовании SqlDataProvider.
},
],
],
]);
Учтите, что если columns не сконфигурирована, то Yii попытается отобразить все возможные колонки из провайдера данных.
Колонки таблицы могут быть настроены, используя различные классы колонок:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\SerialColumn', // <-- тут
// тут можно настроить дополнительные свойства
],
В дополнение к классам колонок от Yii, вы можете самостоятельно создать свой собственный класс.
Каждый класс колонки наследуется от yii\grid\Column, так что есть некоторые общие параметры, которые можно установить при настройке колонок.
content позволяет передавать действительный обратный вызов, который будет возвращать данные для строки.Формат следующий:
function ($model, $key, $index, $column) {
return 'a string';
}
Вы можете задать различные параметры контейнера HTML через массивы:
Data column используется для отображения и сортировки данных. По умолчанию этот тип используется для всех колонок.
Основная настройка этой колонки - это свойство format. Значение этого свойства посылается
в методы formatter
компонента, который по умолчанию Formatter
echo GridView::widget([
'columns' => [
[
'attribute' => 'name',
'format' => 'text'
],
[
'attribute' => 'birthday',
'format' => ['date', 'php:Y-m-d']
],
'created_at:datetime', // короткий вид записи формата
[
'label' => 'Education',
'attribute' => 'education',
'filter' => ['0' => 'Elementary', '1' => 'Secondary', '2' => 'Higher'],
'filterInputOptions' => ['prompt' => 'All educations', 'class' => 'form-control', 'id' => null]
],
],
]);
В вышеприведённом коде text
соответствует yii\i18n\Formatter::asText(). В качестве первого аргумента для этого
метода будет передаваться значение колонки. Во второй колонки описано date
, которая соответствует yii\i18n\Formatter::asDate().
В качестве первого аргумента, опять же, будет передаваться значение колонки, в то время как второй аргумент будет
'php:Y-m-d'.
Доступный список форматов смотрите в разделе Форматирование данных.
Для конфигурации колонок данных также доступен короткий вид записи, который описан в API документации для колонок.
Используйте filter и filterInputOptions для настройки HTML кода фильтра.
По умолчанию заголовки колонок генерируются используя yii\data\Sort::link(). Это можно изменить через свойство yii\grid\Column::$header. Для изменения заголовка нужно задать yii\grid\DataColumn::$label, как в примере выше. По умолчанию текст будет взят из модели данных. Подробное описание ищите в yii\grid\DataColumn::getHeaderCellLabel().
ActionColumn отображает кнопки действия, такие как изменение или удаление для каждой строки.
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\ActionColumn',
// вы можете настроить дополнительные свойства здесь.
],
Доступные свойства для конфигурации:
{view}
будет
заменён результатом из функции, определённой в buttons['view']
. Если такая функция не может быть найдена, то маркер
заменяется на пустую строку. По умолчанию шаблон имеет вид {view} {update} {delete}
.buttons массив из функций для отображения кнопок. Ключи массива представлены как имена кнопок (как описывалось выше), а значения представлены в качестве анонимных функций, которые выводят кнопки. Замыкания должны использоваться в следующем виде:
function ($url, $model, $key) {
// возвращаем HTML код для кнопки
}
где, $url
- это URL, который будет повешен как ссылка на кнопку, $model
- это объект модели для текущей строки и
$key
- это ключ для модели из провайдера данных.
`
php
function ($model, $key, $index) {
return $model->status === 'editable'; // отображать ли кнопку
}
`
Или вы можете передать булево значение:
`
php
[
'update' => \Yii::$app->user->can('update')
]
`
Checkbox column отображает колонку как флаг (сheckbox).
Для добавления CheckboxColumn в виджет GridView, необходимо добавить его в columns:
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
// ...
[
'class' => 'yii\grid\CheckboxColumn',
// вы можете настроить дополнительные свойства здесь.
],
],
Пользователи могут нажимать на флаги для выделения строк в таблице. Отмеченные строки могут быть обработаны с помощью JavaScript кода:
var keys = $('#grid').yiiGridView('getSelectedRows');
// массив ключей для отмеченных строк
Serial column выводит в строках номера начиная с 1
и увеличивая их по мере вывода строк.
Использование очень простое :
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'], // <-- тут
// ...
Примечание: Эта секция под разработкой
Для фильтрации данных в GridView необходима модель, которая описывает форму для фильтрации, внося
условия в запрос поиска для провайдера данных.
Общепринятой практикой считается использование active records и создание для неё класса модели для
поиска, которая содержит необходимую функциональность(может быть сгенерирована через Gii). Класс модели
для поиска должен описывать правила валидации и реализовать метод search()
, который будет возвращать провайдер данных.
Для поиска возможных Post
моделей, можно создать PostSearch
наподобие следующего примера:
<?php
namespace app\models;
use Yii;
use yii\base\Model;
use yii\data\ActiveDataProvider;
class PostSearch extends Post
{
public function rules()
{
// только поля определенные в rules() будут доступны для поиска
return [
[['id'], 'integer'],
[['title', 'creation_date'], 'safe'],
];
}
public function scenarios()
{
// bypass scenarios() implementation in the parent class
return Model::scenarios();
}
public function search($params)
{
$query = Post::find();
$dataProvider = new ActiveDataProvider([
'query' => $query,
]);
// загружаем данные формы поиска и производим валидацию
if (!($this->load($params) && $this->validate())) {
return $dataProvider;
}
// изменяем запрос добавляя в его фильтрацию
$query->andFilterWhere(['id' => $this->id]);
$query->andFilterWhere(['like', 'title', $this->title])
->andFilterWhere(['like', 'creation_date', $this->creation_date]);
return $dataProvider;
}
}
Теперь можно использовать этот метод в контроллере, чтобы получить провайдер данных для GridView:
$searchModel = new PostSearch();
$dataProvider = $searchModel->search(Yii::$app->request->get());
return $this->render('myview', [
'dataProvider' => $dataProvider,
'searchModel' => $searchModel,
]);
и в виде присвоить их $dataProvider
и $searchModel
в виджете GridView:
echo GridView::widget([
'dataProvider' => $dataProvider,
'filterModel' => $searchModel,
'columns' => [
// ...
],
]);
Фильтров в шапке GridView достаточно для большинства задач, но добавление отдельной формы фильтрации не представляет особой сложности. Она бывает полезна в случае необходимости фильтрации по полям, которые не отображаются в GridView или особых условий фильтрации, например по диапазону дат.
Создайте частичное представление _search.php
со следующим содержимым:
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
/* @var $this yii\web\View */
/* @var $model app\models\PostSearch */
/* @var $form yii\widgets\ActiveForm */
?>
<div class="post-search">
<?php $form = ActiveForm::begin([
'action' => ['index'],
'method' => 'get',
]); ?>
<?= $form->field($model, 'title') ?>
<?= $form->field($model, 'creation_date') ?>
<div class="form-group">
<?= Html::submitButton('Искатьатьclass' => 'btn btn-primary']) ?>
<?= Html::resetButton('Сброситьситьтььclass' => 'btn btn-default']) ?>
</div>
<?php ActiveForm::end(); ?>
</div>
и добавьте его отображение в index.php
таким образом:
<?= $this->render('_search', ['model' => $searchModel]) ?>
Примечание: если вы используете Gii для генерации CRUD кода, отдельная форма фильтрации (
_search.php
) генерируется по умолчанию, но закомментирована в представленииindex.php
. Вам остается только раскомментировать эту строку и форма готова к использованию!
Для фильтра по диапазону дат мы можем добавить дополнительные атрибуты createdFrom
и createdTo
в поисковую модель
(их нет в соответствующей таблице модели):
class PostSearch extends Post
{
/**
* @var string
*/
public $createdFrom;
/**
* @var string
*/
public $createdTo;
}
Расширим условия запроса в методе search()
:
$query->andFilterWhere(['>=', 'creation_date', $this->createdFrom])
->andFilterWhere(['<=', 'creation_date', $this->createdTo]);
И добавим соответствующие поля в форму фильтрации:
<?= $form->field($model, 'creationFrom') ?>
<?= $form->field($model, 'creationTo') ?>
Бывают случаи, когда необходимо в GridView вывести в колонке значения из зависимой модели для active records, например
имя автора новости, вместо его id
. Для этого необходимо задать yii\grid\GridView::$columns как author.name
, если
же модель Post
содержит зависимость с именем author
и имя автора хранится в атрибуте name
. GridView отобразит
имя автора, но вот сортировка и фильтрации по этому полю будет не доступна. Необходимо дополнить некоторый функционал в
PostSearch
модель, которая была упомянута в предыдущем разделе.
Для включения сортировки по зависимой колонки необходимо присоединить зависимую таблицу и добавить правило в компонент Sort для провайдера данных.:
$query = Post::find();
$dataProvider = new ActiveDataProvider([
'query' => $query,
]);
// присоединяем зависимость `author` которая является связью с таблицей `users`
// и устанавливаем алиас таблицы в значение `author`
$query->joinWith(['author' => function($query) { $query->from(['author' => 'users']); }]);
// добавляем сортировку по колонке из зависимости
$dataProvider->sort->attributes['author.name'] = [
'asc' => ['author.name' => SORT_ASC],
'desc' => ['author.name' => SORT_DESC],
];
// ...
Фильтрации также необходим вызов joinWith, как описано выше. Также необходимо определить для поиска столбец в атрибутах и правилах:
public function attributes()
{
// делаем поле зависимости доступным для поиска
return array_merge(parent::attributes(), ['author.name']);
}
public function rules()
{
return [
[['id'], 'integer'],
[['title', 'creation_date', 'author.name'], 'safe'],
];
}
В search()
просто добавляется другое условие фильтрации:
$query->andFilterWhere(['LIKE', 'author.name', $this->getAttribute('author.name')]);
Информация: В коде, что выше, используется такая же строка, как и имя зависимости и псевдонима таблицы. Однако, когда ваш псевдоним и имя связи различаются, вы должны обратить внимание, где вы используете псевдоним, а где имя связи. Простым правилом для этого является использование псевдонима в каждом месте, которое используется для построения запроса к базе данных, и имя связи во всех других определениях, таких как
attributes()
,rules()
и т.д.Например, если вы используете псевдоним
au
для связи с таблицей автора, то joinWith будет выглядеть так:
$query->joinWith(['author' => function($query) { $query->from(['au' => 'users']); }]);
Это также возможно вызвать как
$query->joinWith(['author']);
, когда псевдоним определен в определении отношения.Псевдоним должен быть использован в состоянии фильтра, но имя атрибута остается неизменным:
$query->andFilterWhere(['LIKE', 'au.name', $this->getAttribute('author.name')]);
То же самое верно и для определения сортировки:
$dataProvider->sort->attributes['author.name'] = [ 'asc' => ['au.name' => SORT_ASC], 'desc' => ['au.name' => SORT_DESC], ];
Кроме того, при определении defaultOrder для сортировки необходимо использовать имя зависимости вместо псевдонима:
$dataProvider->sort->defaultOrder = ['author.name' => SORT_ASC];
Информация: Для подробной информации по
joinWith
и запросам, выполняемым в фоновом режиме, обратитесь к active record документации.
Существует и другой подход, который быстре и более удобен - SQL виды. Например, если необходимо показать таблицу из пользователей и их профилей, то можно выбрать такой путь:
CREATE OR REPLACE VIEW vw_user_info AS
SELECT user.*, user_profile.lastname, user_profile.firstname
FROM user, user_profile
WHERE user.id = user_profile.user_id
Теперь вам необходимо создать ActiveRecord, через который будут доступны данные из вида выше:
namespace app\models\views\grid;
use yii\db\ActiveRecord;
class UserView extends ActiveRecord
{
/**
* {@inheritdoc}
*/
public static function tableName()
{
return 'vw_user_info';
}
public static function primaryKey()
{
return ['id'];
}
/**
* {@inheritdoc}
*/
public function rules()
{
return [
// здесь определяйте ваши правила
];
}
/**
* {@inheritdoc}
*/
public function attributeLabels()
{
return [
// здесь определяйте ваши метки атрибутов
];
}
}
После этого вы можете использовать UserView в модели поиска, без каких-либо дополнительных условий по сортировке и фильтрации. Все атрибуты будут работать из коробки. Но такая реализация имеет свои плюсы и минусы:
isActive
, isDeleted
, необходимо продублировать в классе, который описывает вид.Вы можете использовать больше одной GridView на одной странице. Для этого нужно внести некоторые дополнительные настройки для того, чтобы они друг другу не мешали. При использовании нескольких экземпляров GridView вы должны настроить различные имена параметров для сортировки и ссылки для разбиения на страницы так, чтобы каждый GridView имел свою индивидуальную сортировку и разбиение на страницы. Сделать это возможно через настройку sortParam и pageParam свойств провайдеров данных sort и pagination
Допустим мы хотим список моделей Post
и User
, для которых мы уже подготовили провайдеры данных $userProvider
и
$postProvider
, тогда код будет выглядеть следующим образом:
use yii\grid\GridView;
$userProvider->pagination->pageParam = 'user-page';
$userProvider->sort->sortParam = 'user-sort';
$postProvider->pagination->pageParam = 'post-page';
$postProvider->sort->sortParam = 'post-sort';
echo '<h1>Users</h1>';
echo GridView::widget([
'dataProvider' => $userProvider,
]);
echo '<h1>Posts</h1>';
echo GridView::widget([
'dataProvider' => $postProvider,
]);
Примечание: Секция находится в стадии разработки
TBD
Found a typo or you think this page needs improvement?
Edit it on github !
Signup or Login in order to comment.