Tutoriel HAML

Le plugin HAML pour Ruby on Rails s'installe comme tout autre plugin. Il est téléchargeable à l'adresse http://haml.hamptoncatlin.com/download/.

Si vous débutez avec Ruby on Rails, voici la procédure à suivre pour installer ce plugin :
Placez-vous à la racine de votre application Rails, et entrez la commande suivante :

ruby script/plugin install http://svn.hamptoncatlin.com/haml/tags/stable

Le script se charge alors de télécharger les fichiers nécessaires et les place dans le dossier vendor/plugins/.

Une fois le plugin pour Rails installé, vous pouvez commencer à écrire vos vues avec HAML. Pour l'utiliser à la place de ERB, il vous suffit de nommer votre fichier avec l'extension haml. Par exemple, le template de l'action inscrire du controlleur membres sera app/views/membres/inscrire.haml au lieu de app/views/membres/inscrire.rhtml. De plus, vous pouvez parfaitement écrire certaines vues en HAML et d'autres en RHTML, voire faire un partial en HAML et l'inclure dans une vue en RHTML et vice-versa. La transition entre RHTML et HAML est donc très facile, car elle peut se faire petit à petit. Sachez seulement que si les deux fichiers existent, c'est le fichier HAML qui sera utilisé.

HAML utilise une indentation de deux espaces pour sa mise en forme, il est donc important d'utiliser un éditeur bien configuré pour nous faciliter la tâche. Il existe actuellement des plugins pour les éditeurs suivants :

• TextMate ;
• Aptana/RadRails (Eclipse) ;
• Jedit ;
• (G)Vim ;
• Komodo ;
• Emacs.

Ces plugins ont l'avantage d'ajouter également la coloration syntaxique, et quelques raccourcis qui vous faciliteront la tâche lorsque vous maîtriserez ce langage.

Vous pourrez retrouver les liens vers ces plugins sur http://groups.google.com/group/haml/web/syntax-highlighting. Je me suis intéressé en particulier à TextMate et Aptana/RadRails pour vous proposer une méthode d'installation détaillée. N'hésitez pas à consulter la page des plugins pour installer le support de HAML dans votre éditeur favori.

II-B-1. Installation du plugin pour TextMate▲

mkdir -p /Library/Application Support/TextMate/Bundles
cd /Library/Application Support/TextMate/Bundles
svn co http://macromates.com/svn/Bundles/trunk/Bundles/Haml.tmbundle

II-B-2. Installation du plugin pour Aptana/RadRails▲

IV-A-1. Les balises▲

%p
%li
%br

%meta{'content-type' => 'text/html', 'charset' => 'utf8'}
%label{:for => 'user_login'}
 
%ul{:id => 'menu'}
%p{:class => 'details'}

IV-A-2. Un peu de CSS▲

%ul#menu    =>    <ul id="menu">

%p.details    =>    <p class="details">

#sidebar    =>    <div id="sidebar">
 
.footer     =>    <div class="footer">

#colonne.gauche             =>    <div id="colonne" class="gauche">
 
#messages.colonne.gauche    =>    <div id="messages" class="colonne gauche">

IV-B-1. Afficher du contenu dynamique▲

= @article.titre      =>    Introduction au moteur de template HAML
 
%p= @article.titre    =>    <p>Introduction au moteur de template HAML</p>

%p= link_to "Accueil", accueil_path    =>    <p><a href="/">Accueil</a></p>

IV-B-2. Tests et boucles▲

- if logged_in?
  Bienvenue dans votre espace personnel
- else
  Accès refusé

%ul
  - @articles.each do |article|
    %li= article.title

L'imbrication des balises et des blocs se fait simplement en fonction de l'indentation. Il n'y a pas de 'end' ou de balises fermantes avec HAML. L'indentation en HAML est aussi importante que le code, car elle définit la portée des éléments. Ainsi vous pouvez changer facilement et rapidement l'imbrication des balises, car tous les éditeurs textes ont un moyen d'indenter ou désindenter les lignes sélectionnées. En revanche, cela peut vous jouer des tours si vous n'y faites pas attention.

<div id="content">
  <div class="left column">
    <h2>Bienvenue dans notre site !</h2>
    <p>
      <%= print_information %>
    </p>
  </div>
  <div class="right column">
    <%= render :partial => 'sidebar' %>
  </div>
</div>

L'équivalent de ce code HTML sera :

#content
  .left.column
    %h2 Bienvenue dans notre site !
    %p= print_information
  .right.column= render :partial => "sidebar"

Avant d'aller plus loin, prenez quelques minutes pour convertir un template d'une de vos applications. N'ayez pas d'inquiétude, si vous faites une erreur, il vous suffira de supprimer le fichier .haml que vous avez créé. Convertir quelques-uns de vos templates vous permettra de bien vous familiariser avec le langage. Dans le reste de cet article, vous trouverez quelques conseils et astuces pour vous aider à améliorer encore la lisibilité de vos vues.

Un des premiers problèmes rencontrés lorsque l'on débute avec HAML est la gestion des balises inline, c'est-à-dire :
« Comment faire si je veux mettre un mot en gras ou en italique au milieu d'une phrase ? »
En HAML, la représentation suivant la structure du document serait :

%p
  Ceci est un paragraphe avec un mot en
  %strong gras
  et en
  %em italique
  \.

Ce n'est pas très lisible… Cependant dans ce cas, on peut écrire simplement :

%p
  Ceci est un paragraphe avec un mot en  <strong>gras</strong> et en <em>italique</em>.

Qui sera compilé en :

<p>
  Ceci est un paragraphe avec un mot en  <strong>gras</strong> et en <em>italique</em>.
</p>

De la même manière, pour interpréter des valeurs, plutôt que d'écrire :

%p
  Prix :
  = #{produit.prix}
  ?

Il suffit de faire :

%p= "Prix : #{produit.prix}?"

On peut également utiliser un double égal qui évite l'utilisation de guillemets. Ce code ci-dessous est strictement équivalent au code précédent :

%p== Prix : #{produit.prix}?

On peut aussi utiliser les helpers, par exemple link_to pour faire un lien :

%p== Un lien vers la page #{link_to 'contact', contact_url}.

À l'inverse, vous aurez parfois besoin d'insérer du code sur plusieurs lignes. Pour cela, on utilise le caractère | (« pipe ») à la fin de chaque ligne. Par exemple pour un helper particulièrement long :

%p= link_to_remote "Supprimer", |
  :url => {:action => 'delete_profile_from_duel', :id => 2}, |
  :before => "Element.show('wait_icon')", |
  :complete => "Element.hide('wait_icon')" |

Notez que cette syntaxe est un peu lourde, mais peut être très souvent évitée en utilisant les mécanismes de Rails. La vocation d'HAML est également de vous inciter à utiliser au mieux les Helpers et les routes nommées : si votre code n'est pas assez clair, refactorisez !

Il n'est pas possible d'utiliser les raccourcis # et . pour spécifier dynamiquement un id ou une classe, il faut passer par un Hash dans lequel n'importe quel code Ruby est accepté :

- @items.each do |item|
  %tr{ :class => cycle('even', 'odd') }
    %td= item.titre
    %td= item.description

Contrôleur :
@article = Article.find(3)
Vue :
%p[@article]     =>    <p id="article_3" class="article">

V-E-1. Doctype▲

!!!
%html
  %head
    %title Utilisation de !!!
  %body
    %h1 Exemple de document HAML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
    <title>Utilisation de !!!</title>
  </head>
  <body>
    <h1>Exemple de document HAML</h1>
  </body>
</html>

!!! 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
!!! strict
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
!!! frameset
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
 
!!! 1.1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 
!!! xml iso-8859-1
<?xml version='1.0' encoding='iso-8859-1' ?>

V-E-2. Commentaires▲

/
  %p Ceci ne sera pas affiché ...

<!--
  <p>Ceci ne sera pas affiché</p>
-->

/[if IE]
  = stylesheet_link_tag 'ie'

<!--[if IE]>
  <link href="/stylesheets/ie.css" media="screen" rel="Stylesheet" type="text/css" />
<![endif]-->

V-E-3. Échappement▲

%p
  \- Ceci ne sera pas interprété comme du code ...

<p>
  - Ceci ne sera pas interprété comme du code ...
</p>