output-data-widgets.md

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 [[yii\widgets\DetailView|DetailView]] muestra los detalles de un único [[yii\widgets\DetailView::$model|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 [[yii\widgets\DetailView::$attributes|$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|GridView]], que procesa un conjunto de modelos, [[yii\widgets\DetailView|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 [[yii\widgets\ListView|ListView]] se usa para mostrar datos de un proveedor de datos. Cada modelo de datos se representa usando el [[yii\widgets\ListView::$itemView|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 [[yii\widgets\ListView::$viewParams|$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 [[yii\grid\GridView|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 [[yii\grid\GridView::columns|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 [[yii\grid\GridView::columns|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 [[yii\grid\GridView::columns|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.

• [[yii\grid\Column::header|header]] permite establecer el contenida para la fila cabecera

• [[yii\grid\Column::footer|footer]] permite establece el contenido de la fila al pie

• [[yii\grid\Column::visible|visible]] define si la columna debería ser visible.

• [[yii\grid\Column::content|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:

• [[yii\grid\Column::headerOptions|headerOptions]]
• [[yii\grid\Column::footerOptions|footerOptions]]
• [[yii\grid\Column::filterOptions|filterOptions]]
• [[yii\grid\Column::contentOptions|contentOptions]]