You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
246 lines
8.7 KiB
246 lines
8.7 KiB
6 years ago
|
Widgets de datos
|
||
|
================
|
||
|
|
||
|
Yii proporciona un conjunto de [widgets](structure-widgets.md) que se pueden usar para mostrar datos.
|
||
|
Mientras que el _widget_ [DetailView](#detail-view) se puede usar para mostrar los datos de un único
|
||
|
registro, [ListView](#list-view) y [GridView](#grid-view) se pueden usar para mostrar una lista o
|
||
|
tabla de registros de datos proporcionando funcionalidades como paginación, ordenación y filtro.
|
||
|
|
||
|
|
||
|
DetailView <span id="detail-view"></span>
|
||
|
----------
|
||
|
|
||
|
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](db-active-record.md) 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](output-formatting.html) se pueden ver las opciones de formato
|
||
|
disponibles.
|
||
|
|
||
|
Un uso típico de DetailView sería así:
|
||
|
|
||
|
```php
|
||
|
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`:
|
||
|
|
||
|
```php
|
||
|
echo DetailView::widget([
|
||
|
'model' => $model,
|
||
|
'attributes' => [
|
||
|
[
|
||
|
'attribute' => 'owner',
|
||
|
'value' => function ($model) {
|
||
|
return $model->owner->name;
|
||
|
},
|
||
|
'visible' => \Yii::$app->user->can('posts.owner.view'),
|
||
|
],
|
||
|
],
|
||
|
]);
|
||
|
```
|
||
|
|
||
|
|
||
|
ListView <span id="list-view"></span>
|
||
|
--------
|
||
|
|
||
|
El _widget_ [[yii\widgets\ListView|ListView]] se usa para mostrar datos de un
|
||
|
[proveedor de datos](output-data-providers.md).
|
||
|
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:
|
||
|
|
||
|
```php
|
||
|
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
|
||
|
<?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:
|
||
|
|
||
|
```php
|
||
|
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 <span id="grid-view"></span>
|
||
|
--------
|
||
|
|
||
|
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](output-data-providers.md)
|
||
|
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:
|
||
|
|
||
|
```php
|
||
|
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 <span id="grid-columns"></span>
|
||
|
|
||
|
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.
|
||
|
|
||
|
|
||
|
```php
|
||
|
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 <span id="column-classes"></span>
|
||
|
|
||
|
Las columnas de la cuadrícula se pueden personalizar usando diferentes clases de columna:
|
||
|
|
||
|
```php
|
||
|
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:
|
||
|
|
||
|
```php
|
||
|
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]]
|
||
|
|