CGridView. Свойства и методы

Виджет CGridView отображает список элементов данных в виде таблицы.
Каждая строка таблицы представляет данные одного элемента, а столбец обычно представляет атрибут элемента (некоторые столбцы могут отображать результат сложного выражения или статический текст).
CGridView поддерживает сортировку и пагинацию элементов данных.
Сортировка и пагинация могут работать как в режиме AJAX-запросов так и в режиме обычных запросов страниц. Преимущество использования CGridView в том, что если в браузере пользователя отключен JavaScript, сортировка и пагинация автоматически используют режим обычных запросов страниц и функционируют так, как ожидается.
CGridView должен использоваться совместно с IDataProvider поставщиком данных, желательно, с CActiveDataProvider.
Минимальный код, требуемый для использования CGridView:
$dataProvider=new CActiveDataProvider('Post');

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
));
В коде выше сначала создается поставщик данных для ActiveRecord-класса Post. Затем используется виджет CGridView для отображения каждого атрибута в каждом экземпляре Post. Отображаемая таблица снабжается сортировкой и пагинацией.
Для выборочного отображения атрибутов в различных форматах можно настроить свойство CGridView::columns. Например, можно для отображения определить только атрибуты title и create_time, а атрибут create_time должен быть отформатирован в виде строки времени. Также можно отображать атрибуты связанных объектов с использованием точечного синтаксиса как показано ниже:
$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
    'columns'=>array(
        'title',          // отображает атрибут 'title'
        'category.name',  // отображает атрибут 'name' связанного объекта 'category'
        'content:html',   // отображает атрибут 'content' в виде очищенного HTML-кода
        array(            // отображает атрибут 'create_time' с использованием PHP-выражения
            'name'=>'create_time',
            'value'=>'date("M j, Y", $data->create_time)',
        ),
        array(            // отображает атрибут 'author.username' с использованием PHP-выражения
            'name'=>'authorName',
            'value'=>'$data->author->username',
        ),
        array(            // отображает столбец с кнопками просмотра (view), обновления (update) и удаления (delete)
            'class'=>'CButtonColumn',
        ),
    ),
));

Свойства


afterAjaxUpdate

@var string javascript-функция, вызываемая после успешного получения результата AJAX-запроса. Вид функции - function(id, data), где 'id' - идентификатор виджета таблицы, а 'data' - полученные в результате ajax-запроса данные

ajaxUpdate

@var mixed идентификатор контейнера, содержимое которого может быть изменено при помощи AJAX-запроса. По умолчанию - null - обновляется контейнер данного экземпляра виджета. Если установлено в значение false, то сортировка и пагинация будут проходить в виде обычных запросов страниц вместо AJAX-запросов. Если сортировка и пагинация должны запускать обновление содержимого нескольких контейнеров в AJAX-виде, идентификаторы данных контейнеров должны быть перечислены в данном свойстве (разделенные запятыми)

ajaxUpdateError

@var string javascript-функция, вызываемая в случае возникновения ошибки при AJAX-запросе обновления. Функция имеет вид function(xhr, textStatus, errorThrown, errorMessage), где
  • xhr - объект XMLHttpRequest; 
  • textStatus - строка, описывающая тип возникшей ошибки. Возможные значения (кроме null): "timeout", "error", "notmodified" и "parsererror"; 
  • errorThrown - опциональный объект исключения, в случае его возникновения; 
  • errorMessage - сообщение виджета CGridView об ошибке по умолчанию, производная от объектов xhr и errorThrown. Полезно, если хочется просто отобразить ошибку по-другому. Виджет CGridView по умолчанию ошибку при помощи javascript.alert().
Примечание: данный обработчик не вызывается для JSONP-запросов, т.к. они не используют XMLHttpRequest. Например (добавление вызова в виджет CGridView):
     ...
     'ajaxUpdateError'=>'function(xhr,ts,et,err){ $("#myerrordiv").text(err); }',
     ...

ajaxUrl (с v1.1.8)

@var mixed URL-адрес, на который должны посылаться AJAX-запросы. Для данного свойства будет вызван метод CHtml::normalizeUrl(). Если не установлено, то для AJAX-запросов будет использоваться URL-адрес текущей страницы

ajaxVar

@var string имя GET-переменной, показывающей, что запрос является AJAX-запросом, вызванным данным виджетом. По умолчанию - 'ajax'. Имеет значение только если свойство ajaxUpdate не равно false

baseScriptUrl

@var string базовый URL-адрес для всех ресурсов виджета (например, javascript, CSS-файлы, изображения). По умолчанию - null, т.е., используются встроенные ресурсы (которые публикуются как веб-ресурсы)

beforeAjaxUpdate

@var string javascript function-функция, вызываемая перед выполнением AJAX-запроса на обновление. Вид функции - function(id,options), где 'id' - идентификатор виджета, а 'options' - опции AJAX-запроса (см. документацию по API для jQuery.ajax)

blankDisplay (с v1.1.7)

@var string текст, отображаемый в пустой ячейки таблицы. Свойство НЕ проходит HTML-кодирование при генерации. По умолчанию - неразрывный пробел. Отличается от свойства nullDisplay, тем, что nullDisplay используется для генерации нулевых значений классом CDataColumn

columns

@var array конфигурация столбцов таблицы. Каждый элемент массива представляет конфигурацию одного отдельного столбца таблицы и может быть строкой или массивом.
Если столбец определяется строкой, то эта строка должна иметь формат "имя:тип:заголовок", где "тип" и "заголовок" - опциональны. В этом случае будет создан экземпляр класса CDataColumn, свойства CDataColumn::name, CDataColumn::type и CDataColumn::header которого будут определены согласно заданной строке.
Если столбец определяется массивом, он будет использоваться для создания экземпляра столбца таблицы. При этом элемент 'class' массива определяет класс столбца (по умолчанию - CDataColumn). В настоящий момент фреймворк предоставляет следующие классы столбцов: CDataColumn, CLinkColumn, CButtonColumn и CCheckBoxColumn

cssFile

@var string URL-адрес CSS-файла, используемого данным виджетом. По умолчанию - null, т.е., используется встроенный CSS-файл. Если установлено в значение false, необходимо самостоятельно явно включить требуемый CSS-файл в страницу

filter (с v1.1.1)

@var CModel экземпляр модели, содержащей введенные пользователем фильтрующие данные.
Если данное свойство установлено, таблица активирует фильтрацию для данного столбца. Каждый столбец данных по умолчанию отображает наверху таблицы текстовое поле, которое пользователь может заполнить фильтрующими данными. Примечание: для того, чтобы показать поле ввода для фильтрации, столбец должен иметь установленное свойство CDataColumn::name или свойство CDataColumn::filter в виде HTML-кода поля ввода.
Фильтрация отключена, когда данное свойство не установлено (null)

filterCssClass (с v1.1.1)

@var string имя CSS-класса для элемента строки таблицы, содержащим все поля ввода фильтров. По умолчанию - 'filters'
Смотрите также filter

filterPosition (с v1.1.1)

@var string отображать ли фильтры таблицы. Допустимые значения:        
  • header: фильтры отображаются наверху каждого столбца в ячейке-заголовке; 
  • body: фильтры отображаются сразу за ячейкой-заголовком; 
  • footer: фильтры отображаются ниже ячейки-футера.
Смотрите также filter

formatter

@var CFormatter экземпляр форматтера. По умолчанию - компонент приложения 'format'

hasFooter read-only

@var boolean должна ли таблица генерировать подошву (футер). Возвращает true, если в любом элементе свойства columns есть значение CGridColumn::hasFooter, равное true

hideHeader (с v1.1.1)

@var boolean скрывать ли ячейки-заголовки таблицы. Если установлено в значение true, ячейки-заголовки не будут генерироваться, т.е., таблицу нельзя будет отсортировать, т.к. ссылки для сортировки находятся в заголовке. По умолчанию - false

loadingCssClass (с v1.1.1)

@var string имя CSS-класса, присваемого элементу контейнера виджета при обновлении содержимого виджета AJAX-запросом. По умолчанию - 'grid-view-loading'

nullDisplay

@var string текст, отображаемый в ячейке данных, если значение равно null. Данное свойство НЕ будет проходить HTML-кодирование при генерации. По умолчанию - HTML-пробел (nbsp)

rowCssClass

@var array имена CSS-классов строк основной части таблицы. Если передано несколько имен CSS-классов, они будут присвоены строкам последовательно и циклически повторяясь. Свойство игнорируется, если установлено свойство rowCssClassExpression. По умолчанию - array('odd', 'even')
Смотрите также rowCssClassExpression

rowCssClassExpression

@var string PHP-выражение, вычисляемое для каждой строки основной части таблицы и результат которого используется в качестве имени CSS-класса для данной строки. В данном выражении доступны переменные: $row - номер строки (начиная с нуля), $data - модель данных, ассоциированных со строкой и $this - объект виджета
Смотрите также rowCssClass

selectableRows

@var integer количество доступных для выделения строк таблицы.
Если равно 0, то ни одна строка не может быть выбрана;
если 1 - только 1 строка может быть выбрана;
если 2 и больше - могут быть выбраны несколько строк.
Выбранная строка будет иметь CSS-класс с именем 'selected'. Также можно вызвать JavaScript-функцию $.fn.yiiGridView.getSelection(containerID) для получения значений ключей выбранных строк

selectionChanged

@var string javascript-функция, вызываемая после изменения списка выбранных строк. Вид функции - function(id), где 'id' - идентификатор виджета таблицы. В данной функции можно использовать функцию $.fn.yiiGridView.getSelection(id) для получения значений ключей выбранных строк
Смотрите также selectableRows

showTableOnEmpty

@var boolean отображать ли таблицу в случае, если данных нет. По умолчанию - true. Значение свойства emptyText отображается при отсутствии реальных данных

updateSelector (с v1.1.7)

@var string селектор jQuery для HTML-элементов, которые могут запускать AJAX-обновление при клике на них. Если не установлено, AJAX-обновление будут вызывать только ссылки пагинации и сортировки

Методы


createDataColumn()

createDataColumn(string $text)
$textстрока спецификации столбца
Создает CDataColumn, основываясь на строке спецификации столбца

getFormatter()

возвращает CFormatter экземпляр форматтера. По умолчанию - компонент приложения 'format'

getHasFooter()

должна ли таблица генерировать подошву (футер). Возвращает true, если в любом элементе свойства columns есть значение CGridColumn::hasFooter, равное true

init()

Инициализирует таблицу.
Данный метод инициализирует значениями требуемые свойства и инстанцирует объекты columns

initColumns()

Создает объекты столбцов и инициализирует их

registerClientScript()

Регистрирует требуемые клиентские скрипты

renderFilter()

Генерирует фильтр

renderItems()

Генерирует элементы данных для таблицы

renderTableBody()

Генерирует основную часть таблицы (тело)

renderTableFooter()

Генерирует футер таблицы

renderTableHeader()

Генерирует заголовок таблицы

renderTableRow()

renderTableRow(integer $row)
$rowномер строки (начиная с нуля)
Генерирует строку основной части таблицы

setFormatter()

setFormatter(CFormatter $value)
$valueэкземпляр форматтера

Комментарии

  1. Анонимный21 мая 2014 г., 12:51

    Норм бложик. Только фон отвлекает сильно =(

    ОтветитьУдалить
    Ответы
    1. Простите за такую эстетическую непривлекательность :))

      Удалить
  2. Анонимный2 июня 2015 г., 20:27

    Да, очень полезный блог)

    ОтветитьУдалить

Отправить комментарий

Популярные сообщения