Guides.rubyonrails.org

1 Fundamentos de la línea de comandos

Hay unos cuantos comandos que son absolutamente críticos para el uso diario de Rails. En el orden en que probablemente los utilices son:

• rails console
• rails server
• rake
• rails generate
• rails dbconsole
• rails new app_name

Creemos una aplicación Rails sencilla para ver cada uno de estos comandos en su contexto.

1.1 rails new

Lo primero que vamos a hacer es crear una nueva aplicación Rails ejecutando el comando rails new después de instalar Rails.

$ rails new commandsapp create create README.rdoc create .gitignore create Rakefile create config.ru create Gemfile create app ... create tmp/cache create tmp/pids create vendor/plugins create vendor/plugins/.gitkeep

¡Rails te instalará lo que parece una cantidad enorme de cosas para un comando tan pequeño! Ya tienes toda la estructura de directorios de Rails con todo el código que necesitas para ejecutar nuestra sencilla aplicación nada más sacarla de la caja.

1.2 rails server

El comando rails server lanza un pequeño servidor web llamado WEBrick que viene incluido con Ruby. Lo utilizarás siempre que quieras acceder a tu aplicación a través de un navegador web.

Sin más trabajo, el servidor Rails ejecutará nuestra nueva y brillante aplicación Rails:

Con sólo tres comandos hemos creado un servidor Rails que escucha en el puerto 3000. Ve a tu navegador y abre http://localhost:3000, verás una aplicación Rails básica ejecutándose.

También puedes usar el alias «s» para iniciar el servidor: rails s.

El servidor puede ejecutarse en un puerto diferente usando la opción -p. El entorno de desarrollo por defecto puede cambiarse usando -e.

$ rails server -e production -p 4000

La opción -b vincula Rails a la ip especificada, por defecto es 0.0.0.0. Puedes ejecutar un servidor como demonio pasando la opción -d.

1.3 rails generate

El comando rails generate usa plantillas para crear un montón de cosas. Al ejecutar rails generate por sí mismo se obtiene una lista de generadores disponibles:

También puedes usar el alias «g» para invocar el comando generator: rails g.

Usar generadores te ahorrará una gran cantidad de tiempo al escribir código boilerplate, código necesario para que la app funcione.

Hagamos nuestro propio controlador con el generador de controladores. Pero, ¿qué comando debemos utilizar? Preguntemos al generador:

El generador de controladores espera parámetros en forma de generar controlador ControllerName action1 action2. Hagamos un controlador de Saludos con una acción de hola, que nos dirá algo bonito.

$ rails generate controller Greetings hello create app/controllers/greetings_controller.rb route get "greetings/hello" invoke erb create app/views/greetings create app/views/greetings/hello.html.erb invoke test_unit create test/functional/greetings_controller_test.rb invoke helper create app/helpers/greetings_helper.rb invoke test_unit create test/unit/helpers/greetings_helper_test.rb invoke assets create app/assets/javascripts/greetings.js invoke css create app/assets/stylesheets/greetings.css

¿Qué ha generado todo esto? Se aseguró de que hubiera un montón de directorios en nuestra aplicación, y creó un archivo de controlador, un archivo de vista, un archivo de prueba funcional, un helper para la vista, un archivo javascript y un archivo de hoja de estilos.

Comprueba el controlador y modifícalo un poco (en app/controllers/greetings_controller.rb):

class GreetingsController < ApplicationController def hello @message = "Hello, how are you today?" endend

Luego la vista, para mostrar nuestro mensaje (en app/views/greetings/hello.html.erb):

<h1>A Greeting for You!</h1><p><%= @message %></p>

Enciende tu servidor usando rails server.

$ rails server=> Booting WEBrick...

La URL será http://localhost:3000/greetings/hello.

Rails viene con un generador para modelos de datos también.

Pero en lugar de generar un modelo directamente (lo que haremos más adelante), vamos a configurar un andamio. Un scaffold en Rails es un conjunto completo de modelo, migración a la base de datos para ese modelo, controlador para manipularlo, vistas para ver y manipular los datos, y un conjunto de pruebas para cada uno de los anteriores.

Vamos a configurar un recurso sencillo llamado «HighScore» que llevará la cuenta de nuestra puntuación más alta en los videojuegos que juguemos.

El generador comprueba que existen los directorios para modelos, controladores, helpers, layouts, tests funcionales y unitarios, hojas de estilo, crea las vistas, el controlador, el modelo y la migración a la base de datos para HighScore (creando la tabla y los campos de high_scores), se encarga de la ruta para el recurso, y de los nuevos tests para todo.

La migración requiere que migremos, es decir, que ejecutemos algo de código Ruby (que vive en ese 20100209025147_create_high_scores.rb) para modificar el esquema de nuestra base de datos. ¿Qué base de datos? La base de datos sqlite3 que Rails creará por nosotros cuando ejecutemos el comando rake db:migrate. Hablaremos más a fondo de Rake dentro de un rato.

Veamos la interfaz que Rails ha creado para nosotros.

$ rails server

Ve a tu navegador y abre http://localhost:3000/high_scores, ahora podemos crear nuevas puntuaciones altas (¡55,160 en Space Invaders!)

1.4 consola rails

El comando consola te permite interactuar con tu aplicación Rails desde la línea de comandos. En la parte inferior, la consola de rails utiliza IRB, así que si alguna vez lo has usado, estarás como en casa. Esto es útil para probar ideas rápidas con el código y cambiar datos del lado del servidor sin tocar el sitio web.

También puedes usar el alias «c» para invocar la consola: rails c.

Si quieres probar algún código sin cambiar ningún dato, puedes hacerlo invocando rails console –sandbox.

$ rails console --sandboxLoading development environment in sandbox (Rails 3.1.0)Any modifications you make will be rolled back on exitirb(main):001:0>

1.5 rails dbconsole

rails dbconsole averigua qué base de datos estás usando y te lleva a la interfaz de línea de comandos que usarías con ella (¡y también averigua los parámetros de línea de comandos que debes darle!). Soporta MySQL, PostgreSQL, SQLite y SQLite3.

También puedes usar el alias «db» para invocar la dbconsole: rails db.

1.6 rails plugin

El comando rails plugin simplifica la gestión de plugins. Los plugins se pueden instalar por su nombre o por la URL de su repositorio. Necesitas tener instalado Git si quieres instalar un plugin desde un repositorio Git. Lo mismo ocurre con Subversion.

$ rails plugin install https://github.com/technoweenie/acts_as_paranoid.git+ ./CHANGELOG+ ./MIT-LICENSE......

1.7 rails runner

runner ejecuta código Ruby en el contexto de Rails de forma no interactiva. Por ejemplo:

$ rails runner "Model.long_running_method"

También puedes utilizar el alias «r» para invocar el runner: rails r.

Puedes especificar el entorno en el que debe operar el comando runner utilizando el parámetro -e.

$ rails runner -e staging "Model.long_running_method"

1.8 rails destroy

Piensa que destroy es lo contrario de generate. Descubrirá lo que hizo generate y lo deshará.

También puedes usar el alias «d» para invocar el comando destroy: rails d.

2 Rake

Rake es Ruby Make, una utilidad independiente de Ruby que reemplaza a la utilidad de Unix ‘make’, y usa un ‘Rakefile’ y archivos .rake para construir una lista de tareas. En Rails, Rake se utiliza para las tareas de administración más comunes, especialmente las más sofisticadas que se construyen a partir de otras.

Puedes obtener una lista de las tareas de Rake disponibles, que a menudo dependerán de tu directorio actual, escribiendo rake –tasks. Cada tarea tiene una descripción y debería ayudarte a encontrar lo que necesitas.

$ rake --tasks(in /home/foobar/commandsapp)rake db:abort_if_pending_migrations # Raises an error if there are pending migrationsrake db:charset # Retrieves the charset for the current environment's databaserake db:collation # Retrieves the collation for the current environment's databaserake db:create # Create the database defined in config/database.yml for the current Rails.env......rake tmp:pids:clear # Clears all files in tmp/pidsrake tmp:sessions:clear # Clears all files in tmp/sessionsrake tmp:sockets:clear # Clears all files in tmp/sockets

2.1 about

rake about da información sobre los números de versión de Ruby, RubyGems, Rails, los subcomponentes de Rails, la carpeta de tu aplicación, el nombre del entorno Rails actual, el adaptador de la base de datos de tu aplicación y la versión del esquema. Es útil cuando necesitas pedir ayuda, comprobar si un parche de seguridad puede afectarte, o cuando necesitas algunas estadísticas para una instalación Rails existente.

2.2 assets

Puedes precompilar los assets en app/assets usando rake assets:precompile y eliminar esos assets compilados usando rake assets:clean.

2.3 db

Las tareas más comunes del namespace db: Rake namespace son migrate y create, y valdrá la pena probar todas las tareas de rake de migración (up, down, redo, reset). rake db:version es útil a la hora de solucionar problemas, ya que te indica la versión actual de la base de datos.

Puedes encontrar más información sobre migraciones en la guía de Migraciones.

2.4 doc

El namespace doc: tiene las herramientas para generar documentación para tu app, documentación de la API, guías. La documentación también puede ser despojada, lo que es útil principalmente para adelgazar tu código base, como si estás escribiendo una aplicación Rails para una plataforma embebida.

• rake doc:app genera documentación para tu aplicación en doc/app.
• rake doc:guides genera guías Rails en doc/guides.
• rake doc:rails genera documentación de la API para Rails en doc/api.
• rake doc:plugins genera documentación de la API para todos los plugins instalados en la aplicación en doc/plugins.
• rake doc:clobber_plugins elimina la documentación generada para todos los plugins.

2.5 notes

rake notes buscará en tu código comentarios que empiecen por FIXME, OPTIMIZE o TODO. La búsqueda se realiza en archivos con extensión .builder, .rb, .erb, .haml y .slim tanto para las anotaciones por defecto como para las personalizadas.

Si está buscando una anotación específica, digamos FIXME, puede utilizar rake notes:fixme. Tenga en cuenta que tiene que poner en minúsculas el nombre de la anotación.

También puede usar anotaciones personalizadas en su código y listarlas usando rake notes:custom especificando la anotación usando una variable de entorno ANNOTATION.

$ rake notes:custom ANNOTATION=BUG(in /home/foobar/commandsapp)app/model/post.rb: * Have to fix this one before pushing!

2.6 routes

rake routes listará todas las rutas definidas, lo que resulta útil para localizar problemas de enrutamiento en la aplicación, o para tener una buena visión general de las URLs de una aplicación con la que estamos tratando de familiarizarnos.

2.7 test

Rails viene con una suite de pruebas llamada Test::Unit. Rails debe su estabilidad al uso de pruebas. Las tareas disponibles en el espacio de nombres test: ayudan a ejecutar las diferentes pruebas que, con suerte, escribiremos.

2.8 tmp

El directorio Rails.root/tmp es, al igual que el directorio /tmp de *nix, el lugar donde se guardan los archivos temporales como las sesiones (si se utiliza un almacén de archivos), los archivos de identificación de procesos y las acciones en caché.

Las tareas con espacio de nombres tmp: le ayudarán a limpiar el directorio Rails.root/tmp:

2.9 Miscelánea

• rake stats es genial para mirar las estadísticas de su código, mostrando cosas como KLOCs (miles de líneas de código) y su relación de código a la prueba.
• rake secret le dará una clave pseudo-aleatoria para utilizar para su secreto de sesión.
• rake time:zones:all lista todas las zonas horarias que conoce Rails.

3 La línea de comandos avanzada de Rails

Un uso más avanzado de la línea de comandos se centra en encontrar opciones útiles (incluso sorprendentes a veces) en las utilidades, y adaptarlas a tus necesidades y flujo de trabajo específico. A continuación se enumeran algunos trucos bajo la manga de Rails.

3.1 Rails con bases de datos y SCM

Cuando creamos una nueva aplicación Rails, tenemos la opción de especificar qué tipo de base de datos y qué tipo de sistema de gestión de código fuente va a utilizar nuestra aplicación. Esto nos ahorrará unos minutos, y seguramente muchas pulsaciones.

Veamos lo que la opción –git y la opción –database=postgresql harán por nosotros:

Tenemos que crear el directorio gitapp e inicializar un repositorio git vacío antes de que Rails añada los ficheros que ha creado a nuestro repositorio. Veamos lo que pone en la configuración de nuestra base de datos:

También ha generado algunas líneas en nuestra configuración database.yml correspondientes a nuestra elección de PostgreSQL como base de datos.

3.2 Servidores con diferentes backends

Mucha gente ha creado un gran número de servidores web diferentes en Ruby, y muchos de ellos pueden utilizarse para ejecutar Rails. Desde la versión 2.3, Rails utiliza Rack para servir sus páginas web, lo que significa que se puede utilizar cualquier servidor web que implemente un manejador Rack. Esto incluye WEBrick, Mongrel, Thin y Phusion Passenger (por nombrar algunos).

Para utilizar un servidor diferente, sólo hay que instalar su gema y utilizar su nombre como primer parámetro de rails server:

Feedback

Te animamos a que ayudes a mejorar la calidad de esta guía.

Si ves algún error tipográfico o fáctico que confíes en parchear, por favor clona el repositorio de rails y abre un nuevo pull request. También puedes pedir derechos de commit en docrails si planeas enviar varios parches. Los commits se revisan, pero eso ocurre después de que hayas enviado tu contribución. Este repositorio se fusiona con el maestro periódicamente.

También puede encontrar contenido incompleto, o cosas que no están actualizadas. Por favor, añade cualquier documentación que falte para el master. Revisa las Guías de Ruby on Rails para el estilo y las convenciones.

Si por alguna razón ves algo que hay que arreglar pero no puedes hacerlo tú mismo, por favor, abre una incidencia.

Y por último, pero no por ello menos importante, cualquier tipo de discusión sobre la documentación de Ruby on Rails es bienvenida en la lista de correo rubyonrails-docs.