Guides.rubyonrails.org

1 Bases de la ligne de commande

Il existe quelques commandes qui sont absolument essentielles à votre utilisation quotidienne de Rails. Dans l’ordre de la fréquence à laquelle vous les utiliserez probablement, ce sont :

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

Créons une application Rails simple pour passer en revue chacune de ces commandes en contexte.

1.1 rails new

La première chose que nous allons vouloir faire est de créer une nouvelle application Rails en exécutant la commande rails new après avoir installé 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 vous configurera avec ce qui semble être une énorme quantité de choses pour une si petite commande ! Vous avez maintenant toute la structure de répertoire de Rails avec tout le code dont vous avez besoin pour exécuter notre application simple dès le départ.

1.2 rails server

La commande rails server lance un petit serveur web nommé WEBrick qui est fourni avec Ruby. Vous l’utiliserez chaque fois que vous voudrez accéder à votre application via un navigateur web.

Sans autre travail, le serveur rails exécutera notre nouvelle application Rails brillante:

Avec seulement trois commandes, nous avons fouetté un serveur Rails écoutant sur le port 3000. Allez dans votre navigateur et ouvrez http://localhost:3000, vous verrez une application Rails de base s’exécuter.

Vous pouvez également utiliser l’alias « s » pour démarrer le serveur : rails s.

Le serveur peut être exécuté sur un port différent en utilisant l’option -p. L’environnement de développement par défaut peut être modifié en utilisant -e.

$ rails server -e production -p 4000

L’option -b lie Rails à l’ip spécifié, par défaut c’est 0.0.0.0. Vous pouvez exécuter un serveur comme un démon en passant une option -d.

1.3 rails generate

La commande rails generate utilise des modèles pour créer tout un tas de choses. L’exécution de rails generate par elle-même donne une liste de générateurs disponibles :

Vous pouvez également utiliser l’alias « g » pour invoquer la commande de générateur : rails g.

L’utilisation des générateurs vous fera gagner un temps considérable en écrivant du code boilerplate, du code nécessaire au fonctionnement de l’application.

Faisons notre propre contrôleur avec le générateur de contrôleur. Mais quelle commande devons-nous utiliser ? Demandons au générateur :

Le générateur de contrôleur attend des paramètres sous la forme generate controller ControllerName action1 action2. Faisons un contrôleur Greetings avec une action de hello, qui nous dira quelque chose de gentil.

$ 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

Que tout cela a-t-il généré ? Il s’est assuré qu’un tas de répertoires étaient dans notre application, et a créé un fichier de contrôleur, un fichier de vue, un fichier de test fonctionnel, une aide pour la vue, un fichier javascript et un fichier de feuille de style.

Vérifiez le contrôleur et modifiez-le un peu (dans app/controllers/greetings_controller.rb):

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

Puis la vue, pour afficher notre message (dans app/views/greetings/hello.html.erb):

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

Démarrez votre serveur en utilisant rails server.

$ rails server=> Booting WEBrick...

L’URL sera http://localhost:3000/greetings/hello.

Rails est livré avec un générateur pour les modèles de données aussi.

Mais au lieu de générer un modèle directement (ce que nous ferons plus tard), mettons en place un scaffold. Un scaffold dans Rails est un ensemble complet de modèle, de migration de base de données pour ce modèle, de contrôleur pour le manipuler, de vues pour visualiser et manipuler les données, et une suite de tests pour chacun des éléments ci-dessus.

Nous allons mettre en place une ressource simple appelée « HighScore » qui gardera la trace de notre meilleur score sur les jeux vidéo auxquels nous jouons.

Le générateur vérifie qu’il existe les répertoires pour les modèles, les contrôleurs, les aides, les mises en page, les tests fonctionnels et unitaires, les feuilles de style, crée les vues, le contrôleur, le modèle et la migration de la base de données pour HighScore (création de la table high_scores et des champs), s’occupe de la route pour la ressource, et de nouveaux tests pour tout.

La migration nécessite de migrer, c’est-à-dire d’exécuter du code Ruby (vivant dans ce 20100209025147_create_high_scores.rb) pour modifier le schéma de notre base de données. Quelle base de données ? La base de données sqlite3 que Rails créera pour vous lorsque nous exécuterons la commande rake db:migrate. Nous parlerons plus en profondeur de Rake dans un petit moment.

Voyons l’interface que Rails a créée pour nous.

$ rails server

Allez dans votre navigateur et ouvrez http://localhost:3000/high_scores, maintenant nous pouvons créer de nouveaux hauts scores (55 160 sur Space Invaders !)

1.4 rails console

La commande console vous permet d’interagir avec votre application Rails depuis la ligne de commande. En dessous, rails console utilise IRB, donc si vous l’avez déjà utilisé, vous serez à l’aise. Cela est utile pour tester des idées rapides avec du code et modifier des données côté serveur sans toucher au site web.

Vous pouvez également utiliser l’alias « c » pour invoquer la console : rails c.

Si vous souhaitez tester du code sans modifier aucune donnée, vous pouvez le faire en invoquant 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 détermine quelle base de données vous utilisez et vous laisse tomber dans n’importe quelle interface de ligne de commande que vous utiliseriez avec elle (et détermine les paramètres de ligne de commande à lui donner, aussi !). Elle prend en charge MySQL, PostgreSQL, SQLite et SQLite3.

Vous pouvez également utiliser l’alias « db » pour invoquer la dbconsole : rails db.

1.6 rails plugin

La commande rails plugin simplifie la gestion des plugins. Les plugins peuvent être installés par leur nom ou par l’URL de leur dépôt. Vous devez avoir Git installé si vous voulez installer un plugin à partir d’un repo Git. Il en va de même pour Subversion également.

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

1.7 rails runner

runner exécute du code Ruby dans le contexte de Rails de manière non interactive. Par exemple :

$ rails runner "Model.long_running_method"

Vous pouvez également utiliser l’alias « r » pour invoquer le runner : rails r.

Vous pouvez spécifier l’environnement dans lequel la commande runner doit fonctionner en utilisant le commutateur -e.

$ rails runner -e staging "Model.long_running_method"

1.8 rails destroy

Pensez à destroy comme l’opposé de generate. Il va comprendre ce que generate a fait, et le défaire.

Vous pouvez également utiliser l’alias « d » pour invoquer la commande destroy : rails d.

2 Rake

Rake est Ruby Make, un utilitaire Ruby autonome qui remplace l’utilitaire Unix ‘make’, et utilise un ‘Rakefile’ et des fichiers .rake pour construire une liste de tâches. Dans Rails, Rake est utilisé pour les tâches d’administration courantes, en particulier les tâches sophistiquées qui se construisent les unes à partir des autres.

Vous pouvez obtenir une liste des tâches Rake à votre disposition, qui dépendra souvent de votre répertoire actuel, en tapant rake –tasks. Chaque tâche a une description, et devrait vous aider à trouver ce dont vous avez besoin.

$ 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 donne des informations sur les numéros de version de Ruby, RubyGems, Rails, les sous-composants de Rails, le dossier de votre application, le nom de l’environnement Rails actuel, l’adaptateur de base de données de votre application, et la version du schéma. Il est utile lorsque vous avez besoin de demander de l’aide, de vérifier si un patch de sécurité peut vous affecter, ou lorsque vous avez besoin de quelques statistiques pour une installation Rails existante.

2.2 assets

Vous pouvez précompiler les actifs dans app/assets en utilisant rake assets:precompile et supprimer ces actifs compilés en utilisant rake assets:clean.

2.3 db

Les tâches les plus courantes du db : Rake sont migrate et create, et il sera payant d’essayer toutes les tâches rake de migration (up, down, redo, reset). rake db:version est utile lors du dépannage, vous indiquant la version actuelle de la base de données.

Plus d’informations sur les migrations peuvent être trouvées dans le guide Migrations.

2.4 doc

L’espace de noms doc : a les outils pour générer la documentation pour votre app, la documentation API, les guides. La documentation peut également être dépouillée, ce qui est principalement utile pour alléger votre codebase, comme si vous écrivez une application Rails pour une plateforme embarquée.

• rake doc:app génère de la documentation pour votre application dans doc/app.
• rake doc:guides génère des guides Rails dans doc/guides.
• rake doc:rails génère de la documentation API pour Rails dans doc/api.
• rake doc:plugins génère la documentation API pour tous les plugins installés dans l’application dans doc/plugins.
• rake doc:clobber_plugins supprime la documentation générée pour tous les plugins.

2.5 notes

rake notes recherchera dans votre code les commentaires commençant par FIXME, OPTIMIZE ou TODO. La recherche se fait dans les fichiers avec l’extension .builder, .rb, .erb, .haml et .slim pour les annotations par défaut et personnalisées.

Si vous recherchez une annotation spécifique, disons FIXME, vous pouvez utiliser rake notes:fixme. Notez que vous devez mettre en minuscule le nom de l’annotation.

Vous pouvez également utiliser des annotations personnalisées dans votre code et les lister en utilisant rake notes:custom en spécifiant l’annotation à l’aide d’une variable d’environnement 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 listera toutes vos routes définies, ce qui est utile pour traquer les problèmes de routage dans votre application, ou vous donner un bon aperçu des URL dans une application avec laquelle vous essayez de vous familiariser.

2.7 test

Rails est livré avec une suite de tests appelée Test::Unit. Rails doit sa stabilité à l’utilisation de tests. Les tâches disponibles dans l’espace de nom test : aident à l’exécution des différents tests que vous allez, avec un peu de chance, écrire.

2.8 tmp

Le répertoire Rails.root/tmp est, comme le répertoire *nix /tmp, le lieu de rétention des fichiers temporaires comme les sessions (si vous utilisez un magasin de fichiers pour les fichiers), les fichiers d’id de processus et les actions mises en cache.

Les tâches de l’espace de noms tmp : vous aideront à vider le répertoire Rails.root/tmp:

2.9 Divers

• rake stats est excellent pour regarder les statistiques sur votre code, affichant des choses comme les KLOC (milliers de lignes de code) et votre ratio de code à tester.
• rake secret vous donnera une clé pseudo-aléatoire à utiliser pour votre secret de session.
• rake time:zones:all liste tous les fuseaux horaires connus de Rails.

3 La ligne de commande avancée de Rails

Une utilisation plus avancée de la ligne de commande se concentre sur la recherche d’options utiles (voire surprenantes parfois) dans les utilitaires, et l’adaptation de celles-ci à vos besoins et à votre flux de travail spécifique. Voici une liste de quelques astuces dans la manche de Rails.

3.1 Rails avec des bases de données et SCM

Lorsque vous créez une nouvelle application Rails, vous avez la possibilité de spécifier quel type de base de données et quel type de système de gestion du code source votre application va utiliser. Cela vous fera gagner quelques minutes, et certainement de nombreuses frappes au clavier.

Voyons ce qu’une option –git et une option –database=postgresql vont faire pour nous :

Nous avons dû créer le répertoire gitapp et initialiser un dépôt git vide avant que Rails n’ajoute les fichiers qu’il a créés à notre dépôt. Voyons ce qu’il a mis dans notre configuration de base de données :

Il a également généré quelques lignes dans notre configuration database.yml correspondant à notre choix de PostgreSQL pour la base de données.

3.2 serveur avec différents backends

De nombreuses personnes ont créé un grand nombre de serveurs web différents en Ruby, et beaucoup d’entre eux peuvent être utilisés pour exécuter Rails. Depuis la version 2.3, Rails utilise Rack pour servir ses pages web, ce qui signifie que tout serveur web qui implémente un gestionnaire Rack peut être utilisé. Cela inclut WEBrick, Mongrel, Thin et Phusion Passenger (pour n’en citer que quelques-uns !).

Pour utiliser un serveur différent, il suffit d’installer sa gemme, puis d’utiliser son nom pour le premier paramètre de rails server:

Feedback

Vous êtes encouragé à aider à améliorer la qualité de ce guide.

Si vous voyez des coquilles ou des erreurs factuelles que vous êtes sûr de corriger, veuillez cloner le dépôt rails et ouvrir une nouvelle demande de pull. Vous pouvez également demander des droits de commit sur docrails si vous prévoyez de soumettre plusieurs patchs. Les commits sont revus, mais cela se passe après que vous ayez soumis votre contribution. Ce dépôt est cross-merged avec master périodiquement.

Vous pouvez également trouver du contenu incomplet, ou des choses qui ne sont pas à jour. S’il vous plaît, ajoutez toute documentation manquante pour master. Consultez les directives des guides Ruby on Rails pour le style et les conventions.

Si pour une raison quelconque vous repérez quelque chose à corriger mais que vous ne pouvez pas le patcher vous-même, veuillez ouvrir un problème.

Et enfin, tout type de discussion concernant la documentation de Ruby on Rails est très bienvenu dans la liste de diffusion rubyonrails-docs.