diff --git a/docs/guide-es/output-data-widgets.md b/docs/guide-es/output-data-widgets.md new file mode 100644 index 0000000..06db9fe --- /dev/null +++ b/docs/guide-es/output-data-widgets.md @@ -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 +---------- + +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 +-------- + +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 + +
+

title) ?>

+ + text) ?> +
+``` + +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 +-------- + +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 + +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 + +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]] +