Tag - Ruby - blog.pagesd.info

Tag - Ruby

jeudi 2 septembre 2010

SuperDo : Une todo liste avec Sinatra et DataMapper

Par Michel le jeudi 2 septembre 2010, 20:21 - Traductions

Ceci est la traduction du tutoriel "SuperDo - A Sinatra and DataMapper To Do List" de Darren Jones.

Dans ce nouveau tutoriel dédié à Sinatra, Darren explique comment construire une petite application de type Todo liste qui utilisera une base de données pour enregistrer les différentes tâches. Cela donnera l'occasion d'aborder les points suivants :

Installer SQLIte et DataMapper
Se connecter à la base de données
Gérer les actions de types CRUD
Utiliser des URLs de type RESTFul

Avant de commencer, il est bien entendu nécessaire d'avoir procédé à l'installation de Ruby, de Ruby Gems et de Sinatra.

L'application que nous allons développer s'appellera Superdo et nous pouvons d'ores et déjà voir ce qu'elle donnera sur la version que Darren à déployé sur Heroku.

Installer SQLite et Datamapper

Dans ce tutoriel, nous allons utiliser SQLite comme base de données et DataMapper comme ORM pour nous connecter à notre base de données.

Nous devons donc commencer par installer SQLite sous Windows 7 en téléchargeant la version la plus récente de sqlite3.dll depuis le site de SQLite, soit sqlitedll-3_6_23_1.zip à ce jour. Après avoir décompacté cette archive, il ne reste qu'à copier le fichier sqlite3.dll dans le répertoire C:\Ruby\bin.

Il faut ensuite installer le gem DataMapper :

C:\Ruby>gem install data_mapper

Note : la suite sur le tutoriel en anglais et ses commentaires, le temps que je refasse une installation propre pour bien noter la procédure à suivre pour installer DataMapper sous Windows 7.

Se connecter à la base de données

La première chose à faire est de créer un répertoire nommé "todo" pour notre application et de commencer par y enregistrer un fichier "main.rb" avec le code ci-dessous :

require 'rubygems'
require 'sinatra'
require 'dm-core'
require 'dm-migrations'

DataMapper.setup(:default, ENV['DATABASE_URL'] || "sqlite3://#{Dir.pwd}/development.db")

class Task
  include DataMapper::Resource

  property :id, Serial
  property :name, String
  property :completed_at, DateTime
end

DataMapper.auto_upgrade!

Ca fait pas mal de nouveaux trucs d'un coup, aussi je vais les expliquer un par un.

Les 4 premières lignes déclarent les gems nécessaires :

require 'rubygems'
require 'sinatra'
require 'dm-core'
require 'dm-migrations'

On a besoin de "rubygems" et de "sinatra" pour toutes les applications Sinatra et le gem "dm-core" est nécessaire pour DataMapper. Par rapport au tutoriel de Darren, on a besoin en plus du gem "dm-migrations" car il n'est plus intégré à "dm_core" depuis le passage en version 1.00 de DataMapper.

Le morceau de code suivant permet de se connecter à la base de données :

DataMapper.setup(:default, ENV['DATABASE_URL'] || "sqlite3://#{Dir.pwd}/development.db")

Voila un bout de code très intéressant qui vaut le coup d'être conservé. Il commence par tester si l'application est déployée sur Heroku et dans ce cas se connecte à la base de données qui y est hébergée. Dans le cas contraire, il se connecte à une base de données SQLite locale nommée "development.db". Si celle-ci n'existe pas encore, SQLite la crée automatiquement.

Le bloc de code suivant créé une classe Task avec ses propriétés :

class Task
  include DataMapper::Resource

  property :id, Serial
  property :name, String
  property :completed_at, DateTime
end

Vous aurez besoin de la ligne de code include DataMapper::Resource dans toutes les classes qui utilisent DataMapper. Puis les 3 lignes suivantes définissent les propriétés de votre classe Task. La première défini un identifiant unique propre à chaque tâche. Le type Serial qui lui est associé indique que la propriété "id" doit être auto-incrémentée à chaque fois qu'une nouvelle tâche est ajoutée à la base de données. La deuxième propriété "name" va servir à un libellé pour chaque tâche et nous indiquons à DataMapper que celui-ci sera de type String. Et enfin, la dernière propriété "completed_at" est définie en tant que DateTime pour enregistrer à quel moment la tâche a été marquée comme terminée. Cette propriété nous permettra également de savoir si la tâche a été réalisée ou non : une tâche dont la propriété "completed_at" sera à nil étant considérée comme à faire.

La dernière ligne du fichier "main.rb" contient l'appel à la méthode auto_upgrade! :

DataMapper.auto_upgrade!

Cette méthode indique à DataMapper de mettre à jour la base de données pour refléter toutes modifications apportées à la classe Task. Grâce à cela, nous pouvons ajouter ou supprimer des propriétés à la classe Task et DataMapper se chargera de répercuter ces modifications dans la base de données. Cela permet de développer très rapidement et nous évite de mettre les mains dans le cambouis pour essayer de faire évoluer la structure de notre base de données. La commande auto_upgrade! a l'avantage de conserver les données existantes dans la base de données. Si vous préférez repartir d'une base de données vide, vous pouvez choisir d'utiliser la commande DataMapper.auto_migrate! qui efface définitivement toutes les données déjà présentes dans la base de données.

OK. Maintenant que la base de données est configurée, nous allons pouvoir la tester. Comme nous n'avons pas encore d'interface web, nous allons ouvrir une invite de commandes et aller dans le répertoire "todo" pour lancer la commande suivante :

C:\Ruby\projets\todo>irb -r main.rb

Cela a pour effet d'ouvrir un shell "irb", mais étant donné que nous avons ajouté l'option "-r main.rb", tout le code de notre fichier "main.rb" est chargé dans notre session. Par conséquent, nous avons accès à la base de données et pouvons créer, rechercher ou supprimer des tâches.

Pour commencer, examinons la liste de nos tâches :

irb(main):001:0> Task.all
=> []

Cette commande renvoie à juste titre un tableau vide puisque pour l'instant nous n'avons encore aucune tâche dans notre base de données. On va donc en créer une nouvelle :

irb(main):002:0> t = Task.new
=> #<Task @id=nil @name=nil @completed_at=nil>
irb(main):003:0> t.name = "Acheter du lait"
=> "Get milk"

Pour l'instant, cette tâche n'existe qu'en mémoire. Nous devons explicitement l'enregistrer dans la base de données :

irb(main):004:0> t.save
=> true

Vérifions que cela a correctement fonctionné en recherchant maintenant la première tâche :

irb(main):005:0> Task.first
=> #<Task @id=1 @name="Acheter du lait" @completed_at=nil>

Il existe une autre façon pour créer une nouvelle tâche, en utilisant la commande create :

irb(main):006:0> Task.create(:name => "Acheter des bananes")
=> #<Task @id=2 @name="Acheter des bananes" @completed_at=<not loaded>>

Nous pouvons ajouter des paramètres en les plaçant entre parenthèses après le nom de méthode et en utilisant la notation hash du langage Ruby. Avec la commande create, il n'est pas nécessaire d'enregistrer nous même la nouvelle tâche, car elle est automatiquement sauvegardée dans la base de données. Nous pouvons vérifier cela en demandant à afficher toutes les tâches de la table Tasks :

irb(main):007:0> Task.all
=> [#<Task @id=1 @name="Acheter du lait" @completed_at=nil>, #<Task @id=2 @name=
"Acheter des bananes" @completed_at=nil>]

Comme vous le constatez, nos deux tâches apparaissent désormais dans le tableau. Mais ça risque de devenir un peu compliqué pour s'y retrouver parmi toutes les tâches dès lors qu'on aura un grand nombre d'enregistrement. C'est pourquoi nous pouvons plus simplement utiliser la méthode count :

irb(main):008:0> Task.all.count
=> 2

Cela nous indique qu'il y a actuellement 2 tâches enregistrées dans la base de données.

Nous avons donc vu comment créer et rechercher des enregistrements dans notre base de données. Nous allons à présent voir comment les modifier. Supposons que nous préférions le lait demi-écrémé. Nous devons tout d'abord retrouver le bon enregistrement :

irb(main):009:0> t = Task.first(:name => "Acheter du lait")
=> #<Task @id=1 @name="Acheter du lait" @completed_at=nil>

Il s'agit là d'une des façons de retrouver des enregistrements dans une base de données. Dans notre cas, nous voulons retrouver la tâche dont la propriété "name" contient "Acheter du lait" pour la charger dans la variable t. Nous avons alors deux méthodes pour modifier cet enregistrement. La première consiste à modifier manuellement la variable t puis à la sauvegarder :

irb(main):010:0> t.name = "Acheter du lait demi-écrémé"
=> "Acheter du lait demi-écrémé"
irb(main):011:0> t.save
=> true
irb(main):012:0> t
=> #<Task @id=1 @name="Acheter du lait demi-écrémé" @completed_at=nil>

La seconde méthode est d'utiliser la méthode update. Disons que finallement nous voulons du lait entier :

irb(main):013:0> t.update(:name => "Acheter du lait entier")
=> true
irb(main):014:0> t
=> #<Task @id=1 @name="Acheter du lait entier" @completed_at=nil>

Et pour finir, voyons comment gérer la dernière des actions CRUD : la suppression. Disons que nous n'avons pas besoin de lait ce qui fait que nous pouvons supprimer cette tâche. On commence donc par retrouver cette tâche puis nous la supprimons à l'aide de la commande destroy :

irb(main):015:0> t = Task.get(1)
=> #<Task @id=1 @name="Acheter du lait entier" @completed_at=nil>
irb(main):016:0> t.destroy
=> true

Cette fois-ci, j'ai employé la méthode get pour retrouver la tâche dont l'identifiant est 1. Cette syntaxe n'est utilisable que lorsque l'on passe par la clé primaire pour effectuer la recherche. Dans notre cas, la clé primaire est la propriété id dont la valeur est 1 pour la tâche recherchée. Nous aurons souvent recours à cette méthode par la suite pour retrouver les tâches à partir d'URLs uniques. Nous pouvons désormais vérifier que la tâche a bien été supprimée en redemandant la liste de toutes les tâches :

irb(main):017:0> Task.all
=> [#<Task @id=2 @name="Acheter des bananes" @completed_at=nil>]

Nous constatons alors que seule la tâche "Acheter des bananes" reste enregistrée dans notre base de données.

C'était plutôt amusant et le fait d'utiliser la console constitue une excellente entrée en matière pour faire des essais et tester notre base de données. Mais notre objectif étant de créer une application internet, il est temps de développer une interface pour toutes ces actions.

Associer des URLs RESTful aux actions CRUD

L'interface web que nous allons créer pour interagir avec notre base de données suivra une architecture REST. Cela consiste à utiliser les verbes http POST, GET, PUT et DELETE. Ceux-ci sont très similaires aux actions CRUD (Create, Read, Update et Delete) destinées à mettre à jour la base de données. Chaque tâche aura sa propre URL de la forme "/tasks/:id" où ":id" correspond à l'identifiant unique de la tâche. Par exemple, la tâche "Acheter des bananes" que nous avons créée auparavant aurait l'URL "/tasks/2" étant donné que son identifiant est 2. Le fait qu'il faille lire, modifier ou supprimer une tâche dépendra du verbe http que le navigateur enverra. Par conséquent, même si l'URL sera toujours la même, l'action effectuée sera différente. Et chacune de ces actions sera traitée par un handler différent dans notre application Sinatra.

Commençons par créer le handler qui va servir à consulter les tâches. Pour cela, nous devons modifier le code du fichier "main.rb" de la façon suivante :

require 'rubygems'
require 'sinatra'
require 'dm-core'
require 'dm-migrations'

DataMapper.setup(:default, ENV['DATABASE_URL'] || "sqlite3://#{Dir.pwd}/development.db")

class Task
  include DataMapper::Resource

  property :id, Serial
  property :name, String
  property :completed_at, DateTime
end

# Afficher une tâche
get '/task/:id' do
  @task = Task.get(params[:id])
  erb :task
end

DataMapper.auto_upgrade!

Le handler qui sert à afficher une tâche est contenu dans le code ci-dessous :

# Afficher une tâche
get '/task/:id' do
  @task = Task.get(params[:id])
  erb :task
end

Ce code recherche la tâche dont l'identifiant est égal au paramètre "id" mentionné dans l'URL et affecte cette tâche à la variable d'instance @task qui pourra être utilisée au niveau de la vue. Nous demandons ensuite à Sinatra d'afficher la vue "task" à l'aide d'erb. Il nous faut donc créer une vue "task.erb" dans le dossier "views" contenant les vues de notre application et y saisir le code ci-dessous :

<h2><%= @task.name %></h2>

Il n'y a là rien d'extraordinaire. Juste un titre pour afficher le libellé de la tâche. Pendant que nous y sommes, nous allons créer le layout de notre application. Pour cela, nous créons un fichier "layout.erb" dans le même répertoire "views" avec le code suivant :

<!DOCTYPE html>
<html lang="fr">
  <head>
    <title>To Do Liste</title>
    <meta charset=windows-1250 />
  </head>
  <body>
    <h1>To Do Liste</h1>

    <%= yield %>

  </body>
</html>

Là encore, rien de bien spécial. Nous nous contentons d'un code HTML très basique avec un simple titre annonçant "To Do Liste". On sauvegarde et on va pouvoir tester tout ça en lançant le serveur :

C:\Ruby\projets\todo>ruby main.rb

Nous pouvons alors utiliser notre navigateur pour consulter l'URL "http://localhost:4567/task/2" et on obtient l'écran suivant :

Créer de nouvelles tâches

Passons maintenant à la création d'une nouvelle tâche par l'intermédiaire d'un formulaire web. La façon standard de faire ça est de découper l'action de création en deux handlers :

le premier est nommé "new" et sert à afficher un formulaire de saisie
le second est nommé "create" et sert pour créer la nouvelle tâche à partir des données saisies (généralement en arrière plan)

Commençons par l'action "new" et son formulaire. Le code de l'action est très simple puisque nous souhaitons seulement afficher un formulaire de saisie lorsque l'utilisateur consulte l'URL "/task/new". Pour réaliser cela, copiez le code ci-dessous avant le code pour l'action "show" (sans quoi il ne serait pas pris en compte) :

# Saisir une nouvelle tâche
get '/task/new' do
  erb :new
end

Ce code se contente d'afficher la vue "new.erb" que nous allons immédiatement créer dans le dossier "views" en saisisant les quelques lignes suivantes :

<form action="/task/create" method="POST">
  <input type="text" name="name" id="name">
  <input type="submit" value="Ajouter la tâche"/>
</form>

C'est un formulaire simple qui permet à l'utilisateur de saisir le libellé d'une nouvelle tâche dans une zone de saisie nommée "name" (ce qui correspond à la colonne "name" de la table des tâches, ce qui n'est pas obligatoire mais beaucoup plus facile).

Le bouton submit va envoyer cette information vers l'URL "/task/create" pour laquelle nous allons créer le handler correspondant. Son code est un peu plus compliqué que celui de l'action "new", mais pas tant que ça :

# Créer une nouvelle tâche
post '/task/create' do
  task = Task.new(:name => params[:name])
  if task.save
    status 201
    redirect '/task/' + task.id.to_s
  else
    status 412
    redirect '/tasks'
  end
end

Examinons d'un peu plus près ce qui se passe dans ce code. Pour commencer, il s'exécute lorsqu'il s'agit d'une requête POST étant donné que nous attendons les données postées depuis le formulaire. Puis il crée une nouvelle tâche en lui donnant comme nom la valeur stockée dans le paramètre "name" en provenance du formulaire. Ensuite nous vérifions que la tâche a bien été enregistrée. Si c'est le cas, nous définissons le statut http à 201 (la valeur standard pour signifier que quelque chose a été créé) et renvoyons l'utilisateur vers l'URL affichant la tâche en concaténant son identifiant après "/task/" (ce qui correspond à l'action d'affichage d'une tâche que nous avions développée auparavant). Dans le cas où la tâche n'a pas été sauvegardée, nous renvoyons un statut http à 412 ce qui indique au navigateur que certaines conditions (comme la validation de données) n'ont pas été remplies. L'utilisateur est alors redirigé vers la page d'index "/tasks" (que nous n'avons pas encore créé mais dont nous nous occuperons très bientôt).

Nous pouvons alors tester tout cela et créer une nouvelle tâche à l'aide du navigateur en allant à l'URL "http://localhost:4567/task/new" qui nous présente le formulaire de saisie reproduit ci-dessous :

Continuez et ajoutez plusieurs nouvelles tâches. A chaque fois que vous validez le formulaire, vous devez voir apparaitre une nouvelle page qui affiche le nom de la nouvelle tâche créée.

Arrivé à ce point, le contenu de votre fichier "main.rb" doit être le suivant :

require 'rubygems'
require 'sinatra'
require 'dm-core'
require 'dm-migrations'

DataMapper.setup(:default, ENV['DATABASE_URL'] || "sqlite3://#{Dir.pwd}/development.db")

class Task
  include DataMapper::Resource
  property :id, Serial
  property :name, String
  property :completed_at, DateTime
end

# Saisir une nouvelle tâche
get '/task/new' do
  erb :new
end

# Créer une nouvelle tâche
post '/task/create' do
  task = Task.new(:name => params[:name])
  if task.save
    status 201
    redirect '/task/' + task.id.to_s
  else
    status 412
    redirect '/tasks'
  end
end

# Afficher une tâche
get '/task/:id' do
  @task = Task.get(params[:id])
  erb :task
end

DataMapper.auto_upgrade!

Afficher la liste des tâches

Pour l'instant, nous pouvons créer de nouvelles tâches et les afficher une par une. Nous allons maintenant afficher une liste qui contiendra toutes les tâches existantes. Pour cela, nous commençons par créer l'action suivante :

# Afficher toutes les tâches
get '/tasks' do
  @tasks = Task.all
  erb :index
end

Ce code récupère tout simplement la liste de toutes les tâches enregistrées dans la base de données via la méthode "all" et les stocke dans la variable d'instance "@tasks" qui sera utilisable dans la vue. Puis il affiche la vue "index.erb" que nous allons créer dans le sous-répertoire "views" :

<h2>Liste des tâches :</h2>
<% unless @tasks.empty? %>
<ul>
<% @tasks.each do |task| %>
  <li <%= "class=\"completed\"" if task.completed_at %>>
    <a href="/task/<%=task.id%>"><%= task.name %></a>
  </li>
<% end %>
</ul>
<% else %>
<p>Aucune tâche enregistrée !</p>
<% end %>

Cette vue commence par tester si le tableau des tâches est vide. Si ce n'est pas le cas, elle parcours ce tableau pour créer une liste à puces à partir des tâches qu'il contient. Pour chaque tâche, elle teste si celle-ci a été terminée ou non et ajoute une classe "completed" lorsque c'est le cas. Cela nous servira plus tard lorsque nous travaillerons sur la feuille de style de notre application. Dans le cas où le tableau "@tasks" est vide, nous affichons simplement un message pour indiquer qu'il n'y a pas de tâche. Si vous lancez votre navigateur pour visiter l'URL "http://localhost:4567/tasks", vous obtenez l'écran suivant :

Modifier des tâches

Il ne nous reste plus que quelques traitements à gérer, à savoir la modification et la suppression. Nous allons pour l'instant permettre aux utilisateurs de modifier les tâches existantes. Comme pour la création avec les actions "new" et "create", la modification nécessite une action "edit" associée avec une action "update". L'action "edit" affiche un formulaire qui permet à l'utilisateur de saisir les informations d'une tâche et de valider. C'est l'action "update" qui effectue la mise à jour dans la base de données. Voici ce que donne ces deux actions dans le code ci-dessous :

# Modifier une tâche existante
get '/task/:id/edit' do
  @task = Task.get(params[:id])
  erb :edit
end

# Mettre à jour une tâche
put '/task/:id' do
  task = Task.get(params[:id])
  task.completed_at = params[:completed] ? Time.now : nil
  task.name = (params[:name])
  if task.save
    status 201
    redirect '/task/' + task.id.to_s
  else
    status 412
    redirect '/tasks'
  end
end

Nous devons également créer un fichier "edit.erb" dans le sous-répertoire des vues :

<form action="/task/<%= @task.id %>" method="post">
  <input name="_method" type="hidden" value="put" />
  <input type="text" name="name" id="name" value="<%= @task.name %>">
  <input id="completed" name="completed" type="checkbox" value="done" <%= @task.completed_at ? "checked" : "" %>/>
  <input id="task_submit" name="commit" type="submit" value="Modifier" />
</form>

Il y a pas mal de trucs à voir là dedans. Pour commencer, le handler "edit" se contente d'afficher un formulaire lorsque l'utilisateur accède à l'URL "task/2/edit". Le formulaire est assez semblable à celui pour créer une nouvelle tâche, à quelques différences près. Il contient un champ pour le nom qui est pré-rempli avec le libellé de la tâche, une case à cocher si on veut signaler que la tâche est terminée et un bouton pour envoyer les données saisies.

La particularité de ce formulaire est qu'il poste ses données vers l'URL "task/2", soit la même URL que celle que nous utilisons déjà pour afficher une tâche. C'est pourquoi on défini un champ caché avec la ligne <input name="_method" type="hidden" value="put" /> pour indiquer qu'il s'agit en fait d'une requête http PUT et pas d'une simple requête POST. Cet artifice est nécessaire parce qu'à l'heure actuelle, il n'existe aucun navigateur qui sache gérer les requêtes PUT. Cela a pour effet d'envoyer la requête sous forme de POST mais Sinatra voyant qu'il y a un champ caché "_method" avec la valeur "put", il agit comme s'il avait reçu une requête http PUT et la transmet au handler pour l'URL "task/2/edit" qui correspond à un PUT, soit la méthode "update" dans notre code.

Le handler "update" est assez proche du handler "create". Il commence par accéder à la base de données pour retrouver la tâche à modifier en utilisant l'id stocké dans la collection "params" (notez au passage que celui-ci provient de l'URL et pas du formulaire). Il vérifie ensuite si la case à cocher a été cochée et si c'est le cas il initialise la propriété "completed_at" avec l'heure en cours, pour indiquer que la tâche est terminée. Dans le cas contraire, il affecte simplement la valeur nil à cette propriété. Puis après avoir mis à jour la propriété "name", la tâche est enregistrée en suivant la même méthode qu'au niveau du handler "create".

Testons tout ça. Supposons qu'armé de courage je décide de vraiment faire du sport et plus particulièrement du vélo. Je vais donc cliquer sur le lien "Faire du sport" dans la liste des tâches puis ajouter "/edit" à la fin de l'URL de la page obtenue (c'est pas très ergonomique mais on s'occupera de ça plus tard). Cela a pour effet d'afficher le formulaire de mise à jour de la tâche où je vais pouvoir modifier le nom en "Faire du velo" puis cliquer sur le bouton "Modifier" pour enregistrer la modification.

Supprimer des tâches.

Le dernier traitement à prendre en compte est la suppression de tâches existantes. Nous allons faire cela en deux étapes. En premier lieu, nous allons ajouter un lien pour la suppression dans la vue "edit". Pour cela, nous ouvrons le fichier "edit.erb" pour le modifier comme ci-dessous :

<form action="/task/<%= @task.id %>" method="post">
  <input name="_method" type="hidden" value="put" />
  <input type="text" name="name" id="name" value="<%= @task.name %>">
  <input id="completed" name="completed" type="checkbox" value="done" <%= @task.completed_at ? "checked" : "" %>/>
  <input id="task_submit" name="commit" type="submit" value="Modifier" />
</form>

<p><a href="/task/<%= @task.id %>/delete">Supprimer cette tâche</a></p>

La dernière ligne dans ce code ajoute un lien vers l'URL "/task/:id/delete" qui va conduire vers une page où nous demanderons à l'utilisateur s'il est certain de vouloir supprimer la tâche. Nous allons donc ajouter le traitement pour faire confirmer la suppression à notre fichier "main.rb" :

# Confirmer la suppression
get '/task/:id/delete' do
  @task = Task.get(params[:id])
  erb :delete
end

Ce code recherche la tâche dont l'identifiant est mentionné dans l'URL puis stocke cette tâche dans la variable d'instance "@task". Encore une fois, nous devons utiliser une variable d'instance (qui est préfixée par un @) car nous aurons besoin d'y faire référence dans la vue de confirmation. Et maintenant, il nous reste à coder cet écran de confirmation en créant un fichier "delete.erb" dans le sous-répertoire des vues et en y saisissant le code ci-dessous :

<h2><%= @task.name %><h2>
<h3>Est-ce que vous souhaitez réellement supprimer cette tâche ?</h3>
<form action="/task/<%= @task.id %>" method="post">
  <input type="hidden" name="_method" value="delete" />
  <input type="submit" value="Supprimer"> ou <a href="/tasks">Annuler</a>
</form>

Le fonctionnement de cette vue est très proche du formulaire pour la modification. Vous pouvez voir que là aussi nous avons besoin d'un champ caché pour simuler la méthode http DELETE étant donné que quasiment aucun navigateur ne sait la gérer. Et nous avons en plus ajouté un lien pour annuler la demande de suppression et revenir à la liste des tâches.

Il ne nous reste donc plus qu'à créer le code pour gérer l'action qui va réellement supprimer la tâche dans la base de données. Pour cela, nous devons ajouter le code suivant à notre fichier "main.rb" :

# Supprimer une tâche
delete '/task/:id' do
  Task.get(params[:id]).destroy
  redirect '/tasks'  
end

Nous pouvons alors tester ce code en supprimant la tâche "Faire du vélo" (de toute façon je n'ai pas de vélo). On clique sur cette tâche dans la liste des tâches, on ajoute "/edit" à la fin de l'URL obtenue puis là on suit le lien "Supprimer la tâche" ce qui nous amène sur l'écran de confirmation ci-dessous :

Ces deux derniers traitements sont une excellente illustration de la façon dont REST fonctionne. Les actions pour afficher, modifier et supprimer une tâche correspondent toutes à la même URL (par exemple "/task/2") et concernent le même objet (la tâche dont l'identifiant est 2 dans notre exemple). Mais elles accomplissent toutes des fonctions très différentes et elles sont sélectionnées en fonction du verbe http employé (soit GET, UPDATE et DELETE respectivement).

Le code source du fichier "main.rb" complet présente désormais le contenu suivant :

require 'rubygems'
require 'sinatra'
require 'dm-core'
require 'dm-migrations'

DataMapper.setup(:default, ENV['DATABASE_URL'] || "sqlite3://#{Dir.pwd}/development.db")

class Task
  include DataMapper::Resource
  property :id, Serial
  property :name, String
  property :completed_at, DateTime
end

# Saisir une nouvelle tâche
get '/task/new' do
  erb :new
end

# Créer une nouvelle tâche
post '/task/create' do
  task = Task.new(:name => params[:name])
  if task.save
    status 201
    redirect '/task/' + task.id.to_s
  else
    status 412
    redirect '/tasks'
  end
end

# Modifier une tâche existante
get '/task/:id/edit' do
  @task = Task.get(params[:id])
  erb :edit
end

# Mettre à jour une tâche
put '/task/:id' do
  task = Task.get(params[:id])
  task.completed_at = params[:completed] ? Time.now : nil
  task.name = (params[:name])
  if task.save
    status 201
    redirect '/task/' + task.id.to_s
  else
    status 412
    redirect '/tasks'
  end
end

# Confirmer la suppression
get '/task/:id/delete' do
  @task = Task.get(params[:id])
  erb :delete
end

# Supprimer une tâche
delete '/task/:id' do
  Task.get(params[:id]).destroy
  redirect '/tasks'  
end

# Afficher une tâche
get '/task/:id' do
  @task = Task.get(params[:id])
  erb :task
end

# Afficher toutes les tâches
get '/tasks' do
  @tasks = Task.all
  erb :index
end

DataMapper.auto_upgrade!

Celui-ci contient à présent les 7 handlers REST traditionnels : index, show, new, create, edit, update et delete ainsi qu'une action supplémentaire pour faire confirmer la suppression.

Améliorer l'interface utilisateur

Notre application est maintenant complète, mais il reste encore quelques points où pouvons encore l'améliorer. Comme je l'ai indiqué auparavant, son code suit les conventions de Rails en ce qui concerne les URLs REST. Ce qui est bien avec Sinatra, c'est que vous pouvez faire les choses à votre façon. C'est pourquoi je vais maintenant modifier certaines de ces URLs.

Pour commencer, je préfèrerais que ce soit la page principale qui affiche la liste de toutes les tâches plutôt que d'avoir une URL "/tasks" pour cela. Cette modification est toute simple à faire :

# Afficher toutes les tâches
get '/' do
  @tasks = Task.all
  erb :index
end

J'aimerais aussi que le formulaire pour créer une nouvelle tâche apparaisse dans la page principale, à la suite de la liste des tâches. Pour cela, il suffit de copier le code du fichier "new.erb" dans le fichier "index.erb" (tous deux dans le sous-répertoire views). Le fichier "index.erb" contient alors le code suivant :

<h2>Liste des tâches :</h2>
<% unless @tasks.empty? %>
<ul>
<% @tasks.each do |task| %>
  <li <%= "class=\"completed\"" if task.completed_at %>>
    <a href="/task/<%=task.id%>"><%= task.name %></a>
  </li>
<% end %>
</ul>
<% else %>
<p>Aucune tâche enregistrée !</p>
<% end %>

<h2>Créer une tâche</h2>
<form action="/task/create" method="POST">
  <input type="text" name="name" id="name">
  <input type="submit" value="Ajouter la tâche"/>
</form>

Il est ensuite possible de supprimer le fichier new.erb qui ne sert plus à rien ainsi que le handler pour l'action "new" dans le fichier "main.rb" (par contre, il faut conserver celui pour l'action "create"). Je vais également supprimer l'action "show" et la vue "task.erb" qui lui est associée étant donné que cela ne sert qu'à afficher le nom d'une tâche, ce que l'on peut déjà voir dans la liste des tâches. L'avantage de cette suppression, c'est que l'URL "/task/:id" ne sert plus et que je vais pouvoir l'utiliser pour afficher le formulaire de mise à jour d'une tâche. Pour cela, il faut donc modifier l'action "edit" comme suit :

# Modifier une tâche existante
get '/task/:id' do
  @task = Task.get(params[:id])
  erb :edit
end

Votre code fait tout de suite plus propre. Il reste encore quelques redirections qui pointent vers des URLs qui n'existent plus et qu'il faut donc corriger, généralement pour les faire pointer vers la racine du site. Suite à tout cela, le code du fichier "main.erb" est beaucoup plus léger et doit ressembler à ceci :

require 'rubygems'
require 'sinatra'
require 'dm-core'
require 'dm-migrations'

DataMapper.setup(:default, ENV['DATABASE_URL'] || "sqlite3://#{Dir.pwd}/development.db")

class Task
  include DataMapper::Resource
  property :id, Serial
  property :name, String
  property :completed_at, DateTime
end

# Créer une nouvelle tâche
post '/task/create' do
  task = Task.new(:name => params[:name])
  if task.save
    status 201
    redirect '/'
  else
    status 412
    redirect '/'
  end
end

# Modifier une tâche existante
get '/task/:id' do
  @task = Task.get(params[:id])
  erb :edit
end

# Mettre à jour une tâche
put '/task/:id' do
  task = Task.get(params[:id])
  task.completed_at = params[:completed] ? Time.now : nil
  task.name = (params[:name])
  if task.save
    status 201
    redirect '/'
  else
    status 412
    redirect '/'
  end
end

# Confirmer la suppression
get '/task/:id/delete' do
  @task = Task.get(params[:id])
  erb :delete
end

# Supprimer une tâche
delete '/task/:id' do
  Task.get(params[:id]).destroy
  redirect '/'  
end

# Afficher toutes les tâches
get '/' do
  @tasks = Task.all
  erb :index
end

DataMapper.auto_upgrade!

J'ai aussi décidé d'ajouter un lien de retour vers la page d'accueil quand on clique sur le titre de la page. Pour que ce lien apparaisse partout, il faut modifier le fichier "layout.erb" dans le sous-répertoire des vues :

<!DOCTYPE html>
<html lang="fr">
  <head>
    <title>To Do Liste</title>
    <meta charset=windows-1250 />
  </head>
  <body>
    <h1><a href="/">To Do Liste</a></h1>

    <%= yield %>

  </body>
</html>

L'application est désormais plus simple à utiliser et fonctionne de façon beaucoup plus intuitive :

Améliorer le code

Après ces modifications visibles par l'utilisateur, je vais réaliser quelques modifications destinées à simplifier le code de l'application. Pour commencer, je vais ajouter quelques méthodes pour faciliter la gestion des tâches terminées. Etant donné qu'il s'agit de méthodes liées aux tâches, il faut les placer dans la définition de la classe :

class Task
  include DataMapper::Resource
  property :id, Serial
  property :name, String
  property :completed_at, DateTime

  def completed?
    true if completed_at
  end

  def self.completed
    all(:completed_at.not => nil)
  end
end

La première méthode est une méthode d'instance: elle est définie au niveau de la tâche, comme dans le cas d'une propriété. Elle considère que s'il y a une date de définie pour la propriété "completed_at" c'est que la tâche est terminée et renvoie donc "true" dans ce cas, ou "false" dans le cas contraire.

La seconde méthode est une méthode de classe et porte sur toutes les tâches. Elle peut servir pour filtrer vos recherches à l'aide de DataMapper. Par exemple, le fait d'utiliser Task.completed permettra de retrouver toutes les tâches qui sont terminées. Un truc très intéressant avec ces méthodes, c'est qu'elles peuvent être chainées les unes aux autres pour affiner les recherches. Par exemple, s'il existait une méthode de classe nommée "important" qui renvoyait toutes les tâches importantes (c'est pas trop possible pour l'instant, mais on pourrait parfaitement ajouter un tel truc à l'avenir !), alors on pourrait utiliser Task.important.completed pour retrouver toutes les tâches importantes qui sont terminées.

Je souhaiterais aussi avoir une méthode pour générer un lien vers une tâche. Vous sous souvenez peut-être du code assez minable que j'avais utilisé pour générer un tel lien dans la vue "index.erb" :

<a href="/task/<%=task.id%>"><%= task.name %></a>

Cela serait beaucoup plus propre si nous pouvions masquer cette complexité dans une méthode d'instance au niveau de la classe Task :

class Task
  include DataMapper::Resource
  property :id, Serial
  property :name, String
  property :completed_at, DateTime

  def completed?
    true if completed_at
  end

  def self.completed
    all(:completed_at.not => nil)
  end

  def link
    "<a href=\"task/#{self.id}\">#{self.name}</a>"
  end
end

La méthode "link" est vraiment toute simple. Elle renvoie une chaine contenant le code html qui fait un lien vers la page de mise à jour d'une tâche. Pour cela, j'ai utilisé l'interpolation de texte qui consiste à placer du code Ruby devant être évalué à l'intérieur de #{}. Et pour faire référence à la tâche concerné par la méthode, j'ai employé le mot-clé "self".

Après cela, nous pouvons simplifier le contenu de la vue "index.erb" pour utiliser ces différents méthodes, ce qui donne le code suivant :

<h2>Liste des tâches :</h2>
<% unless @tasks.empty? %>
<ul>
<% @tasks.each do |task| %>
  <li <%= "class=\"completed\"" if task.completed? %>>
    <%= task.link %>
  </li>
<% end %>
</ul>
<% else %>
<p>Aucune tâche enregistrée !</p>
<% end %>

<h2>Créer une tâche</h2>
<form action="/task/create" method="POST">
  <input type="text" name="name" id="name">
  <input type="submit" value="Ajouter la tâche"/>
</form>

Notre source est devenu bien plus lisible et par conséquent beaucoup plus facile à maintenir. Pour devenir parfait, il ne nous reste plus qu'à faire ressortir les tâches qui ont été accomplies. Etant donné que celles-ci sont d'ores et déjà marquées d'une classe CSS "completed" (il vous suffit d'afficher le code source de la page pour contrôler ça), on a juste besoin d'ajouter une ligne de CSS dans le fichier "layout.erb" :

<!DOCTYPE html>
<html lang="fr">
  <head>
    <title>To Do Liste</title>
    <meta charset=windows-1250 />
    <style>
      .completed {text-decoration: line-through;}
    </style>
  </head>
  <body>
    <h1><a href="/">To Do Liste</a></h1>

    <%= yield %>

  </body>
</html>

Après cette ultime fioriture, vous pouvez compléter votre todo liste ou indiquer que certaines tâches sont terminées et avoir un retour visuel direct dans la liste des tâches de l'écran principal. Au final, votre application doit ressembler à la copie d'écran ci-dessous :

Conclusion

Ce tutoriel correspond à une application de base de données toute simple, mais cela constitue un bon point de départ. Notre application n'est peut être pas tout à fait à la hauteur de son nom étant donné que pour l'instant il faut pas mal chercher pour faire ressortir tout son côté "Super". Mais en nous appuyant sur cette base, nous avons des tas de perspectives d'évolutions. Vous pourriez par exemple essayer de gérer différentes listes de tâches (pour étudier les associations sous DataMapper), vous pourriez ajouter un peu de Javascript ou de jQuery pour améliorer l'interface utilisateur ou encore vous pourriez intégrer une notion de priorité et afficher les tâches prioritaires en haut de liste...

aucun commentaire aucun rétrolien

mardi 3 août 2010

Guide pour démarrer avec Git

Par Michel le mardi 3 août 2010, 10:25 - Traductions

Ceci est la traduction du tutoriel "Git Beginners Guide" de Darren Jones.

Dans ce nouveau tutoriel, Darren présente les bases de Git et aborde les éléments suivants :

Qu'est-ce que Git ?
Installer et configurer Git
Ajouter et Commiter avec Git
Les Branches
Les Tags
Les repositories distants
Quelques ressources sur Git

Qu'est-ce que Git ?

Git est un système de contrôle de version qui vous de garder une trace de toutes les modifications que l'on fait quand on travaille sur un projet. Git permet de faire un "roll back" pour revenir sur une version précédente et aussi de créer des "branches" dans votre code pour tester de nouvelles fonctionalités sans toucher à la version en cours et stable de votre code. Un système de contrôle source est essentiel quand vous travaillez en équipe, mais dans le cadre de Sinatra, c'est aussi un outil pour déployer des applications sur le cloud chez Heroku (cela fera l'objet d'un autre billet).

Git utilise la ligne de commande pour son interface utilisateur, mais pour ceux qui préfèrent, il existe aussi de nombreux outils visuels.

Installer et configurer Git

Pour commencer, vous avez besoin d'installer Git.

La VO de ce tutoriel Git Beginners Guide explique comment installer Git pour Linux, Mac et Windows. Par ailleurs, GitHub propose un tutoriel très complet pour installer Git sur Windows et un autre qui explique comment générer les clés SSH pour Git et ajouter votre clé publique à votre compte GitHub.

Une fois l'installation terminée, il faut lancer un "Git Bash" (en faisant un clic-droit sur un répertoire et en choisissant la commande "Git Bash here"). Cela a pour effet d'ouvrir un genre d'invite de commandes pour Git où vous pouvez définir quelques paramètres généraux en utilisant les deux commandes suivantes :

$ git config --global user.name "Votre Nom"
$ git config --global user.email "votremail@example.com"

Note : pour quitter Git Bash, on peut taper la commande exit.

Maintenant, il faut se placer dans le répertoire de notre projet. Pour nos tests, nous allons utiliser le projet Reverse réalisé lors du tutoriel précédent :

$ cd /c/Ruby/projets/reverse

Puis nous initialisons ce répertoire pour que Git assure le suivi des modifications que nous apporterons au contenu de ce répertoire.

$ git init

Nous obtenons en retour le message "Initialized empty Git repository in c:/Ruby/_projets/reverse/.git/". Si on consulte le répertoire C:\Ruby\projets\reverse dans l'explorateur de Windows, on peut constater qu'il contient désormais un sous-répertoire ".git" qui sert va servir à Git pour stocker le repository.

Ajouter et Commiter avec Git

A présent, nous allons ajouter tous les fichiers et les sous-répertoire de notre projet Reverse dans le repository que nous venons de créer. On effectue cela en tapant la commande suivante :

$ git add .

Ceci va ajouter tous les fichiers à l'index, puisque le "." représente tous les fichiers. L'index est un peu comme une zone de transit dans laquelle les fichiers attendent d'être commités dans le repository. Ce que nous allons faire avec cette commande :

$ git commit -m "Version initiale du projet Reverse"

Cela a pour effet de commiter tous les fichiers de l'index dans le repository. Le texte entre guillemets après le "-m" est un message que vous devez définir à chaque commit pour expliquer ce que vous avez fait.

Et maintenant on va apporter quelques modifications à notre projet, comme par exemple de changer légèrement la fin du fichier "layout.erb" pour y ajouter un lien :

<!DOCTYPE html>
<html lang="en">
<head>
<title>Reverse!</title>
<meta charset=utf-8 />
</head>
<body>
<h1>Reverse</h1>
<h2><%= @title %></h2>

<%= yield %>

<p>The first Sinatra project for <a href="http://ididitmyway.heroku.com/">I Did It My Way</a></p>
</body>
</html>

Puis on saisi la commande suivante dans Git Bash pour mettre à jour l'index :

$ git add views/layout.erb

Comme vous pouvez le voir, on peut décider de spécifier quel fichier on veut ajouter à l'index plutôt que d'utiliser "." pour sélectionner tous les fichiers. Et sinon, n'oubliez pas de commiter votre modification :

$ git commit -m "Ajout d'un lien en pied de page"

Le fait d'avoir à ajouter puis à commiter peut sembler un peu fastidieux. Mais cela présente l'avantage de permettre d'ajouter plusieurs modifications avant de réellement faire le commit. Toutefois, on peut ramener ça à une seule étape en utilisant l'option "-a" :

$ git commit -a -m "un message d'explication"

Cela aura pour effet d'ajouter et de commiter les modifications en une seule fois. En fait, tous les fichiers modifiés ou supprimés sont commités. Les nouveaux fichiers ne sont pas concernés.

Si vous souhaitez supprimer des fichiers, vous ne pouvez pas vous contenter de les supprimer directement depuis Windows. Vous devez aussi les supprimer du repository Git en utilisant la commande "rm". Par exemple, nous n'avons plus besoin du fichier "frank.erb" qui doit encore se trouver dans le sous-répertoire "views". Nous pouvons donc le supprimer du repository avec la commande suivante :

$ git rm views/frank.erb

Le fichier "frank.erb" est alors supprimé physiquement du sous-répertoire "views". Il reste encore à commiter pour qu'il soit supprimé définitivement du repository Git :

$ git commit -a -m "Suppression fichier inutile"

Les Branches

En ce qui me concerne, c'est LE truc de Git. Quand vous créez une branche, c'est en gros comme si vous faisiez une copie de votre code en cours. Vous pouvez alors faire plein de modifications ou d'essais sans toucher au code d'origine. Si on veut conserver ces changements, on peut alors les fusionner avec le code d'origine ou si ces changements ne conviennent pas, on peut tout simplement revenir au code de départ et supprimer la branche. Il est possible de créer autant de branches que l'on souhaite et les fusionner entre elles ou les conserver en tant que branches séparées.

Au départ, vous démarrez avec la branche par défaut qui s'appelle "master". Pour savoir sur quelle branche vous vous trouvez actuellement, il suffit de taper :

$ git branch

Et vous devriez alors avoir le résultat suivant :

* master

L'astérisque devant "master" indique qu'il s'agit de la branche en cours.

Pour créer une nouvelle branche qu'on appellera "development", il faut taper :

$ git branch development

Puis pour basculer sur cette branche vous devez saisir :

$ git checkout development

Après un message Switched to branch 'development', vous pouvez vérifier que cela a fonctionné en tapant :

$ git branch

Et cette fois, vous devez obtenir :

* development
  master

L'astérisque devant "development" vous montre que vous travaillez maintenant sur la branche "development". Si vous faites une modification quelconque, cela affectera uniquement la branche "development" et absolument pas la branche "master".

Essayez par exemple de changer quelques lignes (en supprimant par exemple le lien dans "layout.erb") puis commitez ces modifications :

$ git commit -a -m "Suppression du lien en pied de page"

Revenez alors sur la branche principale :

$ git checkout master

Vous pouvez réouvrir le fichier "layout.erb" pour constater que votre modification n'est pas là ! Et que le lien que vous venez de supprimer est toujours là ! On retourne dare-dare sur la branche de développement :

$ git checkout development

On ré-ouvre derechef la fichier "layout.erb" et notre modification est bien là !

Le plus gros intérêt des branches est de permettre de séparer la branche principale du code de la branche de développement. Mais étant donné que c'est si facile et si rapide, on peut aussi utiliser les branches pour tester de nouvelles fonctionnalités. Supposons que je veuille ajouter un super fonctionnalité Twitter dans ma branche de développement. Je commence par créer une nouvelle branche dédiée à cette fonctionnalité :

$ git branch feature-twitter

Puis je passe sur cette branche

$ git checkout feature-twitter

On va ensuite ajouter notre super fonctionnalité Twitter et tester qu'elle marche correctement. Pour gagner un peu de temps, pourquoi ne pas ajouter un lien vers Twitter dans le pied de page (soit le fichier "layout.erb si vous avez bonne mémoire). Ces modifications vont seulement concerner notre nouvelle branche "feature-twitter". Disons que ces modifications vous donnent satisfaction (et que le lien fonctionne) vous allez les commiter :

$ git commit -a -m "Ajout fonctionnalité Twitter"

Et ensuite vous allez vouloir avoir ces modifications dans votre branche de développement. Et pour cela, vous allez donc devoir les fusionner. Et pour commencer, il faut repasser sur la branche développement :

$ git checkout development

Puis y fusionner les modifications apportées dans la branche pour Twitter :

$ git merge feature-twitter

A partir de maintenant, les modifications que vous aviez faites dans la branche "feature-twitter" sont bel et bien incluses dans la branche développement. Par conséquent, vous n'avez plus besoin de la branche Twitter qui ne vous a servi que pour les tests. Vous pouvez donc la supprimer définitivement en utilisant l'option "-d" :

$ git branch -d feature-twitter

Lorsque votre branche de développement aura été recettée et sera fin prête pour le grand jour de la mise en production, il ne vous restera plus qu'à la fusionner à votre branche "master". Souvenez-vous bien qu'il faut d'abord passer sur la branche "master" puis y fusionner la branche "development" :

$ git checkout master
$ git merge development

Les Tags

Vous pouvez créer un tag pour un projet à n'importe quel moment, en utilisant la commande suivante :

$ git tag v1.0 -m "Version 1.0 du projet Reverse"

Cela vous permet d'immortaliser certains moments du développement - assurez vous d'avoir ajouté et commité tous les changements apportés avant de créer un tag. Si vous voulez voir tous les tags que vous avez créé, vous pouvez taper :

$ git tag

Et si vous souhaitez revenir à une version précédente, alors vous créez une nouvelle branche pour celle-ci. Supposons qu'à l'avenir vous ayez à revenir sur cette version (pour corriger un bug dessus par exemple), vous aurez à saisir la commande ci-dessous :

$ git checkout v1.0 -b version1

Cela va automatiquement créer une nouvelle branche nommée "version1" qui sera la copie exacte de ce qu'était le projet lorsque vous aviez créé le tag "v1.0", sans que cela vous fasse perdre quoique ce soit de votre code actuel.

Les repositories distants

Github est un service extraordinaire qui vous permet de conserver votre code dans un repository distant qui est hébergé sur leurs serveurs. Pour pouvoir démarrer, vous n'avez qu'à vous inscrire pour disposer d'un compte gratuit, définir un nouveau projet puis suivre leurs instructions pour créer un nouveau repository distant.

Une fois que votre repository distant est créé, tout ce qu'il vous reste à faire c'est d'entrer la commande ci-dessous :

$ git push origin master

Cela aura pour effet d'envoyer tout le code de votre branche "master" vers votre repository chez GitHub. C'est très pratique pour disposer d'une sauvegarde externe de votre repository dans le cloud mais aussi pour partager votre travail avec les autres (l'idéal pour tous les projets open source !). Par contre, si vous voulez que votre repository reste privé alors vous aurez besoin de prendre un compte payant sur GitHub.

Vous pouvez aussi vous mettre à utiliser le code d'autres personnes sur GitHub en clonant leur repositories et en utilisant la commande pull pour récupérer toutes les modifications qu'ils ont effectuées. Quant à eux, ils ont aussi la possibilité d'utiliser la commande pull pour récupérer les changement que vous avez apporté. Tout cela fait de Git un outil particulièrement puissant dès qu'il s'agit de collaborer sur un même projet, dans la mesure où il permet aux gens de corriger des bugs dans votre code, d'améliorer votre code ou de développer un projet totalement nouveau.

Quelques ressources sur Git

Daren a collecté un certain nombre de ressources consacrées à Git que vous pouvez retrouver sur le tutoriel d'origine.

Git est une application super puissante qui va révolutionner la façon dont vous gérez vos projets. Et il est extrêmement précieux quand il s'agit de gérer et de déployer des applications Sinatra sur la plateforme Heroku, ce dont je parlerai dans un prochain billet.

aucun commentaire

mercredi 28 juillet 2010

Création d'un premier projet avec Sinatra

Par Michel le mercredi 28 juillet 2010, 19:45 - Traductions

Ceci est la traduction du tutoriel "Project 1: Reverse" de Darren Jones.

Après avoir brillamment suivi pas à pas mon premier tutoriel pour installer Ruby et Sinatra sur mon PC Windows 7, je continue sur ma lancée avec la réalisation du deuxième tutoriel proposé par Darren Jones.

Le but de ce tutoriel est de programmer une première application très très simple qui va se contenter d'afficher un texte à l'envers, d'où son nom : Projet 1 : Reverse. A travers cette mini-application, on peut déjà apprendre quelques trucs sur le fonctionnement de Sinatra, voire sur Ruby si on débute comme moi.

C'est parti

Pour commencer, j'ai créé un répertoire C:\Ruby\projets\reverse puis un fichier main.rb à l'intérieur :

require 'rubygems'
require 'sinatra'

get '/' do
  "I did it my way!"
end

Toutes les applications Sinatra ont besoin des deux premières lignes. Il y a ensuite une ligne blanche pour faire plus joli puis 3 lignes de code où se situe toute l'action :

«get» indique quelle méthode HTTP on souhaite gérer : un GET dans le cas présent,
«'/'» correspond à la route à gérer, soit la racine de l'application dans ce cas,
«do ... end» est un bloc de code pour définir ce qui se passe quand quelqu'un demande la racine du site.

La dernière ligne à l'intérieur du bloc «do ... end» contient toujours (je pense) ce qui sera affiché dans la page, soit "I did it my way!" dans ce premier exemple.

Pour tester ce code, on peut directement double-cliquer sur le fichier main.rb dans le répertoire C:\Ruby\projets\reverse ou faire ça à la main dans une invite de commande :

C:\Ruby\projets\reverse>ruby main.rb

Et Sinatra entre en scène :

== Sinatra/1.0 has taken the stage on 4567 for development with backup from WEBrick
[2010-07-27 21:44:57] INFO  WEBrick 1.3.1
[2010-07-27 21:44:57] INFO  ruby 1.9.1 (2010-07-02) [i386-mingw32]
[2010-07-27 21:44:57] INFO  WEBrick::HTTPServer#start: pid=3604 port=4567

On peut alors lancer un navigateur pour appeler l'URL http://localhost:4567/ :

Tant qu'on est là, si on essaie d'aller sur une URL qui n'existe pas, comme http://localhost:4567/reverse, on obtient alors la page d'erreur 404 de Sinatra pour indiquer qu'il ne connait pas ce morceau :

Cette page d'erreur nous conseille même sur la route ajouter dans notre fichier pour que cela fonctionne, en l'occurrence :

get '/reverse' do
  "Hello World"
end

Avec Sinatra, c'est pas plus compliqué que ça pour créer des actions correspondant à différentes routes.

Ajouter une vue

Pour l'instant, on va rester sur notre route «'/'» et essayer de faire un peu mieux que de seulement renvoyer une ligne de texte. Pour cela, il faut créer une vue en modifiant le fichier main.rb de la façon suivante :

require 'rubygems'
require 'sinatra'

get '/' do
  erb :home
end

__END__

@@ home

<h1>Reverse</h1>

<p>Welcome to the home page of my very first Sinatra app.</p>

Ce coup-ci, au lieu d'utiliser la dernière ligne du bloc pour dire à Sinatra ce qu'il doit afficher, nous lui avons demandé d'utiliser la vue "home" que nous avons codé en erb (embedded ruby). Cette vue est enregistrée à la fin du fichier, après la ligne __END__ et elle est repéré par le code @@ home.

Pour voir ce que donne cette vue, il faut revenir à l'invite de commande et arrêter le serveur s'il est toujours en cours d'exécution. Ctrl-C =>Sinatra has ended his set (crowd applauds). Puis on relance le serveur avec ruby main.rb et on réaffiche la page http://localhost:4567 :

Créer une vue externe

En fait, on n'est pas obligé de stocker les vues dans le même fichier. Il est bien plus pratique de les enregistrer dans un sous-répertoire "views" de notre projet (soit C:\Ruby\projets\reverse\views dans mon cas).

Là, il suffit de créer le fichier "home.erb" avec le code ci-dessous :

<h1>Reverse</h1>

<p>Welcome to the home page of my very first Sinatra app.</p>

Il est alors possible de simplifier le fichier "main.rb" de la façon suivante :

require 'rubygems'
require 'sinatra'

get '/' do
  erb :home
end

Il ne reste plus qu'à contrôler que tout est ok : Ctrl-C, ruby main.rb, rafraichir la page et vérifier que rien n'a changé.

Créer un layout

D'un point de vue visuel, on peut faire encore mieux en définissant un "layout" qui servira de gabarit pour englober toutes les vues. Cela permet d'éviter de répéter le même code dans toutes les vues de l'application.

Pour cela, on doit juste créer un fichier "layout.erb" dans le sous-répertoire "views" et y saisir le code html ci-dessous :

<!DOCTYPE html>
<html lang="en">
<head>
<title>Reverse!</title>
<meta charset=utf-8 />
</head>
<body>
<h1>Reverse</h1>

<%= yield %>

<p>The first Sinatra project for I Did It My Way</p>
</body>
</html>

Tout ce code html sera toujours affiché à chaque fois qu'une vue sera affichée, à part la ligne <%= yield %> qui sera remplacée par le contenu spécifique de la vue.

Ainsi, si on modifie légèrement le code de la vue "home.erb" :

<h2>Home</h2>
<p>Welcome to the home page. This app is going to be amazing....</p>

Le fait de relancer le serveur et de ré-afficher l'URL http://localhost:4567 doit donner le résultat suivant :

Comme vous pouvez le constater, le sous-titre "Home" et le message "Welcome..." en provenance de la vue "home.erb" apparaissent entre le titre "Reverse" et le paragraphe "The first app...", soit exactement là où se situait la ligne <%= yield %> dans le fichier "layout.erb".

ERB

La balise <%= yield %> est un exemple d'embedded ruby (ou erb en abrégé). On peut ainsi ajouter du code ruby dans les fichiers html en l'insérant à l'intérieur de blocs <% ... %>. C'est très utile dans le cas de conditions if :

<% if something_happens %>
<h1>Something happened</h1>
<% else %>
<h1>Nothing happend</h1>
<% end %>

Si le code ruby est placé dans un bloc <%= ... %>, alors ce code est évalué et son résultat est affiché. Comme par exemple dans le code suivant :

<% title = "Reverse" %>
<h1>
<%= title %>
</h1>

Le premier bloc de code <% ... %> défini une variable appelée "title" et le second bloc de code <%= ... %> évalue cette variable et affiche sa valeur. Même si cet exemple est ultra simple, dans la vrai vie on peut faire des tas de chose très utile grâce à l'embedded ruby.

Définir une variable

Plus concrètement, nous allons utiliser embeded ruby pour définir le titre de notre page. Dans un premier temps, on met à jour le code de "main.rb" :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Home"
  erb :home
end

Celui-ci initialise une variable session nommée @title (c'est une variable session parce que son nom débute par un @). Les variables session sont disponibles dans les autres parties du code, y compris dans les vues. On peut donc maintenant faire référence à notre variable session @title dans notre vue ou même notre layout.

Par conséquent, nous pouvons modifier "layout.erb" pour qu'il utilise notre variable session :

<!DOCTYPE html>
<html lang="en">
<head>
<title>Reverse!</title>
<meta charset=utf-8 />
</head>
<body>
<h1>Reverse</h1>
<h2><%= @title %></h2>

<%= yield %>

<p>The first Sinatra project for I Did It My Way</p>
</body>
</html>

Puis nous pouvons alors supprimer le titre qui était en dur dans la vue "home.erb" :

<p>Welcome to the home page. This app is going to be amazing....</p>

Par acquit de conscience, on peut redémarrer le serveur et contrôler que rien n'a changé, ce qui signifie que notre variable session a bien été prise en compte et que nous pouvons maintenant définir le titre de la page au niveau de l'action.

On va vérifier cela en créant une nouvelle route dans le source "main.rb" :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Home"
  erb :home
end

get '/frank' do
  @title = "My Way"
  erb :home
end

Après avoir encore une fois redémarré le serveur, on peut aller à la page http://localhost:4567/frank pour constater que le sous-titre n'est plus "Home" mais "My Way" :

Mais on continue à voir presque la même chose, étant donné qu'on utilise la même vue dans les deux cas. On va donc créer une vue différente qui s'affichera pour la route "/frank". Pour cela, on saisi le code suivant dans un fichier "frank.erb" à créer dans le sous-répertoire "views" :

<p>
And now, the end is here
And so I face the final curtain
My friend, I'll say it clear
I'll state my case, of which I'm certain
I've lived a life that's full
I traveled each and ev'ry highway
And more, much more than this, I did it my way
</p>

Il faut aussi changer la ligne erb:home par erb:frank dans le cas de la route "/frank" avant de redémarrer le serveur et de ré-afficher la page http://localhost:4567/frank pour voir ce que cela donne.

Poster quelque chose

Jusqu'à présent on n'a pas fait grand chose d'autre que des pages statiques. Mais quand on crée une application web, c'est quand même pour avoir un peu d'interaction avec le visiteur. On va donc rendre les choses un peu plus intéressante en commençant par créer un formulaire dans notre page d'accueil. Pour cela, on remplace tout le code de "home.erb" par le code suivant :

<form action="/reverse" method ="post" accept-charset="utf-8">
<input type="text" id="phrase" name="phrase" value="Write something...">
<input type="submit" value="...and reverse it!">
</form>

Une fois que c'est fait, on a aussi besoin d'une nouvelle action pour prendre en compte le formulaire lorsqu'il est envoyé. Si vous observez le code html de "home.erb", vous pouvez voir que le formulaire va être posté à l'URL "/reverse" avec une méthode POST.

Normalement, c'est le moment où vous devriez vous rendre compte que la syntaxe de Sinatra est bien faite. Et vous devriez même avoir une idée ce que nous allons ajouter dans le fichier "main.erb" :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Home"
  erb :home
end

post '/reverse' do
  params.inspect
end

L'avant-avant dernière ligne (l'antépénultième pour les érudits) défini la nouvelle action qui va gérer la route "/reverse". Cette action est définie pour une route de type POST, ce qui signifie qu'elle ne sera activé que pour une requête POST (ce qui correspond à l'envoi d'un formulaire). Ca c'est bon ? Mais par contre, c'est quoi cette ligne params.inspect ? "params" est une collection qui contient toutes les informations qui ont été envoyées en tant que paramètre (aussi bien à travers un formulaire que via l'URL) Par conséquent, params.inspect affiche les paires clé/valeur correspondantes à tous ces paramètres.

Allez. On relance le serveur, on accède à la page http://localhost:4567/, on saisi une phrase au hasard et on clique sur le bouton [... and reverse it] :

Cela signifie que la clé "phrase" contient la valeur "I Did It My Way". Et nous avons une clé "phrase" parce que le formulaire dans "home.erb" contient une balise input dont l'attribut name est "phrase". Il est possible d'accéder à n'importe quel paramètre stocké dans la collection "params" en employant la syntaxe params[:key]. Par exemple, params[:phrase] renverra "I Did It My Way".

Supposons que l'on ait le formulaire suivant :

<form action="/reverse" method ="post" accept-charset="utf-8">
<input type="text" name="name">
<input type="text" name="email">
<input type="text" name="password">
<input type="submit" value="submit">
</form>

On va pouvoir accéder aux valeurs de ce formulaire en utilisant params[:name], params[:email] et params[:password].

Maintenant que nous savons comment accéder aux données d'un formulaire, nous allons pouvoir faire quelque chose du texte saisi dans notre vue. Pour cela, nous ajoutons le code ci-dessous au fichier "main.rb" :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Enter Your text here"
  erb :home
end

post '/reverse' do
  @title = "Here's Your Reversed Text:"
  params[:phrase].reverse
end

On re-démarre le serveur, on ré-accède à la page http://localhost:4567/, on re-saisi une phrase au hasard et on re-clique sur le bouton [... and reverse it]. Cette fois-ci, on doit voir la phrase saisie affichée à l'envers, de la droite vers la gauche :

On obtient ce résultat parce que la dernière ligne de la méthode est params[:phrase].reverse. Et si vous vous souvenez bien, la dernière ligne d'une méthode est ce qui est renvoyé pour l'URL demandée. params[:phrase] correspond au texte entré dans le formulaire et le .reverse à sa suite correspond à la méthode "reverse" pour les chaines de caractères. Et cette méthode fait exactement ce que son nom laisse supposer, soit inverser l'ordre des caractères d'une phrase. Coup de bol, c'est aussi ce à quoi notre application était destinée !

Faire un postback

On peut pousser le bouchon encore plus loin et utiliser la même URL pour nos deux pages (l'affichage du formulaire et l'affichage du résultat de notre application). C'est possible parce que pour afficher le formulaire on fait une requête GET et que pour inverser le texte on envoie le formulaire avec une requête POST. Par conséquent, on peut donc gérer ces deux actions avec la même route, mais deux actions différentes.

On peut donc réécrire "main.rb" :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Enter Your text here"
  erb :home
end

post '/' do
  @title = "Here's Your Reversed Text:"
  params[:phrase].reverse
end

Cette fois-ci, l'URL de la route est toujours la même, mais la méthode HTTP est différente (soit un GET, soit un POST). Le fait de poster vers soit-même s'appelle un "postback". En plus du GET et du POST, Sinatra gère les deux autres méthodes HTTP, à savoir PUT et DELETE. Nous n'en avons pas besoin pour cette application, mais nous aurons l'occasion d'y revenir dans un autre projet.

Pour que le postback fonctionne, il faut aussi penser à modifier l'attribut action du formulaire au niveau de la vue "home.erb" pour qu'il pointe vers la même URL :

<form action="/" method ="post" accept-charset="utf-8">
<input type="text" id="phrase" name="phrase" value="Write something...">
 <input type="submit" value="...and reverse it!">
</form>

Et comme pour l'instant le résultat de notre application se présente seulement sous la forme d'une ligne de texte, on va enjoliver ça en créant une nouvelle vue "reverse.erb" qui va nous permettre d'afficher ce résultat de façon un peu plus élégante :

<h3>Here is your reversed text......</h3>
<p><strong><%= @reversed_text %></strong></p>

Il suffit alors de référencer cette vue dans le fichier "main.rb", dans lequel nous initialisons la variable session "@reversed_text" que nous avons utilisée dans notre nouvelle vue :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Enter Your text here"
  erb :home
end

post '/' do
  @title = "Here's Your Reversed Text:"
  @reversed_text = params[:phrase].reverse
  erb :reverse
end

Si on relance tout et que l'on fait tout bien comme il faut, on arrive sur l'écran suivant :

Les paramètres nommés

On pourrait en rester là puisque l'application fait ce qui était prévu. Mais on peut faire mieux, comme par exemple permettre à l'utilisateur d'indiquer la phrase qu'il veut inverser directement au niveau de l'URL. OK, mais comment faire pour retrouver le texte qui a été proposé ? Pas compliqué, il faut juste ajouter une route avec un paramètre nommé :

get '/:phrase' do

Cela va ajouter automatiquement un paramètre "phrase" à la collection "params". On retrouvera donc tout ce que l'utilisateur aura indiqué dans l'URL en utilisant params[:phrase]. Par exemple, pour l'URL http://localhost:4567/frank on aura params[:phrase] égal à "frank" et pour l'URL http://localhost:4567/sinatra on aura params[:phrase] égal à "sinatra" .

On va donc compléter notre fichier "main.rb" pour lui ajouter du code destiné à gérer cette route :

require 'rubygems'
require 'sinatra'

get '/' do
  @title = "Enter Your text here"
  erb :home
end

post '/' do
  @title = "Here's Your Reversed Text:"
  @reversed_text = params[:phrase].reverse
  erb :reverse
end

get '/:phrase' do
  @title = "Here's Your Reversed Text:"
  @reversed_text = params[:phrase].reverse
  erb :reverse
end

Voyons voir si ça marche. Tout ce qu'il y a à faire (après avoir relancé le serveur pour la dernière fois), c'est d'appeler l'URL http://localhost:4567/ suivi d'une phrase de votre choix et de vérifier que ce texte s'affiche bien à l'envers, comme dans la copie d'écran ci-dessous :

Voilà c'est fini

Et ainsi se termine le tutoriel consacré à la première application Sinatra proposée par Darren Jones (@daz4126) dont ce billet constitue une traduction très très libre.

aucun commentaire

jeudi 22 juillet 2010

Installer Sinatra sous Windows 7

Par Michel le jeudi 22 juillet 2010, 13:47 - Traductions

Ceci est une adaptation en français du tutoriel "Installing Sinatra" de Darren Jones.

Je suis tombé sur une super série de tutoriels pour apprendre à utiliser Sinatra. C'est le résultat de la bonne résolution de Daz (Darren Jones) pour l'année 2010 et ça s'appelle I Dit It My Way ou "The Sinatra Songbook Project".

C'est l'occasion pour se mettre à Sinatra et je me suis donc lancé dans l'installation des outils nécessaires à son utilisation, en suivant un des premiers tutoriels : Installing Sinatra.

Installer Ruby sur Windows

il faut commencer par installer Ruby étant donné que ce n’est pas quelque chose de déjà présent sur mon PC. C’est pas compliqué du tout. Il suffit d’utiliser RubyInstaller pour Windows (la façon la plus simple d’installer Ruby sous Windows) qui va s’occuper de tout.

Cliquer sur le gros bouton rouge « Download » sur la page d’accueil
Sélectionner la version la plus récente de RubyInstallers (soit Ruby 1.9.1-p429 à ce jour)
Enregistrer le fichier sur le disque dur (soit dans le répertoire C:\Temp dans mon cas)
Double-cliquer sur C:\Temp\rubyinstaller-1.9.1-p429.exe pour lancer l’installation
Le seul truc un peu important, c’est de demander à faire l’installation dans C:\Ruby (et pas C:\Ruby191 comme le propose l’installeur) et de cocher les choix « Add Ruby executables to your PATH » et « Associate .rb and .rbw files with this Ruby installation ».

L’installation est très rapide et au final on se retrouve avec un répertoire « C:\Ruby » d’une cinquantaine de méga.

Installer Sinatra sur Windows

On entre ensuite dans le vif du sujet qui consiste à installer Sinatra. Pour cela, il faut ouvrir une « Invite de commandes » et aller dans le répertoire « C:\Ruby » et lancer la commande suivante :

C:\Ruby>gem install sinatra

Ce qui donne presque aussitôt :

Successfully installed rack-1.2.1
Successfully installed sinatra-1.0
2 gems installed
Installing ri documentation for rack-1.2.1...
Installing ri documentation for sinatra-1.0...
Updating class cache with 0 classes...
Installing RDoc documentation for rack-1.2.1...
Installing RDoc documentation for sinatra-1.0...

C:\Ruby>

Ca y est, mon PC devrait contenir Ruby + Sinatra !

Créer une première application Sinatra

On va alors pouvoir tester que ça marche en codant notre toute première application Sinatra. Pour cela, il suffit d'ouvrir Notepad pour créer le fichier C:\Ruby\test.rb avec le code suivant :

require 'rubygems'
require 'sinatra'
get '/hi' do
  "I Did It My Way!"
end

Puis on demande à Ruby d’exécuter ce programme :

C:\Ruby>ruby test.rb

Ce qui donne :

== Sinatra/1.0 has taken the stage on 4567 for development with backup from WEBrick
[2010-07-22 12:07:23] INFO  WEBrick 1.3.1
[2010-07-22 12:07:23] INFO  ruby 1.9.1 (2010-07-02) [i386-mingw32]
[2010-07-22 12:07:23] INFO  WEBrick::HTTPServer#start: pid=952 port=4567

Ca marche ! Il ne reste plus qu’à lancer un des navigateurs installé sur le PC pour aller voir ce que donne l’adresse « http://localhost:4567/hi ». Et là, je retrouve bien le message attendu, à savoir « I Dit It My Way ! ».

C’est magnifique ! Tout fonctionne comme prévu. Il n'y a qu'à arrêter l'exécution du programme test.rb par un simple Ctrl-C et se préparer pour la suite des tutoriels...

== Sinatra has ended his set (crowd applauds)
[2010-07-22 12:10:43] INFO  going to shutdown ...
[2010-07-22 12:10:43] INFO  WEBrick::HTTPServer#start done.

2 commentaires

blog.pagesd.info