Widgets de datos ¶

Yii proporciona un conjunto de widgets que se pueden usar para mostrar datos. Mientras que el widget DetailView se puede usar para mostrar los datos de un único registro, ListView y GridView se pueden usar para mostrar una lista o tabla de registros de datos proporcionando funcionalidades como paginación, ordenación y filtro.

DetailView ¶

El widget DetailView muestra los detalles de un único modelo de datos.

Se recomienda su uso para mostrar un modelo en un formato estándar (por ejemplo, cada atributo del modelo se muestra como una fila en una tabla). El modelo puede ser tanto una instancia o subclase de yii\base\Model como un active record o un array asociativo.

DetailView usa la propiedad $attributes para determinar qué atributos del modelo se deben mostrar y cómo se deben formatear. En la sección sobre formateadores se pueden ver las opciones de formato disponibles.

Un uso típico de DetailView sería así:

echo DetailView::widget([
    'model' => $model,
    'attributes' => [
        'title',                                           // atributo title (en texto plano)
        'description:html',                                // atributo description formateado como HTML
        [                                                  // nombre del propietario del modelo
            'label' => 'Owner',
            'value' => $model->owner->name,
            'contentOptions' => ['class' => 'bg-red'],     // atributos HTML para personalizar el valor
            'captionOptions' => ['tooltip' => 'Tooltip'],  // atributos HTML para personalizar la etiqueta
        ],
        'created_at:datetime',                             // fecha de creación formateada como datetime
    ],
]);

Recuerde que a diferencia de yii\widgets\GridView, que procesa un conjunto de modelos, DetailView sólo procesa uno. Así que la mayoría de las veces no hay necesidad de usar funciones anónimas ya que $model es el único modelo a mostrar y está disponible en la vista como una variable.

Sin embargo, en algunos casos el uso de una función anónima puede ser útil. Por ejemplo cuando visible está especificado y se desea impedir el cálculo de value en case de que evalúe a false:

echo DetailView::widget([
    'model' => $model,
    'attributes' => [
        [
            'attribute' => 'owner',
            'value' => function ($model) {
                return $model->owner->name;
            },
            'visible' => \Yii::$app->user->can('posts.owner.view'),
        ],
    ],
]);

ListView ¶

El widget ListView se usa para mostrar datos de un proveedor de datos. Cada modelo de datos se representa usando el fichero de vista indicado. Como proporciona de serie funcionalidades tales como paginación, ordenación y filtro, es útil tanto para mostrar información al usuario final como para crear una interfaz de usuario de gestión de datos.

Un uso típico es el siguiente:

use yii\widgets\ListView;
use yii\data\ActiveDataProvider;

$dataProvider = new ActiveDataProvider([
    'query' => Post::find(),
    'pagination' => [
        'pageSize' => 20,
    ],
]);

echo ListView::widget([
    'dataProvider' => $dataProvider,
    'itemView' => '_post',
]);

El fichero de vista _post podría contener lo siguiente:

<?php
use yii\helpers\Html;
use yii\helpers\HtmlPurifier;
?>
<div class="tarea">
    <h2><?= Html::encode($model->title) ?></h2>

    <?= HtmlPurifier::process($model->text) ?>
</div>

En el fichero de vista anterior, el modelo de datos actual está disponible como $model. Además están disponibles las siguientes variables:

• $key: mixto, el valor de la clave asociada a este elemento de datos.
• $index: entero, el índice empezando por cero del elemento de datos en el array de elementos devuelto por el proveedor de datos.
• $widget: ListView, esta instancia del widget.

Si se necesita pasar datos adicionales a cada vista, se puede usar la propiedad $viewParams para pasar parejas clave-valor como las siguientes:

echo ListView::widget([
    'dataProvider' => $dataProvider,
    'itemView' => '_post',
    'viewParams' => [
        'fullView' => true,
        'context' => 'main-page',
        // ...
    ],
]);

Entonces éstas también estarán disponibles en la vista como variables.

GridView ¶

La cuadrícula de datos o GridView es uno de los widgets de Yii más potentes. Es extremadamente útil si necesita construir rápidamente la sección de administración del sistema. Recibe los datos de un proveedor de datos y representa cada fila usando un conjunto de columnas que presentan los datos en forma de tabla.

Cada fila de la tabla representa los datos de un único elemento de datos, y una columna normalmente representa un atributo del elemento (algunas columnas pueden corresponder a expresiones complejas de los atributos o a un texto estático).

El mínimo código necesario para usar GridView es como sigue:

use yii\grid\GridView;
use yii\data\ActiveDataProvider;

$dataProvider = new ActiveDataProvider([
    'query' => Post::find(),
    'pagination' => [
        'pageSize' => 20,
    ],
]);
echo GridView::widget([
    'dataProvider' => $dataProvider,
]);

El código anterior primero crea un proveedor de datos y a continuación usa GridView para mostrar cada atributo en cada fila tomados del proveedor de datos. La tabla mostrada está equipada de serie con las funcionalidades de ordenación y paginación.

Columnas de la cuadrícula ¶

Las columnas de la tabla se configuran en términos de clase yii\grid\Column, que se configuran en la propiedad columns de la configuración del GridView. Dependiendo del tipo y ajustes de las columnas éstas pueden presentar los datos de diferentes maneras. La clase predefinida es yii\grid\DataColumn, que representa un atributo del modelo por el que se puede ordenar y filtrar.

echo GridView::widget([
    'dataProvider' => $dataProvider,
    'columns' => [
        ['class' => 'yii\grid\SerialColumn'],
        // Columnas sencillas definidas por los datos contenidos en $dataProvider.
        // Se usarán los datos de la columna del modelo.
        'id',
        'username',
        // Un ejemplo más complejo.
        [
            'class' => 'yii\grid\DataColumn',  // Se puede omitir, ya que es la predefinida.
            'value' => function ($data) {
                return $data->name;  // $data['name'] para datos de un array, por ejemplo al usar SqlDataProvider.
            },
        ],
    ],
]);

Observe que si no se especifica la parte columns de la configuración, Yii intenta mostrar todas las columnas posibles del modelo del proveedor de datos.

Clases de columna ¶

Las columnas de la cuadrícula se pueden personalizar usando diferentes clases de columna:

echo GridView::widget([
    'dataProvider' => $dataProvider,
    'columns' => [
        [
            'class' => 'yii\grid\SerialColumn', // <-- aquí
            // puede configurar propiedades adicionales aquí
        ],

Además de las clases de columna proporcionadas por Yii que se revisarán más abajo, puede crear sus propias clases de columna.

Cada clase de columna extiende yii\grid\Column de modo que hay algunas opciones comunes que puede establecer al configurar las columnas de una cuadrícula.

• header permite establecer el contenida para la fila cabecera
• footer permite establece el contenido de la fila al pie
• visible define si la columna debería ser visible.

• content le permite pasar una función PHP válida que devuelva datos para una fila. El formato es el siguiente:

  function ($model, $key, $index, $column) {
      return 'una cadena';
  }
  

Puede indicar varias opciones HTML del contenedor pasando arrays a:

• headerOptions
• footerOptions
• filterOptions
• contentOptions