¡La versión 2.0 de Play ya está lista! Ayúdanos a traducir la documentación de la útlima versión y sigue nuestro progreso.

Manuales, tutoriales & referencias

Consulte

Contenidos

Elija la versión

Buscar

Busque con google

Libros

Iniciando el proyecto

Introducción

En este tutorial aprenderá a utilizar el framework Play desarrollando una aplicación web de principio a fin. En esta aplicación, utilizaremos todas las prestaciones que precisaría en un proyecto real, y al mismo tiempo presentaremos las “mejores prácticas” para desarrollar una aplicación con el framework Play.

Hemos dividido este tutorial en varias partes independientes. En cada parte presentaremos prestaciones más complejas, abarcando todo lo que precisa un proyecto real: validación, manejo de errores, un esquema de seguridad, una batería de pruebas automáticas, una atractiva interface web, una área de administración de datos, etc.

Puede utilizar todo el código incluido en este tutorial para sus propios proyectos. Lo alentamos a copiar y pegar partes del código o incluso a “robarse” módulos enteros.

El proyecto

Hemos elegido crear un nuevo sitio de blogs. Sabemos que no es una elección demasiado original, pero nos permitirá explorar buena parte de la funcionalidad propia de cualquier aplicación web moderna.

Para hacer el tutorial más interesante, manejaremos varios usuarios con diversos roles (editor, administrador).

Llamaremos a este proyecto de sistema de blog yabe. (Yet Another Blog Engine, que en castellano significaría algo así como “Otro motor de blogs más”)

Este tutorial también es distribuido como una aplicación de ejemplo. Puede encontrar el código de la aplicación terminada en el directorio samples-and-tests/yabe/ de la instalación de Play.

Prerequisitos

Antes que nada, asegúrese de contar con una instación de Java funcionando. Play requiere Java 5 o superior.

Dado que a menudo utilizaremos la línea de comando, será mejor utilizar un sistema operativo al estilo de Unix. Si usted utiliza un sistema operativo Windows, también podrá trabajar sin problemas, tan sólo tendrá que tipear algunos comandos en la línea de comandos.

Asumimos que Ud. ya posee cierto conocimiento de Java y de desarrollo de aplicaciones Web (en especial HTML, CSS y JavaScript). Sin embargo, no necesita tener conocimiento de todos los componentes de la Edición Empresarial de Java (JEE). Play es un framework ‘full-stack’, lo que significa que trae todo lo necesario para desarrollar sus aplicaciones web y encapsula todas las API de Java necesarias. No es preciso saber cómo configurar una administrador de entidades de JPA, ni tampoco saber cómo poner en producción un componente JEE.

Claro que necesitará contar al menos con un editor de texto. Si está acostumbrado a utilizar un IDE completo de Java como Eclipse o Netbeans por supuesto que puede utilizarlo. Sin embargo, con Play puede desarrollar aplicaciones con un simple editor como Textmate, Emacs o VI, gracias a que el framework se encarga de la compilación y puesta en producción de manera transparente, como veremos más adelante...

Más adelante, en este tutorial, también utilizaremos el servidor web Lighthpt y MySql para mostrar cómo instalar una aplicación Play en modo ‘production’. Pero Play también le permite trabajar sin estos componentes, así que no hay ningún problema si no puede instalarlos.

Instalación del framework Play

La instalación es muy simple. Tan sólo tiene que descargar la última versión de la distribución binaria del framework y descomprimirla en alguna carpeta.

Si está utilizando Windows, es generalmente una buena idea evitar espacios en el camino de la carpeta, de manera que, por ejemplo, c:\play sería una mejor elección que c:\Documents And Settings\user\play.

Para trabajar con mayor comodidad resulta conveniente agregar el directorio de la instalación de Play al path. Esto le permitirá tipear play en la línea de comandos sin tener que estar situado en la carpeta del framework ni hacer referencia a ella. Para verificar la instalación de Play, simplemente abra una línea de comandos y tipee play; debería aparecer la ayuda básica del comando play.

Creando el proyecto

Ahora que Play ha sido instalado, es hora de crear la aplicación de blogs. Crear una aplicación de Play es muy simple, ya que la utilidad de línea de comando de play se encarga de todo. Esto permite que todas las aplicaciones de Play mantengan una misma estructura de proyecto estandarizada.

Abra una consola de comandos y tipee:

~$ play new yabe

Le preguntará el nombre completo de la aplicación. Tipee Yet Another Blog Engine.

El comando play new crea un nuevo directorio yabe/ y crea una serie de directorios y archivos en él, siendo los más importantes:

app/ contiene el núcleo de la aplicación, separado en directorios para los modelos, los controladores y las vistas. También puede contener otros paquetes de Java. Aquí es donde residen los archivos fuentes .java.

conf/ contiene todos los archivos de configuración de la aplicación, en especial el archivo principal de configuración application.conf, el archivo routes que contiene la definición de las rutas HTTP y el archivo messages utilizado para la internacionalización de las aplicaciones.

lib/ contiene todas las librerías opcionales de java empaquetadas como archivos .jar común y corrientes.

public/ contiene todos los recursos públicamente disponibles de la aplicación, lo que incluye archivos JavaScript, hojas de estilo (archivo .css) y directorios con imágenes.

test/ contiene las pruebas de la aplicación. Las pruebas pueden ser escritas como pruebas unitarias de JUnit o como pruebas de Selenium.

Dado que Play utiliza UTF-8 como único estándar de codificación, es importante asegurarse de que todos los archivos de estos directorios estén codificados utilizando este juego de caracteres. Asegúrese de configurar su editor de texto de la manera correspondiente.

Ahora si usted cuenta con cierta experiencia desarrollando aplicaciones en Java, seguramente se estará preguntando a dónde van a parar los archivos .class. Pues bien, a ningún lado: Play no utiliza ningún archivo .class; en cambio lo que hace es leer los archivos fuente de Java directamente, utilizando el compilador Java de Eclipse para recompilar el código fuente a medida que usted lo modifica.

Esto nos permite realizar dos cosas muy importantes en el proceso de desarrollo. La primera es que Play detectará cuando usted modifica algún archivo fuente y automáticamente lo recompilará y volverá a cargar en tiempo de ejecución. La segunda que que cuando ocurra alguna excepción de Java, Play creará un reporte de error mucho más detallado, mostrándole incluso la línea exacta de código que generó el error.

De hecho play mantiene un cache del bytecode de la aplicación en la carpeta tmp/, pero únicamente a los efectos de acelerar el proceso de reiniciar grandes aplicaciones. Puede descartar este cache utilizando el comando play clean si lo precisa.

Ejecutando la aplicación

Ahora podemos probar la aplicación que acabamos de crear. Vuelva a la linea de comandos, vaya a la carpeta yabe/ que acabamos de crear, y tipee play run. Play cargará la aplicación e iniciará un servidor web en el puerto 9000.

Puede ver la nueva aplicación abriendo un explorador web en http://localhost:9000. Cada nueva aplicación viene con una página estándar de bienvenida que simplemente le dice que la aplicación fue creada con éxito.

Veamos cómo hace la aplicación para mostrar esta página de bienvenida.

El punto de entrada a su aplicación es el archivo conf/routes. Este archivo define los URLs con lo cuales se puede acceder a la aplicación. Si abre el archivo routes verá la primera ruta definida:

GET     /           Application.index

Esta línea simplemente le dice a play que cuando el servidor web reciba una paquete HTTP con un pedido GET para el camino /, debe ejecutar el método Java Application.index. En este caso Application.index es una manera abreviada de referirnos a controllers.Application.index, ya que el paquete controllers se encuentra implícito en este contexto.

Cuando usted crea una aplicación Java de escritorio, generalmente utiliza un único punto de entrada definido por un método como:

public static void main(String[] args) {
  ... 
}

Por el contrario, una aplicación hecha con Play, tiene múltiples puntos de entrada, uno por cada URL. Llamamos a estos métodos métodos de acción o action methods. Los métodos de acción son definidos en clases especiales a las que llamamos controladores o controllers.

Veamos qué aspecto tiene el controlador controllers.Application. Abra el archivo yabe/app/controllers/Application.java:

package controllers;
 
import play.mvc.*;
 
public class Application extends Controller {
 
    public static void index() {
        render();
    }
 
}

Note que la clase controladora hereda de play.mvc.Controller. Esta clase provee numerosos métodos sumamente útiles para los controladores, como el método render() que utilizamos en la acción index.

La acción index está definida como un método público, estático y que retorna void. Esta es la manera de definir action methods. Dichos métodos son estáticos, porque las clases de controladores nunca son instanciadas. Son públicos para permitir al framework invocarlos en respuesta a un URL. Y siempre retornan void.

La acción index es my simple: llama al método render() el cual le dice a play que procese un template y muestre su resultado. Usar un template es la manera más común (si bien no es la única) de generar una respuesta HTTP.

Los templates son simples archivos de texto que residen en la carpeta /app/views. Dado que no especificamos ningún template, utilizará el template por defecto para esta acción: Application/index.html

Para ver cómo es el template, abra el archivo /yabe/app/views/Application/index.html:

#{extends 'main.html' /}
#{set title:'Home' /}
 
#{welcome /}

El contenido del template es bastante liviando. De hecho, lo único que ve son tags de Play. Los tags de Play son similares a los de JSP. En este caso, el tag #{welcome /} es el encargado de generar el mensaje de bienvenida que ve en el explorador.

El tag @#{extends /} le indica a Play que este template hereda de otro llamado main.html. La herencia de tempaltes es un concepto sumamemente poderoso, que le permite crear páginas complejas reutilizando partes comunes a todos.

Abra el template /yabe/app/views/main.html:

<!DOCTYPE html>
<html>
  <head>
    <title>#{get 'title' /}</title>
    <meta charset="${_response_encoding}">
    <link rel="stylesheet" media="screen"
      href="@{'/public/stylesheets/main.css'}">
    #{get 'moreStyles' /}
    <link rel="shortcut icon" type="image/png"
      href="@{'/public/images/favicon.png'}">
    <script type="text/javascript" charset="${_response_encoding}"
      src="@{'/public/javascripts/jquery-1.5.2.min.js'}"></script>
    #{get 'moreScripts' /}
  </head>
  <body>
    #{doLayout /}
  </body>
</html>

Note la llamada al tag #{doLayout /} cerca del final del código. Ahí es donde será insertado el contenido de Application/index.html.

Podemos editar el archivo del controlador para ver como Play automáticamente lo carga. Abra el archivo yabe/app/controllers/Application.java en un editor de texto y agregue un error quitando el punto y coma que se encuentra a continuación de la llamada al método render().

public static void index() {
    render()
}

Vaya al browser y refresque la página. Puede ver que Play detectó el cambio e intentó volver a cargar el controlador Application. Pero, debido a que usted cometió un error, recibe un mensaje de error de compilación.

Bueno, corrijamos el error e introduzcamos una modificación real:

public static void index() {
    System.out.println("Yop");
    render();
}

Esta vez Play volverá a cargar el controlador, remplazando el anterior código en la JVM. Ahora, con cada llamado al URL / mostrará el mensaje ‘Yop’ en la consola.

Ahora puede sacar esta línea, y editar el template yabe/app/views/Application/index.html para remplazar el mensaje de bienvenida:

#{extends 'main.html' /}
#{set title:'Home' /}
 
<h1>A blog will be there</h1>

Al igual que con los cambios efectuados en el código fuente de Java, simplemente refresque el explorador para ver los cambios.

Ahora comenzaremos a desarrollar la aplicación de blogs. Puede continuar trabajando en el editor de texto o abrir un IDE completo como Elicpse o NetBeans. Si desea configurar un IDE de Java, vea Configurando su IDE favorito.

Configurando la base de datos

Una cosa más antes de empezar a escribir código. Para almacenar la información de los blogs, precisaremos una base de datos. Para el desarrollo, Play viene con una base de datos autónoma llamada H2. Esta es la mejor manera de comenzar un proyecto antes de pasar a una base de datos más robusta en caso de ser necesario. Puede elegir trabajar con una base de datos en memoria o en un archivo, a fin de mantener la información al reiniciar la aplicación.

Al principio, haremos mútliples pruebas y cambios en el modelo de datos de la aplicación. Por esa razón, es mejor utilizar una base de datos en memoria a fin de comenzar siempre con un conjunto de datos limpio.

Para configurar una base de datos abra el archivo yabe/conf/application.conf y descomente la siguiente línea:

db=mem

Como puede ver en los comentarios del archivo de configuración, puede fácilmente utilizar cualquier base de datos para la cual exista un driver JDBC, e incluso configurar también un pool de conexiones.

Esta guía está diseñada para funcionar con la base de datos en memoria provista por play; instrucciones para utilizar JPA con otros bases de datos exceden el alcance de este documento.

Ahora vuelva al explorador y refresque la página de bienvenida. Play automáticamente iniciará la base de datos. Verifique que la siguiente línea esté presente en el log de la aplicación:

INFO  ~ Connected to jdbc:h2:mem:play

Utilizando un sistema de control de código fuente para llevar control de los cambios

Cuando trabaja en un proyecto es recomendable que utilice un sistema de control de código fuente (version control system – VCS) para almacenar el código de la aplicación. Esto le permitirá volver atrás a una versión anterior si los cambios introducidos han roto algo, trabajar con un equipo de personas y brindar acceso a las distintas versiones de la aplicación.

Al guardar una aplicación Play en un VCS, es importante excluir las carpetas tmp/, modules/, lib/, test-result/ y logs/.

Bazaar

Aquí utilizaremos Bazaar a modo de ejemplo. Bazaar es un sistema de control de código fuente distribuido.

La instalación de Bazaar está más allá del objetivo de este tutorial, pero es muy simple. Una vez que tenga una instalación de Bazaar funcionando, vaya al directorio de la aplicación, e inicialice el versionado de la aplicación tipeando:

$ bzr init
$ bzr ignore tmp
$ bzr ignore modules
$ bzr ignore lib
$ bzr ignore test-result
$ bzr ignore logs

Ahora podemos confirmar (commit) la primera versión de nuestro sistema de blogs:

$ bzr add
$ bzr commit -m "YABE inital version"

Git

Git es otro sistema de control de código fuente distribuido. Para mayor información revise su documentación.

Cree un directorio de trabajo de git en la carpeta principal de la aplicación.

$ git init

Cree un archivo .gitignore con el siguinte contenido:

/tmp
/modules
/lib
/test-result
/logs

Agregue los archivos de la aplicación y confírmelos (commit):

$ git add .
$ git commit -m "YABE initial version"

La versión 1 de nuestra aplicación ha sido grabada, y ya contamos con una buena base para continuar con nuestro proyecto.

Vaya a Una primera iteración con el modelo de datos.