Enrique Matías Sánchez
6 years ago
committed by
Alexander Makarov
1 changed files with 245 additions and 0 deletions
@ -0,0 +1,245 @@
|
||||
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]] |
||||
|
||||
Loading…
Reference in new issue