docs/tutorial-es.markdown

   1 Creando una aplicación simple usando el Akelos Framework
   2 =========================================================
   3
   4 Introducción
   5 --------------------------
   6
   7 Este tutorial te muestra cómo crear una aplicación con el Akelos Framework.
   8
   9 Esta aplicación sirve para manejar libros y sus autores y la llamaremos **booklink**
  10
  11 Requisitos para este tutorial
  12 ---------------------------
  13
  14  - Una Base de Datos MySQl o SQLite
  15  - Servidor web Apache
  16  - Acceso Shell a tu servidor
  17  - PHP4 ó PHP5
  18
  19 Esta configuración se puede encontrar en la mayoría de los servidores y proveedores de hosting Linux. Akelos funciona bajo múltiples configuraciones, pero para este tutorial nos centraremos en los requisitos anteriores.
  20
  21 Descarga e Instalación
  22 ---------------------------
  23 Hasta que no esté disponible la versión 1.0, te recomendamos que te descargues la última versión trunk (troncal). Para ello necesitas tener instalado [subversion](http://subversion.tigris.org/).
  24 Puedes retirar una "copia de trabajo" del código fuente de Akelos con el comando:
  25
  26     svn co http://svn.akelos.org/trunk/ akelos
  27
  28 Si no puedes o no quieres descargar el código desde subversion, puedes obtener la [última versión estable](http://www.akelos.org/akelos_framework-dev_preview.tar.gz) generada de forma automática por el sistema de Integración Contínua, y descomprimirlo con el comando:
  29
  30     tar zxvf akelos_framework-dev_preview.tar.gz;mv akelos_framework-dev_preview akelos
  31
  32 Ahora comprobaremos que Akelos puede encontrar tu versión de PHP, ejecutando:
  33
  34     /usr/bin/env php -v
  35
  36 Si ves algo como:
  37
  38     PHP 5.1.2 (cli) (built: Jan 17 2006 15:00:28)
  39     Copyright (c) 1997-2006 The PHP Group
  40     Zend Engine v2.1.0, Copyright (c) 1998-2006 Zend Technologies
  41
  42 vas por buen camino y puedes continuar creando una aplicación con Akelos; de lo contrario necesitarás averiguar la ruta a tu binario de PHP, habitualmente con
  43
  44     which php
  45
  46 Y cambiar el `#!/usr/bin/env php` al inicio de estos archivos  `script/console`, `script/generate`, `script/migrate`, `script/setup` y `script/test` por la ruta a tu binario de php.
  47
  48 **Nota para los usuarios de Windows:** Necesitarás llamar a los scripts desde el directorio de tu aplicación, usando la ruta completa a tu archivo php.exe, por ejemplo:
  49
  50     C:\Archivos de Programa\xampp\php\php.exe ./script/generate scaffold
  51
  52 o alternativamente configurando el path para evitar escribir la ruta completa al binario de PHP siguiendo los pasos dell Mini HOW-TO [Añadiendo PHP al path de Windows](http://svn.akelos.org/trunk/docs/windows_set_php_path-es.markdown).
  53
  54 Instalando una nueva aplicación con Akelos
  55 ---------------------------------------------
  56
  57 Ya te has descargado Akelos y te has asegurado de que puedes ejecutar scripts PHP desde tu linea de comandos (no es necesario para ejecutar aplicaciones realizadas con Akelos, pero sí que es necesario para seguir este tutorial)
  58
  59 Ahora se pueden seguir dos vías:
  60
  61  1. Crear una aplicación con Akelos y enlazarla a las librerías del Framework.
  62  2. Comenzar a escribir el código de tu aplicación desde esta carpeta, con el riesgo que conlleva que los _visitantes_ de tu sitio puedan dirigirse con su navegador directamente a cualquier fichero del Framework o de tu aplicación sin pasar por el controlador principal.
  63
  64 Si ya te has descargado Akelos en `HOME_DIR/akelos` y estás dentro del directorio `akelos`, puedes comprobar las opciones disponibles para instalar tu nueva aplicación con el comando:
  65
  66    ./script/setup -h
  67
  68 lo que nos muestra las opciones disponibles para el instalador
  69
  70     Uso: setup [-sqphf --dependencies] <-d>
  71
  72     -deps --dependencies      Incluye una copia del framework dentro del directorio de la aplicación. (true)
  73     -d --directory=<value>    Directorio de destino para instalar la aplicación.
  74     -f --force                Sobrescribe archivos que ya existen. (false)
  75     -h --help                 Muestra la ayuda que ahora mismo estás leyendo.
  76     -p --public_html=<value>  Ubicación que el servidor web utilizará para iniciar la aplicación. ()
  77     -q --quiet                Suprime la salida por pantalla normal. (false)
  78     -s --skip                 Ignora archivos que ya existen en el directorio. (false)
  79
  80 Así que ejecutando el siguiente comando: (reemplazar `/www/htdocs` con tu  ruta al directorio público del servidor web. En algunos Hosting Compartidos es `/home/USUARIO/public_html`)
  81
  82     ./script/setup -d HOMEDIR/booklink -p /www/htdocs/booklink
  83
  84 Esto creará la siguiente estructura para la aplicación **booklink**:
  85
  86     booklink/
  87         app/ << La aplicación, incluyendo controladores, vistas, modelos e instaladores
  88         config/ << Los aburridos archivos de configuración (haremos la configuración vía web)
  89         public/ << Ésta es la única carpeta pública dentro del enlace simbólico /www/htdocs/booklink
  90         script/ << Utilidades para generación de código y ejecución de pruebas unitarias (tests)
  91
  92 **Nota para los usuarios de Windows:** Un enlace simbólico al directorio booklink/public se crea solamente en sistemas *NIX, así que necesitarás indicarle a tu servidor web cómo encontrar la ruta pública para la aplicación **booklink** en tu archivo `httpd.conf` agregando algo así como:
  93
  94     Alias /booklink "/path/to_your/booklink/public"
  95
  96     <Directory "/path/to_your/booklink/public">
  97         Options Indexes FollowSymLinks
  98         AllowOverride All
  99         Order allow,deny
 100         Allow from all
 101     </Directory>
 102
 103 una vez agregado esto, reinicia el servidor.
 104
 105 ### Creando una base de datos para la aplicación ###
 106
 107 El siguiente paso es crear una base de datos para la aplicación. Si tienes planeado usar SQLite sobre PHP5 puedes saltarte este paso.
 108
 109  En este tutorial no podemos  explicar cómo crear una base de datos MySQL pero quizá te sirva de ayuda tomar como ejemplo este caso común donde creamos tres bases de datos diferentes, una para cada entorno (producción, desarrollo y testing).
 110
 111     mysql -u root -p
 112
 113     mysql> CREATE DATABASE booklink;
 114     mysql> CREATE DATABASE booklink_dev;
 115     mysql> CREATE DATABASE booklink_tests;
 116
 117     mysql> GRANT ALL ON booklink.* TO bermi@localhost IDENTIFIED BY "pass";
 118     mysql> GRANT ALL ON booklink_dev.* TO bermi@localhost IDENTIFIED BY "pass";
 119     mysql> GRANT ALL ON booklink_tests.* TO bermi@localhost IDENTIFIED BY "pass";
 120
 121     mysql> FLUSH PRIVILEGES;
 122     mysql> exit
 123
 124 Si estás en un servidor de hosting compartido, seguramente deberás crearlas desde el panel de control de tu proveedor de alojamiento web.
 125
 126 ### Generando el archivo de configuración ###
 127
 128 #### Usando el instalador web ####
 129
 130 Ahora ya puedes acceder al asistente de configuración de tu aplicacion en http://localhost/booklink
 131
 132 Sigue los pasos del asistente para configurar el acceso a tu base de datos, configuraciones regionales y permisos de archivo, para así generar un archivo de configuración. Yo mientras vas creando la aplicación **booklink** tranquilamente, iré a buscar un café.
 133
 134 #### Configuración manual de la aplicación ####
 135
 136 Guarda los archivos `config/DEFAULT-config.php` y `config/DEFAULT-routes.php` como `config/config.php` y `config/routes.php` y modifica lo que consideres necesario siguiendo las indicaciones del fichero.
 137
 138 Si deseas usar URLs bonitas necesitas definir la ruta base para la reescritura de URLs, editando el archivo `public/.htaccess` y definiendo RewriteBase como:
 139
 140     RewriteBase /booklink
 141
 142 Una vez hayas instalado correctamente tu aplicación, podrás ver un mensaje de bienvenida en http://localhost/booklink. Ahora puedes eliminar los archivos de instalación del framework con toda seguridad (no serán accesibles mientras exista el archivo  `/config/config.php`)
 143
 144 La estructura de la base de datos de booklink
 145 ---------------------------------------------
 146
 147 Ahora necesitas definir las tablas y columnas donde la aplicación almacenará la información de los libros y los autores.
 148
 149 Cuando se trabaja con otros desarrolladores, los cambios en las bases de datos pueden ser difíciles de distribuir entre todos ellos. Akelos ofrece una solución a este problema llamada *instalador* o *migración*.
 150
 151 Para crear la estructura de la base de datos utilizarás un installer para distribuir las modificaciones que realices en ella.
 152 El uso de *instaladores* te permitirá definir las tablas y columnas de tu base de datos independientemente de si usas MySQL, SQLite u otro.
 153
 154 Ahora crearás un archivo llamado `app/installers/booklink_installer.php` con el siguiente código correspondiente al Instalador de Booklink:
 155
 156      <?php
 157
 158      class BooklinkInstaller extends AkInstaller
 159      {
 160          function up_1(){
 161
 162              $this->createTable('books',
 163                 'id,'.          // la clave principal
 164                 'title,'.       // el título del libro
 165                 'description,'. // la descripción del libro
 166                 'author_id,'.   // el identificador del author. Esto lo utilizará Akelos para vincular libros con autores.
 167                 'published_on'  // fecha de publicación
 168             );
 169
 170              $this->createTable('authors',
 171                 'id,'.      // la clave principal
 172                 'name'      // el nombre del autor
 173                 );
 174          }
 175
 176          function down_1(){
 177              $this->dropTables('books','authors');
 178          }
 179      }
 180
 181      ?>
 182
 183 Eso es suficiente para que Akelos cree la estructura de tu base de datos. Si sólo especificas el nombre de la columna, Akelos determinará el tipo de datos basándose en convenciones de normalización de base de datos. Si deseas tener total control de la configuración de tus tablas, puedes usar [sintaxis Datadict de php Adodb](http://phplens.com/lens/adodb/docs-datadict.htm)
 184
 185 Ahora ejecuta el instalador, con el comando:
 186
 187     ./script/migrate Booklink install
 188
 189 y eso creará las tablas definidas en el instalador. Si estás usando una base de datos MySQL, creará las siguientes estructuras:
 190
 191 **TABLA BOOKS**
 192
 193     +--------------+--------------+------+-----+----------------+
 194     | Field        | Type         | Null | Key | Extra          |
 195     +--------------+--------------+------+-----+----------------+
 196     | id           | int(11)      | NO   | PRI | auto_increment |
 197     | title        | varchar(255) | YES  |     |                |
 198     | description  | longtext     | YES  |     |                |
 199     | author_id    | int(11)      | YES  | MUL |                |
 200     | published_on | date         | YES  |     |                |
 201     | updated_at   | datetime     | YES  |     |                |
 202     | created_at   | datetime     | YES  |     |                |
 203     +--------------+--------------+------+-----+----------------+
 204
 205 **TABLA AUTHORS**
 206
 207     +--------------+--------------+------+-----+----------------+
 208     | Field        | Type         | Null | Key | Extra          |
 209     +--------------+--------------+------+-----+----------------+
 210     | id           | int(11)      | NO   | PRI | auto_increment |
 211     | name         | varchar(255) | YES  |     |                |
 212     | updated_at   | datetime     | YES  |     |                |
 213     | created_at   | datetime     | YES  |     |                |
 214     +--------------+--------------+------+-----+----------------+
 215
 216 Modelos, Vistas y Controladores
 217 ------------------------------------------------------
 218
 219 Akelos sigue el [patrón de diseño MVC](http://en.wikipedia.org/wiki/Model-view-controller) para organizar tu aplicación.
 220
 221 ![Diagrama MVC de Akelos.](http://svn.akelos.org/trunk/docs/images/akelos_mvc-es.png)
 222
 223 ### Los archivos de tu aplicación y las convenciones de nomenclatura de Akelos ###
 224
 225 Éstas son las convenciones que permiten mantener la filosofía de convención sobre configuración de Akelos.
 226
 227 #### Modelos ####
 228
 229  * **Ruta:** /app/models/
 230  * **Nombre de la clase:** singular, separando palabras sin espacios y con mayúsculas (CamelCase) *(BankAccount, Person, Book)*
 231  * **Nombre del fichero:** singular, separando palabras con guiones bajos  *(bank_account.php, person.php, book.php)*
 232  * **Nombre de la tabla:** plural,  separando palabras con guiones bajos *(bank_accounts, people, books)*
 233
 234 #### Controladores ####
 235
 236  * **Ruta:** */app/controllers/*
 237  * **Nombre dela clase:** singular o plural, separando palabras sin espacios y con mayúsculas (CamelCase), termina en `Controller` *(AccountController, PersonController)*
 238  * **Nombre del fichero:** singular o pural, separando palabras con guiones bajos, termina en `_controller` *(`account_controller.php`, `person_controller.php`)*
 239
 240 #### Vistas ####
 241
 242  * **Ruta:** /app/views/ + *nombre_del_controlador_con_guiones_bajos/* *(app/views/person/)*
 243  * **Nombre del fichero:** nombre de la acción, minusculas *(app/views/person/show.tpl)*
 244
 245
 246 Scaffolding (Andamiaje) en Akelos
 247 ------------------------------------------
 248
 249 Akelos incluye generadores de código que pueden reducir el tiempo de desarrollo al crear código *scaffold* (andamio) que puedes utilizar como punto de partida para tu aplicación. El proceso de scaffolding genera automáticamente el código necesario para realizar tareas habituales de **altas**, **bajas** y **modificación** de registros en las tablas de la base de datos de la aplicación.
 250
 251 ### Intimando con el generador de Scaffolds  ###
 252
 253 Ahora generarás el esqueleto base para interactuar con la base de datos **booklink** creada en el paso anterior. Para generar este esqueleto de forma rápida puedes usar el *generador de scaffolds* de esta manera:
 254
 255     ./script/generate scaffold Book
 256
 257 y
 258
 259     ./script/generate scaffold Author
 260
 261 Esto generará un montón de archivos y carpetas que ¡funcionan de verdad!. ¿No me crees? Pruébalo tu mismo. Dirige tu navegador a  [http://localhost/booklink/author](http://localhost/booklink/author) y [http://localhost/booklink/books](http://localhost/booklink/books) para empezar a agregar autores y libros. Crea algunos registros y vuelve aquí para saber que es lo que ocurre internamente.
 262
 263
 264 El flujo de trabajo de Akelos
 265 ------------------------------------------
 266
 267 Esta es una pequeña explicación del flujo de trabajo subyacente para una llamada a la siguiente URL  `http://localhost/booklink/book/show/2`
 268
 269  1. Akelos dividirá la petición en tres parámetros  de acuerdo a tu archivo `/config/routes.php` (más sobre este tema en un instante)
 270   * controlador: book
 271   * acción: show
 272   * id: 2
 273
 274  2. Una vez que Akelos conoce las partes de la petición buscará el archivo `/app/controllers/book_controller.php` y si lo encuentra instanciará la clase `BookController`
 275
 276  3. El controlador buscará un modelo que coincida con el parámetro `controlador` de la petición. En este caso buscará `/app/models/book.php`. Si lo encuentra, creará una instancia del modelo en el atributo del controlador  `$this->Book`. si hay un `id` en la petición, buscará en la tabla Books de la base de datos el registro con id 2 y eso permanecerá en `$this->Book`
 277
 278  4. Ahora llamará a la acción `show` de la clase `BookController` si estuviese disponible.
 279
 280  5. Una vez que la acción `show` se ejecuta, el controlador buscará el archivo de la vista en `/app/views/book/show.tpl` y renderizará el resultado en la variable `$content_for_layout`.
 281
 282  6. Ahora Akelos buscará un layout con el mismo nombre que el controlador en `/app/views/layouts/book.tpl`. Si lo encuentra renderizará el mismo, insertando el contenido de `$content_for_layout` y enviando la salida al navegador.
 283
 284 Esto podría ayudarte a comprender la forma en la que Akelos maneja tus peticiones, así que estamos listos para modificar la aplicación base.
 285
 286
 287 Relacionando libros y autores
 288 ----------------------------
 289
 290 Ahora vamos a enlazar autores y libros (trataremos asociaciones más complejas en futuros tutoriales). Para conseguir esto, usarás la columna `author_id` que definiste en la base de datos.
 291
 292 Ahora necesitarás indicar a tus modelos cómo se relacionan unos con otros, de esta forma
 293
 294 */app/models/book.php*
 295
 296     <?php
 297
 298     class Book extends ActiveRecord
 299     {
 300         var $belongs_to = 'author'; // <- declarando la asociación
 301     }
 302
 303     ?>
 304
 305 */app/models/author.php*
 306
 307     <?php
 308
 309     class Author extends ActiveRecord
 310     {
 311         var $has_many = 'books'; // <- declarando la asociación
 312     }
 313
 314     ?>
 315
 316 Ahora que los modelos son conscientes de la existencia del otro necesitas modificar el controlador book, para que incluya las instancias de los modelos `author` y `book`
 317
 318 */app/controllers/book_controller.php*
 319
 320     <?php
 321
 322     class BookController extends ApplicationController
 323     {
 324         var $models = 'book, author'; // <- hace que estos modelos estén dispobibles
 325
 326         // ... más código del BookController
 327
 328         function show()
 329         {
 330             // Reemplaza "$this->book = $this->Book->find(@$this->params['id']);"
 331             // con esto, para encontrar a los autores relacionados
 332             $this->book = $this->Book->find(@$this->params['id'], array('include' => 'author'));
 333         }
 334
 335         // ... más código del BookController
 336     }
 337
 338 El próximo paso es mostrar los autores disponibles en el momento de crear o editar un libro. Esto puede lograrse mediante el uso de `$form_options_helper` insertando el siguiente código
 339 justo después de `<?=$active_record_helper->error_messages_for('book');?>` en el archivo  */app/views/book/_form.tpl*
 340
 341     <p>
 342         <label for="author">_{Author}</label><br />
 343         <?=$form_options_helper->select('book', 'author_id', $Author->collect($Author->find(), 'name', 'id'));?>
 344     </p>
 345
 346 Si aún no has creado ningún autor necesitarás crear algunos ahora mismo para ver de lo que hablamos. Luego visita http://locahost/boolink/book/add para comprobar que nos muestra una lista para seleccionar autores. Adelante, crea un libro seleccionando un autor de la lista.
 347
 348 Parece ser que el autor se ha guardado, pero no se muestra en la vista `app/views/book/show.tpl`. deberás añadir este código después de `<? $content_columns = array_keys($Book->getContentColumns()); ?>`
 349
 350     <label>_{Author}:</label> <span class="static">{book.author.name?}</span><br />
 351
 352 Ahora seguramente estarás poniendo el grito en el cielo sobre la extraña sintaxis de `_{Author}` y `{book.author.name?}` syntax. Eso, en realidad es  [Sintags](http://www.bermi.org/projects/sintags), un pequeño grupo de reglas que ayudan a escribir vistas más limpias y que será compilado como PHP standard.
 353
 354 Comentarios Finales
 355 --------------------
 356
 357 Esto es todo por ahora, iré mejorando este tutorial de vez en cuando, para agregar algunas funcionalidades que faltan, como:
 358
 359  * validaciones
 360  * rutas (routes)
 361  * filtros
 362  * callbacks
 363  * transacciones
 364  * consola
 365  * AJAX
 366  * helpers
 367  * servicios web
 368  * pruebas unitarias (testing)
 369  * distribución
 370  * y mucho más...
 371
 372
 373 ------------
 374
 375 Traducción realizada por: Matias Quaglia