Contrôler et documenter les variables des partials Ruby on Rails

Les partials dans Ruby on Rails peuvent rapidement devenir un enfer à gérer car le seul moyen d’avoir la liste des variables (locals dans le jargon Rails) utilisées par un partial est d’aller directement lire son code source, comportant souvent plusieurs centaines de lignes de code HTML…

Depuis la sortie Ruby on Rails 7.1, il est possible d’utiliser des magic comments en haut de ses partials pour contraindre et documenter l’utilisation des locals dans ce partial.

Voyons tout de suite comment cela fonctionne. 👏

Commençons par définir les variables du partial de la manière suivante :

# app/views/users/_user_card.html.erb

<%# locals: (name:, email:) -%>

My name is <%= name %>
Reach me at <%= email %>

On passe ensuite ces variables depuis le template dans le hash locals.

# app/views/users/show.html.erb

<%= render partial: "user_card",
  locals: {
    name: @user.name.full,
    email: @user.email
  }
%>

Tel que défini, les variables name et email sont obligatoires, leur absence provoquera une erreur.

Supprimons la variable email pour voir ce que cela donne.

# app/views/users/show.html.erb

<%= render partial: "user_card",
  locals: {
    name: @user.name.full
  }
%>

Une erreur est immédiatement levée.

ActionView::Template::Error (missing local: :email):

app/views/users/show.html.erb:1

Tentons maintenant de passer une variable non définie.

# app/views/users/show.html.erb

<%= render partial: "user_card",
  locals: {
    name: @user.name.full,
    email: @user.email,
    phones: @user.phones
  }
%>

Une nouvelle erreur est levée, cette fois pour nous dire que cette variable n’est pas acceptée, car non déclarée dans le partial.

ActionView::Template::Error (unknown local: :phones):

app/views/users/show.html.erb:1

Grâce à ces deux erreurs, nous sommes maintenant certains des variables acceptées par notre partial et nous avons en même temps gagné un peu de documentation ! 🎉

Valeurs par défaut

Il est possible de donner des valeurs par défaut aux variables, ce qui nous permettra de ne pas avoir besoin de les passer à chaque rendu.

# app/views/users/_user_card.html.erb

<%# locals: (name:, email:, phones: []) -%>

My name is <%= name %>
Reach me at <%= email %>
You can also give me a call at <%= phones.join(", ") %>

Ainsi, il est possible de ne passer fournir au partial la variable phones sans que l’appel à la méthode join n’échoue, car elle a été appelée sur nil.

Désactivation des variables

Si vous ne souhaitez qu’aucune variable ne soit passée à votre partial c’est également possible !

# app/views/users/_user_card.html.erb

<%# locals: () -%>

My name is John
Reach me at john@doe.com
You can also give me a call at 0123456789

Si l’on tente de passer des variables lors du rendu, l’erreur ci-dessous sera levée.

ActionView::Template::Error (no locals accepted):

app/views/users/show.html.erb:1

Voilà qui conclut notre petit tour de cette nouveauté de Rails 7.1 nous permettant d’exercer un meilleur contrôle sur les variables passées à nos partials tout en les documentant.

Nathan Le Ray