Skip to content

Y
yii2
Commit 4e39a069 by Carsten Brandt
Options

Merge pull request #3871 from oliversd/master

Fix in start-hello.md and spanish translation of start-forms.md
parents 5034a322 8dd5d144
Showing with 244 additions and 22 deletions
docs/guide-es/start-forms.md 0 → 100644
Trabajando con Formularios
==========================
En esta sección, describiremos como crear una nueva página para solicitar información de los usuarios.
La página mostrará un formulario con un campo de input para el nombre y un campo de input para el email.
Después de recibir estos datos del usuario, la página le mostrará la información de vuelta al usuario para la confirmación.
Para lograr este objetivo, además de crear un [action](structure-controllers.md) (acción) y
dos [views](structure-views.md) (vistas), también crearás un [model](structure-models.md) (modelo).
A través de este tutorial, aprenderás
* Cómo crear un [model](structure-models.md) para representar los datos ingresados por un usuario;
* Cómo declarar reglas para validar los datos ingresado por los usuarios;
* Cómo construir un formulario HTML en un [view](structure-views.md).
Creando un Modelo <a name="creating-model"></a>
-----------------
Para representar los datos ingresados por un usuario, crea una clase modelo `EntryForm` cómo se muestra abajo y
guarda la clase en el archivo `models/EntryForm.php`. Por favor ver la sección [Class Autoloading](concept-autoloading.md)
para más detalles acerca de la convención de como nombrar los archivos de clase.
```php
<?php
namespace app\models;
use yii\base\Model;
class EntryForm extends Model
{
public $name;
public $email;
public function rules()
{
return [
[['name', 'email'], 'required'],
['email', 'email'],
];
}
}
```
La clase se extiende a partir de [[yii\base\Model]], que es una clase base que provee Yii y es comúnmente utilizada
para representar datos de formularios.
La clase contiene dos miembros públicos, `name` y `email`, que son utilizas para mantener
los datos ingresados por el usuario. También contiene el método llamado `rules()` que regresa un conjunto
de reglas utilizadas para validar los datos. Las reglas de validación declaradas arriba indican que
* que ambos datos tanto el `name` como el `email` son requeridos;
* el dato `email` debe ser una dirección de correo válida.
Si tienes un objeto `EntryForm` llenado con los datos ingresados por el usuario, puedes llamar
su [[yii\base\Model::validate()|validate()]] para disparar (trigger) la validación de los datos. Un fallo en la validación
de los datos se mostrará en la propiedad [[yii\base\Model::hasErrors|hasErrors]], y a través de
[[yii\base\Model::getErrors|errors]] puedes aprender cuales son los errores de validación que tiene el modelo.
Creando una Acción <a name="creating-action"></a>
------------------
Luego, crea una acción `entry` en el controlador `site`, como lo hiciste en la sección anterior.
```php
<?php
namespace app\controllers;
use Yii;
use yii\web\Controller;
use app\models\EntryForm;
class SiteController extends Controller
{
// ...código existente...
public function actionEntry()
{
$model = new EntryForm;
if ($model->load(Yii::$app->request->post()) && $model->validate()) {
// validar los datos recibidos en el modelo
// aquí haz algo significativo con el modelo ...
return $this->render('entry-confirm', ['model' => $model]);
} else {
// La página es mostrada inicialmente o hay algún error de validación
return $this->render('entry', ['model' => $model]);
}
}
}
```
La acción primero crea un objeto `EntryForm`. Luego intenta poblar el modelo
con los datos del `$_POST` que es proporcionado por Yii a través de [[yii\web\Request::post()]].
Si el modelo es llenado satisfactoriamente (p.e., el usuario ha enviado (submit) el formulario HTML),
llamará [[yii\base\Model::validate()|validate()]] para asegurarse que los datos ingresados
son válidos.
Si todo está bien, la acción mostrará (render) una vista llamada `entry-confirm` para confirmar
con el usuario que acepta los datos que ha ingresado. De otra manera, la vista `entry` será
mostrada, y mostrará el formulario HTML junto con los mensajes de error de validación (si es que hay alguno).
> Info: La expresión `Yii::$app` representa la instancia de la [application](structure-applications.md) (aplicación)
que es un singleton globalmente accesible. También es un [service locator](concept-service-locator.md) (localizador de servicio)
que provee los componentes, tales como `request`, `response`, `db`, etc. para soportar funcionalidades específicas.
En el código de arriba, el componente `request` es utilizado para acceder los datos `$_POST`.
Creando Vistas <a name="creating-views"></a>
--------------
Finalmente, crea dos vistas llamadas `entry-confirm` y `entry` que son mostradas por la acción `entry`,
como fue descrito en la última sub-sección.
La vista `entry-confirm` simplemente muestra los datos de name y email. Debe ser guardada como el archivo `views/site/entry-confirm.php`.
```php
<?php
use yii\helpers\Html;
?>
<p>You have entered the following information:</p>
<ul>
<li><label>Name</label>: <?= Html::encode($model->name) ?></li>
<li><label>Email</label>: <?= Html::encode($model->email) ?></li>
</ul>
```
La vista `entry` muestra un formulario HTML. Debe ser guardado como el archivo `views/site/entry.php`.
```php
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
?>
<?php $form = ActiveForm::begin(); ?>
<?= $form->field($model, 'name') ?>
<?= $form->field($model, 'email') ?>
<div class="form-group">
<?= Html::submitButton('Submit', ['class' => 'btn btn-primary']) ?>
</div>
<?php ActiveForm::end(); ?>
```
La vista utiliza un poderoso [widget](structure-widgets.md) llamado [[yii\widgets\ActiveForm|ActiveForm]] para
construir el formulario HTML. Los métodos `begin()` y `end()` del widget muestran, respectivamente, las etiquetas de
apertura y cierre del formulario. Entre las llamadas de los dos métodos, los campos de input son creados por el
método [[yii\widgets\ActiveForm::field()|field()]]. El primer campo input es del dato "name",
y el segundo del dato "email". Después de los campos de input, el método [[yii\helpers\Html::submitButton()]]
es llamado para general el botón de submit (enviar).
Probando <a name="trying-it-out"></a>
--------
Para ver como funciona, utiliza tu navegador para ir al siguiente URL:
```
http://hostname/index.php?r=site/entry
```
Verás una página que muestra un formulario con dos campos de input. Adelante de cada campo de input, será mostrada también
una etiqueta indicando que dato necesitas ingresar. Si haces click en el botón de submit sin ingresar nada,
o si ingresas una dirección de correo inválida, verás un mensaje de error que
se mostrará al lado del campo que tiene problemas.
![Form with Validation Errors](images/start-form-validation.png)
Después de ingresar un nombre y dirección de correo válidos y haciendo click en el botón de submit, verás una nueva página
mostrando los datos que acabas de ingresar.
![Confirmation of Data Entry](images/start-entry-confirmation.png)
### Magia Explicada <a name="magic-explained"></a>
Te puedes preguntar como el formulario HTML funciona detrás de cámara, porque parece casi mágico que pueda
mostrar una etiqueta para cada campo de input y mostrar los mensajes de error si no ingresas los datos correctamente
sin recargar la página.
Si, la validación de los datos es realmente realizada en el lado del cliente utilizando JavaScript así como también en el lado del servidor.
[[yii\widgets\ActiveForm]] es lo suficientemente inteligente para extraer las reglas de validación que has declarado en `EntryForm`,
convertirlas en código Javascript, y utilizar el JavaScript para realizar la validación de los datos. En caso de que hayas deshabilitado
JavaScript en tu navegador, la validación igual se realizará en el lado del servidor, como se muestra en
el método `actionEntry()`. Esto garantiza la validez de los datos en todas las circunstancias.
Las etiquetas de los campos de input son generados por el método `field()` basado en los nombres de las propiedades del modelo.
Por ejemplo, la etiqueta `Name` será generada de la propiedad `name`. Puedes personalizar una etiqueta con
el siguiente código:
```php
<?= $form->field($model, 'name')->label('Tu Nombre') ?>
<?= $form->field($model, 'email')->label('Tu Email') ?>
```
> Info: Yii provee muchos widgets para ayudarte a construir rápidamente vistas complejas y dinámicas.
Como aprenderás más adelante, escribir un nuevo widget es extremadamente fácil. Puedes convertir mucho del
código de tus vistas en widgets reutilizables para simplificar el desarrollo de las vistas en un futuro.
Resumen <a name="summary"></a>
-------
En esta sección, has tocado cada parte del patrón de diseño MVC. Ahora has aprendido
a crear una clase modelo para representar los datos del usuario y validarlos.
También has aprendido como obtener datos de los usuarios y como mostrarlos de vuelta. Esta es una tarea que
puede tomarte mucho tiempo cuando estás desarrollando una aplicación. Yii provee poderosos widgets
para hacer muy fácil esta tarea.
En la próxima sección, aprenderás como trabajar con bases de datos que son necesarias en casi cualquier aplicación.
docs/guide-es/start-hello.md
Diciendo Hola
============
=============
Esta sección describe cómo crear una nueva página "Hola" en tu aplicación.
Para lograr este objetivo, vas a crear un [action](structure-controllers.md#creating-actions) (una acción) y
......@@ -18,16 +18,16 @@ A lo largo de este tutorial, aprenderás tres cosas:
Creando una Acción <a name="creating-action"></a>
------------------
Para la tarea "Hola", crearás un [action](structure-controllers.md#creating-actions) `dice` que lee
un parámetro `mensaje` de la petición y muestra este mensaje de vuelta al usuario. Si la petición
no provee un parámetro `mensaje`, la acción mostrará el mensaje por defecto "Hola".
Para la tarea "Hola", crearás un [action](structure-controllers.md#creating-actions) `say` que lee
un parámetro `message` de la petición y muestra este mensaje de vuelta al usuario. Si la petición
no provee un parámetro `message`, la acción mostrará el mensaje por defecto "Hola".
> Info: [Actions](structure-controllers.md#creating-actions) son objetos que los usuarios finales pueden utilizar directamente para
su ejecución. Las Acciones están agrupadas por [controllers](structure-controllers.md) (controladores). El resultado de la ejecución de
una acción es la respuesta que el usuario final recibirá.
Las Acciones deben ser declaradas en [controllers](structure-controllers.md). Para simplificar, puedes
declarar la acción `dice` en el `SiteController` existente. Este controlador está definido
declarar la acción `say` en el `SiteController` existente. Este controlador está definido
en el archivo de clase `controllers/SiteController.php`. Aquí está el inicio de la nueva acción:
```php
......@@ -41,14 +41,14 @@ class SiteController extends Controller
{
// ...código existente...
public function actionDice($mensaje = 'Hola')
public function actionDice($message = 'Hola')
{
return $this->render('dice', ['mensaje' => $mensaje]);
return $this->render('say', ['message' => $message]);
}
}
```
En el código de arriba, la acción `dice` está definida por un método llamado `actionDice` en la clase `SiteController`.
En el código de arriba, la acción `say` está definida por un método llamado `actionDice` en la clase `SiteController`.
Yii utiliza el prefijo `action` para diferenciar los métodos de acciones de otros métodos en las clases de los controladores.
El nombre que le sigue al prefijo `action` se mapea al ID de la acción.
......@@ -58,14 +58,14 @@ referenciados en minúscula. Si un ID de acción requiere múltiples palabras, e
removiendo los guiones, colocando en mayúscula la primera letra de cada palabra, y colocando el prefijo `action` al resultado. Por ejemplo,
el ID de la acción `crear-comentario` corresponde al nombre de método de acción `actionCrearComentario`.
El método de acción en nuestro ejemplo toma un parámetro `$mensaje`, el cual tiene como valor por defecto `"Hola"` (de la misma manera
El método de acción en nuestro ejemplo toma un parámetro `$message`, el cual tiene como valor por defecto `"Hola"` (de la misma manera
que se coloca un valor por defecto a un argumento en cualquier función o método en PHP). Cuando una aplicación
recibe una petición y determina que la acción `dice` es responsable de manejar dicha petición, la aplicación llenará
recibe una petición y determina que la acción `say` es responsable de manejar dicha petición, la aplicación llenará
el parámetro con el parámetro que tenga el mismo nombre en la petición. En otras palabras, si la petición incluye un
parámetro `mensaje` con el valor de `"Adios"`, la variable `$mensaje` dentro de la acción será sustituida por este valor.
parámetro `message` con el valor de `"Adios"`, la variable `$message` dentro de la acción será sustituida por este valor.
Dentro del método de acción, [[yii\web\Controller::render()|render()]] es llamado para hacer render (mostrar o visualizar) un
archivo [view](structure-views.md) llamado `dice`. El parámetro `mensaje` tambien es pasado al view para que pueda ser utilizado ahí.
archivo [view](structure-views.md) llamado `say`. El parámetro `message` tambien es pasado al view para que pueda ser utilizado ahí.
El resultado es regresado al método action. Ese resultado será recibido por la aplicación y mostrado al usuario final en el
navegador (como parte de una página HTML completa).
......@@ -74,24 +74,24 @@ Creando una Vista <a name="creating-view"></a>
-----------------
[Views](structure-views.md) (vistas) son scripts que escribes para generar una respuesta de contenido.
Para la tarea "Hola", vas a crear una vista `dice` que imprime el parámetro `mensaje` recibido desde el método action, y pasado por la acción a la vista:
Para la tarea "Hola", vas a crear una vista `say` que imprime el parámetro `message` recibido desde el método action, y pasado por la acción a la vista:
```php
<?php
use yii\helpers\Html;
?>
<?= Html::encode($mensaje) ?>
<?= Html::encode($message) ?>
```
El view `dice` debe ser guardado en el archivo `views/site/dice.php`. Cuando el método [[yii\web\Controller::render()|render()]]
El view `say` debe ser guardado en el archivo `views/site/dice.php`. Cuando el método [[yii\web\Controller::render()|render()]]
es llamado en una acción, buscará un archivo PHP llamado `views/ControllerID/NombreView.php`.
Nota que en el código de arriba, el parámetro `mensaje` es [[yii\helpers\Html::encode()|HTML-encoded]]
Nota que en el código de arriba, el parámetro `message` es [[yii\helpers\Html::encode()|HTML-encoded]]
antes de ser impreso. Esto es necesario ya que el parámetro viene de un usuario final, haciéndolo vulnerable a
[ataques cross-site scripting (XSS)](http://es.wikipedia.org/wiki/Cross-site_scripting) pudiendo inyectar código de Javascript malicioso dentro del parámetro.
Naturalmente, puedes colocar mas contenido en el view `dice`. El contenido puede consistir de etiquetas HTML, texto plano, e inlcusive código PHP.
De hecho, el view `dice` es sólo un script PHP que es ejecutado por el método [[yii\web\Controller::render()|render()]].
Naturalmente, puedes colocar mas contenido en el view `say`. El contenido puede consistir de etiquetas HTML, texto plano, e inlcusive código PHP.
De hecho, el view `say` es sólo un script PHP que es ejecutado por el método [[yii\web\Controller::render()|render()]].
El contenido impreso por el script view será regresado a la aplicación como la respuesta del resultado. La aplicación a cambio mostrará el resultado al usuario final.
......@@ -108,15 +108,15 @@ http://hostname/index.php?r=site/dice&mensaje=Hello+World
Esta URL resultará en una página mostrando "Hello World". La página comparte el mismo encabezado y pie de página de las otras páginas de la aplicación.
Si omites el parámetro `mensaje` en el URL, verás que la página muestra sólo "Hola". Esto es porque `mensaje` es pasado como un parámetro al método `actionDice()`, y cuando es omitido, el valor por defecto `"Hola"` será utilizado.
Si omites el parámetro `message` en el URL, verás que la página muestra sólo "Hola". Esto es porque `message` es pasado como un parámetro al método `actionDice()`, y cuando es omitido, el valor por defecto `"Hola"` será utilizado.
> Info: La nueva página comparte el mismo encabezado y pie de página que otras páginas porque el método [[yii\web\Controller::render()|render()]]
automáticamente inyectará el resultado del view `dice` en la plantilla [layout](structure-views.md#layouts) que en este
automáticamente inyectará el resultado del view `say` en la plantilla [layout](structure-views.md#layouts) que en este
caso está localizada en `views/layouts/main.php`.
El parámetro `r` en el URL de arriba requiere más explicación. Significa [route](runtime-routing.md) (ruta), y es el ID amplio y único de una aplicación
que refiere a una acción. El formato de las rutas es `ControllerID/ActionID`. Cuando la aplicación recibe una petición, revisará este parámetro, utilizando la parte del `ControllerID` para determinar cual clase de controlador será inicializado para manejar la petición. Entonces, el controlador utilizará la parte `ActionID` para determinar cual acción debe ser inizializada para hacer realmente el trabajo. En este ejemplo, la ruta `site/dice`
será respondida por la clase controlador `SiteController` y la acción `dice`. Como resultado,
será respondida por la clase controlador `SiteController` y la acción `say`. Como resultado,
el método `SiteController::actionDice()` será llamado para manejar el requerimiento.
> Info: Al igual que las acciones, los controladores tambien tienen ID únicos que los identifican en una aplicación.
......@@ -128,7 +128,7 @@ Resumen <a name="summary"></a>
-------
En esta sección, has tocado las partes del controlador y la vista del patrón de diseño MVC.
Has creado una acción como parte de un controlador para manejar una petición específica. Y también has creado una vista para armar el contenido de la respuesta. En este simple ejemplo, ningún modelo ha sido involucrado ya que el único dato que fue utilizado fue el parámetro `mensaje`.
Has creado una acción como parte de un controlador para manejar una petición específica. Y también has creado una vista para armar el contenido de la respuesta. En este simple ejemplo, ningún modelo ha sido involucrado ya que el único dato que fue utilizado fue el parámetro `message`.
También has aprendido acerca de las rutas en Yii, que actúan como puentes entre la petición del usuario y las acciones del controlador.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment