CGridView

$dataProvider=new CActiveDataProvider('Post');

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
));

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
    'columns'=>array(
        'title',          // display the 'title' attribute
        'category.name',  // display the 'name' attribute of the 'category' relation
        'content:html',   // display the 'content' attribute as purified HTML
        array(            // display 'create_time' using an expression
            'name'=>'create_time',
            'value'=>'date("M j, Y", $data->create_time)',
        ),
        array(            // display 'author.username' using an expression
            'name'=>'authorName',
            'value'=>'$data->author->username',
        ),
        array(            // display a column with "view", "update" and "delete" buttons
            'class'=>'CButtonColumn',
        ),
    ),
));

Подробное описание свойств

afterAjaxUpdate свойство

public string $afterAjaxUpdate;

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

ajaxType свойство (доступно с версии v1.1.14)

public string $ajaxType;

тип ('GET' или 'POST') запросов AJAX. Если не задано, используется 'GET'. Можно установить 'POST', если вы фильтруете по многим полям одновременно и у вас проблемы с длиной строки GET запроса. Обратите внимание, что в режиме POST прямые ссылки и функция enableHistory могут работать некорректно!

ajaxUpdate свойство

public mixed $ajaxUpdate;

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

ajaxUpdateError свойство

public string $ajaxUpdateError;

функция javascript, которая будет вызвана в случае ошибки AJAX обновления.

Подпись функции: function(xhr, textStatus, errorThrown, errorMessage)

• xhr — объект XMLHttpRequest.
• textStatus — строка, описывающая тип произошедшей ошибки. Возможные значения (кроме null) — "timeout", "error", "notmodified" и "parsererror"
• errorThrown — необъект исключения, если оно произошло.
• errorMessage — стандартное сообщение об ошибке CGridView, полученное из xhr и errorThrown. Полезно, если вы хотите отобразить эту ошибку иначе. CGridView по умолчанию отображает эту ошибку с помощью javascript.alert()

 ...
 'ajaxUpdateError'=>'function(xhr,ts,et,err,id){ $("#"+id).text(err); }',
 ...

ajaxUrl свойство (доступно с версии v1.1.8)

public mixed $ajaxUrl;

URL для запросов AJAX. К этому свойству будет применена функция CHtml::normalizeUrl(). Если не задано, для запросов AJAX будет использоваться текущий URL страницы.

ajaxVar свойство

public string $ajaxVar;

имя переменной GET, которая указывает, что запрос является запросом AJAX, инициированным этим виджетом. По умолчанию 'ajax'. Действительно только когда ajaxUpdate не равно false.

baseScriptUrl свойство

public string $baseScriptUrl;

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

beforeAjaxUpdate свойство

public string $beforeAjaxUpdate;

функция javascript, которая будет вызвана перед выполнением AJAX обновления. Подпись функции: function(id,options) , где 'id' относится к идентификатору таблицы, 'options' к параметрам AJAX запроса (см. руководство по jQuery.ajax).

blankDisplay свойство (доступно с версии v1.1.7)

public string $blankDisplay;

текст, который будет отображаться в пустой ячейке таблицы. Это свойство НЕ будет кодироваться в HTML при рендеринге. По умолчанию HTML пустая строка. Это отличается от nullDisplay, так как nullDisplay используется только CDataColumn для рендеринга значений null.

columns свойство

public array $columns;

конфигурация колонок таблицы. Каждый элемент массива представляет конфигурацию одной колонки, которая может быть строкой или массивом.

Если колонка задана как строка, она должна быть в формате "name:type:header", где "type" и "header" — необязательны. В этом случае будет создан экземпляр CDataColumn, у которого CDataColumn::name, CDataColumn::type и CDataColumn::header будут инициализированы соответственно.

Если колонка задана как массив, она будет использоваться для создания экземпляра колонки, где элемент 'class' указывает имя класса колонки (по умолчанию CDataColumn, если отсутствует). В настоящее время предоставляются следующие официальные классы колонок: CDataColumn, CLinkColumn, CButtonColumn и CCheckBoxColumn.

cssFile свойство

public string $cssFile;

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

enableHistory свойство (доступно с версии v1.1.11)

public boolean $enableHistory;

использовать объект истории браузера. Установите это свойство в true, чтобы сохранить состояние таблицы при переходах на страницу. Обратите внимание, что для этой функции есть два ограничения:

• эта функция совместима только с браузерами, поддерживающими HTML5.
• ожидайте неожиданного поведения (например, несколько запросов AJAX), если на одной странице есть более одной таблицы/списка с включённой enableHistory.

filter свойство (доступно с версии v1.1.1)

public CModel $filter;

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

filterCssClass свойство (доступно с версии v1.1.1)

public string $filterCssClass;

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

filterPosition свойство (доступно с версии v1.1.1)

public string $filterPosition;

должны ли фильтры отображаться в таблице. Допустимые значения:

• header: фильтры будут отображаться над каждой ячейкой заголовка столбца.
• body: фильтры будут отображаться непосредственно под каждой ячейкой заголовка столбца.
• footer: фильтры будут отображаться под каждой ячейкой подвала столбца.

filterSelector свойство (доступно с версии v1.1.13)

public string $filterSelector;

jQuery селектор полей ввода фильтра. Токен '{filter}' распознаётся и заменяется селектором фильтров таблицы. По умолчанию '{filter}'.

Примечание: если это значение пустое, будет выброшено исключение.

Пример (добавление пользовательского селектора к стандартному):

 ...
 'filterSelector'=>'{filter}, #myfilter',
 ...

formatter свойство

public CFormatter getFormatter()
public void setFormatter(CFormatter $value)

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

hasFooter свойство только для чтения

public boolean getHasFooter()

должен ли таблица отображать подвал. Это true, если у любой из колонок есть значение true CGridColumn::hasFooter.

hideHeader свойство (доступно с версии v1.1.1)

public boolean $hideHeader;

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

loadingCssClass свойство (доступно начиная с v1.1.1)

public string $loadingCssClass;

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

nullDisplay свойство

public string $nullDisplay;

текст, который будет отображаться в ячейке данных, когда значение данных равно null. Это свойство НЕ будет кодироваться в HTML при рендеринге. По умолчанию пустой HTML.

rowCssClass свойство

public array $rowCssClass;

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

rowCssClassExpression свойство

public string $rowCssClassExpression;

PHP-выражение, которое вычисляется для каждой строки тела таблицы, а результат используется в качестве имени CSS-класса для строки. В этом выражении вы можете использовать следующие переменные:

• $row номер строки (нумерация с нуля)
• $data модель данных для строки
• $this объект грида

rowHtmlOptionsExpression свойство (доступно начиная с v1.1.13)

public string $rowHtmlOptionsExpression;

PHP-выражение, которое вычисляется для каждой строки тела таблицы, а результат используется в качестве дополнительных атрибутов HTML для строки. Выражение должно возвращать массив, пары ключ-значение которого соответствуют атрибуту и значению HTML. В этом выражении вы можете использовать следующие переменные:

• $row номер строки (нумерация с нуля)
• $data модель данных для строки
• $this объект грида

selectableRows свойство

public integer $selectableRows;

количество строк тела таблицы, которые можно выбрать. Если 0, строки нельзя выбрать. Если 1, можно выбрать только одну строку. Если 2 или любое другое число, можно выбрать несколько строк. Выбранная строка будет иметь CSS-класс «selected». Вы также можете вызвать JavaScript-функцию $(gridID).yiiGridView('getSelection') для получения ключевых значений текущих выбранных строк (gridID — селектор DOM грида).

selectionChanged свойство

public string $selectionChanged;

JavaScript-функция, которая будет вызвана после изменения выбора строк. Подпись функции: function(id) , где «id» относится к идентификатору грида. В этой функции вы можете использовать $(gridID).yiiGridView('getSelection') для получения ключевых значений текущих выбранных строк (gridID — селектор DOM грида).

showTableOnEmpty свойство

public boolean $showTableOnEmpty;

отображать ли таблицу, даже если данных нет. По умолчанию true. emptyText будет отображаться, чтобы указать, что данных нет.

updateSelector свойство (доступно начиная с v1.1.7)

public string $updateSelector;

jQuery-селектор HTML-элементов, которые могут инициировать AJAX-обновления при нажатии. Распознаются токены: {page} и {sort}. Они будут заменены селекторами страниц и сортировки. По умолчанию '{page}, {sort}', что означает, что ссылки постраничной навигации и ссылки сортировки будут вызывать AJAX-обновления. Токены доступны с версии 1.1.11

Примечание: если это значение пустое, будет брошено исключение.

Пример (добавление пользовательского селектора к стандартным):

 ...
 'updateSelector'=>'{page}, {sort}, #mybutton',
 ...

Подробное описание методов

createDataColumn() метод

protected CDataColumn createDataColumn(string $text)

protected function createDataColumn($text)
{
    if(!preg_match('/^([\w\.]+)(:(\w*))?(:(.*))?$/',$text,$matches))
        throw new CException(Yii::t('zii','The column must be specified in the format of "Name:Type:Label", where "Type" and "Label" are optional.'));
    $column=new CDataColumn($this);
    $column->name=$matches[1];
    if(isset($matches[3]) && $matches[3]!=='')
        $column->type=$matches[3];
    if(isset($matches[5]))
        $column->header=$matches[5];
    return $column;
}

Создаёт CDataColumn на основе короткой строки описания столбца.

getFormatter() метод

public CFormatter getFormatter()

public function getFormatter()
{
    if($this->_formatter===null)
        $this->_formatter=Yii::app()->format;
    return $this->_formatter;
}

getHasFooter() метод

public boolean getHasFooter()

public function getHasFooter()
{
    foreach($this->columns as $column)
        if($column->getHasFooter())
            return true;
    return false;
}

init() метод

public void init()

public function init()
{
    parent::init();

    if(empty($this->updateSelector))
        throw new CException(Yii::t('zii','The property updateSelector should be defined.'));
    if(empty($this->filterSelector))
        throw new CException(Yii::t('zii','The property filterSelector should be defined.'));

    if(!isset($this->htmlOptions['class']))
        $this->htmlOptions['class']='grid-view';

    if($this->baseScriptUrl===null)
        $this->baseScriptUrl=Yii::app()->getAssetManager()->publish(Yii::getPathOfAlias('zii.widgets.assets')).'/gridview';

    if($this->cssFile!==false)
    {
        if($this->cssFile===null)
            $this->cssFile=$this->baseScriptUrl.'/styles.css';
        Yii::app()->getClientScript()->registerCssFile($this->cssFile);
    }

    $this->initColumns();
}

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

initColumns() метод

protected void initColumns()

protected function initColumns()
{
    if($this->columns===array())
    {
        if($this->dataProvider instanceof CActiveDataProvider)
            $this->columns=$this->dataProvider->model->attributeNames();
        elseif($this->dataProvider instanceof IDataProvider)
        {
            // use the keys of the first row of data as the default columns
            $data=$this->dataProvider->getData();
            if(isset($data[0]) && is_array($data[0]))
                $this->columns=array_keys($data[0]);
        }
    }
    $id=$this->getId();
    foreach($this->columns as $i=>$column)
    {
        if(is_string($column))
            $column=$this->createDataColumn($column);
        else
        {
            if(!isset($column['class']))
                $column['class']='CDataColumn';
            $column=Yii::createComponent($column, $this);
        }
        if(!$column->visible)
        {
            unset($this->columns[$i]);
            continue;
        }
        if($column->id===null)
            $column->id=$id.'_c'.$i;
        $this->columns[$i]=$column;
    }

    foreach($this->columns as $column)
        $column->init();
}

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

registerClientScript() метод

public void registerClientScript()

public function registerClientScript()
{
    $id=$this->getId();

    if($this->ajaxUpdate===false)
        $ajaxUpdate=false;
    else
        $ajaxUpdate=array_unique(preg_split('/\s*,\s*/',$this->ajaxUpdate.','.$id,-1,PREG_SPLIT_NO_EMPTY));
    $options=array(
        'ajaxUpdate'=>$ajaxUpdate,
        'ajaxVar'=>$this->ajaxVar,
        'pagerClass'=>$this->pagerCssClass,
        'loadingClass'=>$this->loadingCssClass,
        'filterClass'=>$this->filterCssClass,
        'tableClass'=>$this->itemsCssClass,
        'selectableRows'=>$this->selectableRows,
        'enableHistory'=>$this->enableHistory,
        'updateSelector'=>$this->updateSelector,
        'filterSelector'=>$this->filterSelector
    );
    if($this->ajaxUrl!==null)
        $options['url']=CHtml::normalizeUrl($this->ajaxUrl);
    if($this->ajaxType!==null) {
        $options['ajaxType']=strtoupper($this->ajaxType);
        $request=Yii::app()->getRequest();
        if ($options['ajaxType']=='POST' && $request->enableCsrfValidation) {
            $options['csrfTokenName']=$request->csrfTokenName;
            $options['csrfToken']=$request->getCsrfToken();
        }
    }
    if($this->enablePagination)
        $options['pageVar']=$this->dataProvider->getPagination()->pageVar;
    foreach(array('beforeAjaxUpdate', 'afterAjaxUpdate', 'ajaxUpdateError', 'selectionChanged') as $event)
    {
        if($this->$event!==null)
        {
            if($this->$event instanceof CJavaScriptExpression)
                $options[$event]=$this->$event;
            else
                $options[$event]=new CJavaScriptExpression($this->$event);
        }
    }

    $options=CJavaScript::encode($options);
    $cs=Yii::app()->getClientScript();
    $cs->registerCoreScript('jquery');
    $cs->registerCoreScript('bbq');
    if($this->enableHistory)
        $cs->registerCoreScript('history');
    $cs->registerScriptFile($this->baseScriptUrl.'/jquery.yiigridview.js',CClientScript::POS_END);
    $cs->registerScript(__CLASS__.'#'.$id,"jQuery('#$id').yiiGridView($options);");
}

Регистрирует необходимые клиентские скрипты.

renderDataCell() метод (доступно начиная с v1.1.16)

protected void renderDataCell(CGridColumn $column, integer $row)

protected function renderDataCell($column, $row)
{
    $column->renderDataCell($row);
}

Точка входа для расширения CGridView, чтобы подключиться к процессу рендеринга ячеек данных.

Переопределяя только этот метод, нам не нужно копировать и изменять весь метод `renderTableRow`. Или переопределить метод `renderDataCell()` всех возможных потомков CGridColumn.

renderFilter() метод (доступно начиная с v1.1.1)

public void renderFilter()

public function renderFilter()
{
    if($this->filter!==null)
    {
        echo "<tr class=\"{$this->filterCssClass}\">\n";
        foreach($this->columns as $column)
            $column->renderFilterCell();
        echo "</tr>\n";
    }
}

Отображает фильтр.

renderItems() метод

public void renderItems()

public function renderItems()
{
    if($this->dataProvider->getItemCount()>0 || $this->showTableOnEmpty)
    {
        echo "<table class=\"{$this->itemsCssClass}\">\n";
        $this->renderTableHeader();
        ob_start();
        $this->renderTableBody();
        $body=ob_get_clean();
        $this->renderTableFooter();
        echo $body; // TFOOT must appear before TBODY according to the standard.
        echo "</table>";
    }
    else
        $this->renderEmptyText();
}

Отображает элементы данных для грида.

renderTableBody() метод

public void renderTableBody()

public function renderTableBody()
{
    $data=$this->dataProvider->getData();
    $n=count($data);
    echo "<tbody>\n";

    if($n>0)
    {
        for($row=0;$row<$n;++$row)
            $this->renderTableRow($row);
    }
    else
    {
        echo '<tr><td colspan="'.count($this->columns).'" class="empty">';
        $this->renderEmptyText();
        echo "</td></tr>\n";
    }
    echo "</tbody>\n";
}

Отображает тело таблицы.

renderTableFooter() метод

public void renderTableFooter()

public function renderTableFooter()
{
    $hasFilter=$this->filter!==null && $this->filterPosition===self::FILTER_POS_FOOTER;
    $hasFooter=$this->getHasFooter();
    if($hasFilter || $hasFooter)
    {
        echo "<tfoot>\n";
        if($hasFooter)
        {
            echo "<tr>\n";
            foreach($this->columns as $column)
                $column->renderFooterCell();
            echo "</tr>\n";
        }
        if($hasFilter)
            $this->renderFilter();
        echo "</tfoot>\n";
    }
}

Отображает подвал таблицы.

renderTableHeader() метод

public void renderTableHeader()

public function renderTableHeader()
{
    if(!$this->hideHeader)
    {
        echo "<thead>\n";

        if($this->filterPosition===self::FILTER_POS_HEADER)
            $this->renderFilter();

        echo "<tr>\n";
        foreach($this->columns as $column)
            $column->renderHeaderCell();
        echo "</tr>\n";

        if($this->filterPosition===self::FILTER_POS_BODY)
            $this->renderFilter();

        echo "</thead>\n";
    }
    elseif($this->filter!==null && ($this->filterPosition===self::FILTER_POS_HEADER || $this->filterPosition===self::FILTER_POS_BODY))
    {
        echo "<thead>\n";
        $this->renderFilter();
        echo "</thead>\n";
    }
}

Отображает заголовок таблицы.

renderTableRow() метод

public void renderTableRow(integer $row)

public function renderTableRow($row)
{
    $htmlOptions=array();
    if($this->rowHtmlOptionsExpression!==null)
    {
        $data=$this->dataProvider->data[$row];
        $options=$this->evaluateExpression($this->rowHtmlOptionsExpression,array('row'=>$row,'data'=>$data));
        if(is_array($options))
            $htmlOptions = $options;
    }

    if($this->rowCssClassExpression!==null)
    {
        $data=$this->dataProvider->data[$row];
        $class=$this->evaluateExpression($this->rowCssClassExpression,array('row'=>$row,'data'=>$data));
    }
    elseif(is_array($this->rowCssClass) && ($n=count($this->rowCssClass))>0)
        $class=$this->rowCssClass[$row%$n];

    if(!empty($class))
    {
        if(isset($htmlOptions['class']))
            $htmlOptions['class'].=' '.$class;
        else
            $htmlOptions['class']=$class;
    }

    echo CHtml::openTag('tr', $htmlOptions)."\n";
    foreach($this->columns as $column)
        $this->renderDataCell($column, $row);
    echo "</tr>\n";
}

Отображает строку тела таблицы.

setFormatter() метод

public void setFormatter(CFormatter $value)

public function setFormatter($value)
{
    $this->_formatter=$value;
}