Ce document décrit exactement ce que ce pipeline accepte et exécute. Là où il diverge de la section 7 de docs/design.md (le projet de spécification initial) ou de ce qu’attendrait un développeur Rails, c’est le code qui a raison, et ce document le dit (cherchez « Tel qu’implémenté »).
Ce qui est du Ruby ici, et ce qui n’en est pas
Les templates ne sont pas du Ruby. Spinel (le compilateur AOT de Ruby de Matz que vise cybertrain) n’a pas d’eval, donc « interpréter le Ruby propre à la vue au moment de la requête » n’a jamais été envisageable (D9 dans docs/design.md) ; ce qui s’exécute à la place est une petite grammaire fermée qui ne fait qu’emprunter une syntaxe d’allure ERB/Ruby. Il n’y a pas de Ruby arbitraire dans une balise — seulement ce que ExprParser (parser.rb) reconnaît comme instruction ou expression. Il n’y a pas d’eval, de send, d’instance_eval, de définitions de méthodes/classes/modules, de require, d’exceptions (begin/rescue), d’intervalles, de regex, ni d’affectation multiple. Les blocs n’existent que là où ce document les énumère : les boucles each/each_with_index/each_slice, un ensemble fixe de méthodes d’Array et de Hash (map, select, sum, group_by... — voir Blocs), les appels de helpers (form_with(...) do |f| ... end) et le constructeur tag. Chaque appel de méthode (recv.name) est résolu par des tables de dispatch case écrites à la main dans interpreter.rb, indexées par la classe Ruby du receveur à l’exécution ; un nom absent de la table de ce type échoue avec une RuntimeError — il n’y a pas de method_missing, pas de réflexion, et (d’après Interpreter#call_method) c’est précisément l’absence de send dans Spinel qui fait que c’est un case et non une recherche par métaprogrammation. Un template ne peut faire que ce que décrit ce document.
Où cela se trouve dans le sourceles huit fichiers du pipeline de templates
Le pipeline se trouve dans cybertrain/template/ :
| Fichier | Rôle |
|---|---|
lexer.rb |
Sépare le source en balises <% %>/<%= %>/<%== %>/<%# %> et en texte brut |
parser.rb |
TreeBuilder imbrique les balises en un AST ; ExprParser analyse la grammaire des expressions à l’intérieur d’une balise |
ast.rb |
Les classes de nœuds de l’AST que produit le parseur |
inode.rb |
Compile aplatit l’AST en INode monomorphes (un « kind » entier plus des emplacements typés) pour une interprétation rapide |
interpreter.rb |
Parcourt les INode dans un env (Hash<String, value>) ; détient toutes les tables par type de « quelles méthodes existent » |
helpers.rb |
link_to, form_with, render, pluralize, ... — tout ce qu’un template appelle sans receveur |
form_builder.rb |
Le f passé par form_with(...) do |f| ... end |
engine.rb |
Charge les sources .html.erb — depuis le disque sous une racine, ou depuis la table intégrée gen/views.rb (Engine.embedded) —, les analyse (et éventuellement les met en cache), et les rend avec un layout |
Balises
| Balise | Signification |
|---|---|
<% code %> |
Exécute une instruction ; ne produit aucune sortie |
<%= expr %> |
Évalue expr et l’affiche, échappé pour le HTML |
<%== expr %> |
Évalue expr et l’affiche sans échappement |
<%# comment %> |
Ignoré (sauf la forme locals: de la ligne 1, ci-dessous) |
Contrôle des espaces (Lexer.tokenize) :
- Une balise
<% %>/<%# %>qui est la seule chose sur sa ligne (rien que des espaces/tabulations de part et d’autre jusqu’aux sauts de ligne) avale silencieusement sa propre indentation et son saut de ligne final, comme le mode trim de l’ERB de Rails.<%= %>/<%== %>ne sont jamais rognées automatiquement de cette façon, même seules sur une ligne. <%-supprime explicitement les espaces/tabulations qui précèdent la balise, et-%>supprime le saut de ligne qui la suit immédiatement — pour tout type de balise. Les deux sont sans effet quand autre chose que des espaces occupe ce côté de la ligne.<%%dans le texte est un<%littéral ;%%>dans une balise est un%>littéral qui ne ferme pas la balise.<% # a Ruby-style comment %>(une balise de code dont le contenu commence par#) est ignorée comme<%# %>. Un commentaire après du vrai code dans la même balise n’est pas pris en charge —<% x = 1 # note %>est uneSyntaxError.- Les balises non terminées lèvent une erreur dès l’analyse lexicale :
"posts/show:2: unterminated <% tag".
Le commentaire de locals stricts
Une balise de commentaire dont le contenu commence par locals: et qui est la toute première balise du fichier, sur la ligne 1, déclare les seules variables locales qu’accepte un template (presque toujours un partiel) :
<%# locals: (post:, comment:) %>
<%= post.title %>
<%# locals: () %>(liste vide) signifie « ce partiel ne prend aucune variable locale ».- Chaque entrée doit être un simple
name:en minuscules (Lexer.identifier?n’accepte que[a-z_][a-z0-9_]*). Tel qu’implémenté : contrairement à Rails 7.1, les entrées ne peuvent pas porter de valeur par défaut —<%# locals: (post:, comment: nil) %>, la forme exacte que prend en charge Rails 7.1, est uneSyntaxError:"t:1: bad strict locals entry 'comment: nil' (expected name:)", carcomment: nilne se termine pas par:. Chaque variable locale déclarée est de fait obligatoire. Une spécification mal formée (parenthèses manquantes) lève"t:1: bad strict locals comment (expected locals: (name:, ...))". - Sans ce commentaire, un template ne déclare aucune liste de variables locales :
rendertransmet toutes les variables locales qu’il reçoit, sans vérification, et le template peut aussi lire tout ce qui est déjà présent dans l’environnement de l’appelant (voir Layouts,yield,content_for, partiels). - Si quoi que ce soit précède le commentaire sur une ligne antérieure (ne serait-ce qu’une ligne vide), ce n’est qu’un commentaire ordinaire et inerte, pas une déclaration de locals.
Expressions
Littéraux
| Littéral | Syntaxe | Remarques |
|---|---|---|
| Integer | 1, 1_000 |
tirets bas autorisés ; ni hexadécimal, ni octal, ni binaire, ni exposant |
| Float | 2.5, 12_3.4_5 |
un chiffre est requis de chaque côté du . ; pas de forme à exposant |
| String | "...", '...' |
les guillemets doubles interpolent et acceptent les échappements ; les guillemets simples ne comprennent que \' et \\ |
| Symbol | :title |
caractères d’identifiant uniquement — pas de :"quoted", pas de symboles d’opérateur à la :+ |
nil / true / false |
||
| Array | [1, "a", :b], [] |
les éléments sont des expressions complètes |
| Hash | { a: 1, b: "x" }, {} |
clés de style symbole uniquement, même forme que les arguments nommés ; pas de hashrocket "key" => value |
Les chaînes entre guillemets doubles interpolent #{...} (n’importe quelle expression complète, imbricable) et acceptent \n \t \r \0 \e \s, \", \\ ; tout autre caractère échappé passe tel quel. Une chaîne sans #{} se compile en un littéral simple ; une chaîne avec interpolation se compile en une séquence de morceaux littéraux et d’expressions.
Variables
@ivarlit directementenv["ivar"]— le@n’est que de la syntaxe de surface ; selon D9, « post est à la fois@postet la variable localepost» dans un seul Hash d’environnement. Une ivar absente vaut simplementnil:[<%= @missing %>]rend[], jamais une erreur.- Un nom local nu (
post,title) lit aussienv["name"], mais si la clé n’existe pas du tout, l’interpréteur le traite plutôt comme un appel de helper sans argument. Si la clé existe (même liée ànil— une variable locale stricte déclarée mais non passée, par exemple), sa valeur est renvoyée sans repli sur un helper. C’est pourquoi<%= csrf_meta_tags %>et<%= flash %>fonctionnent sans parenthèses, et pourquoi<%= nope %>échoue avec"undefined helper 'nope'"plutôt qu’avec une erreur « pas de telle variable locale ». - Les variables locales viennent des paramètres de bloc de
each/each_with_index, du paramètre de bloc deform_with, des locals stricts d’un partiel et de<% name = expr %>.
Appels de méthode
recv.method
recv.method(arg1, key: value)
recv&.method # sûr face à nil : court-circuite vers nil, arguments non évalués, si recv vaut nil
method(arg1, key: value) # un appel de helper : pas de receveur
method arg1, key: value # même appel, sans parenthèses (syntaxe « commande »)
- Une liste d’arguments sans parenthèses (« commande ») n’est ouverte que pour l’appel le plus externe d’une expression :
link_to "Show", post_path(post)fonctionne, maislink_to "Show", post_path postest uneSyntaxError— les appels internes ont besoin de leurs propres parenthèses. - Aucun espace n’est autorisé entre la cible d’un appel et sa
(ouvrante :link_to("x")etlink_to "x"fonctionnent tous deux ;link_to ("x")est uneSyntaxError. yieldetyield :keysont toujours analysés comme des appels (voir Layouts,yield,content_for, partiels).- Un mot nu commençant par une majuscule est rejeté d’emblée —
"constants are not supported: 'Time'"— les templates ne peuvent pas atteindre les constantes Ruby. - Ces mots sont réservés et rejetés avec un message dédié (
"'x' is not supported in templates") partout où une expression est attendue :and or not do end if unless elsif else then while until def class module begin rescue return.caseetwhensont des instructions à part entière (case) ; à l’intérieur d’une expression (<%= case x %>), ils sont rejetés de la même façon.
Opérateurs, priorité (de la plus faible à la plus forte)
?: ternary, right-associative on both branches
||
&&
== !=
< > <= >=
+ -
* / %
! - (unary, prefix)
. &. [] (method call / safe-nav / indexing, left-to-right chaining)
&&/|| renvoient l’opérande, pas un booléen converti (nothing || title s’évalue en title, pas en true). Les conditions testent la véracité : seuls nil et false sont faux, comme en Ruby — 0, "" et les tableaux/hashs vides sont vrais (<% if 0 %>yes<% end %> affiche yes).
L’indexation s’écrit target[index] sans espace avant [ (items [0] est une erreur de syntaxe, items[0] non), et s’enchaîne comme tout suffixe : h["k"].first, params[:id].
Instructions
Une balise <% %> contient exactement une instruction : une affectation, ou une expression évaluée pour son effet de bord (valeur ignorée). <%= %>/<%== %> ne contiennent jamais qu’une expression — <%= x = 1 %> est une SyntaxError.
Conditions
<% if cond %>...<% elsif other %>...<% else %>...<% end %>
<% unless cond %>...<% else %>...<% end %>
unless/else/elsif suivent les règles de Ruby ; un elsif après else, un else/elsif/end isolé, ou un bloc jamais fermé par end sont tous des SyntaxError qui nomment la ligne d’ouverture.
case
<% case @article.status %>
<% when :draft, :review %>
<span class="badge">unpublished</span>
<% when :published %>
<span class="badge">live</span>
<% else %>
<span class="badge">?</span>
<% end %>
- Le sujet est évalué une fois ; les valeurs de chaque
when(une ou plusieurs, séparées par des virgules) sont comparées dans l’ordre avec le==du template, et la première branche qui a une valeur égale s’exécute. Les nombres se comparent par valeur (1correspond à1.0) ; les Strings et les Symbols par valeur et par type ("a"ne correspond pas à:a) ; les enregistrements comme le fait==(classe etid) ; les Arrays et les Hashs comme le fait==(par valeur, élément par élément) ; uneSafeStringet uneStringde même texte sont égales. Il n’y a pas de===: ni intervalles, ni classes, ni regex aprèswhen. elses’exécute quand aucune valeur n’a correspondu ; sanselseet sans correspondance, rien n’est affiché.- Seul du texte blanc (indentation, retours à la ligne) peut se trouver entre
caseet son premierwhen; il est ignoré. Tout autre chose à cet endroit est uneSyntaxError("text between 'case' and its first 'when'"). - Un
whenhors d’uncase("'when' without 'case'"), uncasesans sujet ou sanswhen, unwhensans valeur ou aprèselse, et uncasejamais fermé parendsont desSyntaxErrorqui nomment la ligne.thenreste réservé :<% when :a then x %>est uneSyntaxError. - Une variable locale affectée pour la première fois dans une branche suit la règle de localité au bloc du bloc où elle se trouve, comme avec
if.
Boucles
<% @posts.each do |post| %>...<% end %>
<% @counts.each do |name, n| %>...<% end %> <%# Hash: name=key, n=value %>
<% items.each_with_index do |item, i| %>...<% end %>
each/each_with_indexne sont reconnus que comme suffixe de l’en-tête du bloc (x.each do |...|) ; la collection peut être n’importe quelle expression, y compris un appel qui prend un bloc (<% items.group_by { |i| i.kind }.each do |kind, list| %>). Tel qu’implémenté, les deux exigent de déclarer un ou deux paramètres de bloc —xs.each do endest uneSyntaxError(« takes one or two block parameters »), là où le Ruby ordinaire en accepte zéro.<% x.each_slice(n) do |slice| %>...<% end %>parcourt les tranches denéléments (la dernière peut être plus courte), et exige lui aussi un ou deux paramètres ; avec deux, une tranche est déstructurée (do |a, b|), le second valantnilquand la tranche est courte.- Array + un paramètre : l’élément. Array + deux paramètres : un élément
Arrayest déstructuré (a, b = item[0], item[1]) ; sinon, le second vautnil. each_with_indexsur un Array :item, i. Sur un Hash : le premier paramètre est une paire[key, value], le second l’index.eachsur un Hash avec deux paramètres : directementkey, value; avec un paramètre : une paire[key, value].- Itérer sur
nil, unTimeou n’importe quel scalaire est uneRuntimeError("undefined method 'each' for Time") — jamais une absence d’effet silencieuse. - Un paramètre de bloc masque une variable locale externe du même nom uniquement pendant la boucle, et est supprimé ensuite (
refute env.key?("item")une fois la boucle terminée). Une variable qui existait avant le bloc est la même variable à l’intérieur (visible aussi après la boucle) ; une variable affectée pour la première fois dans le bloc est locale au bloc —nilau début de chaque itération, disparue ensuite.
Appels avec bloc (helpers)
do ... end est aussi la façon dont un appel de helper sans receveur prend un bloc (pour un appel avec receveur, voir Blocs) :
<%= form_with(model: @post) do |f| %>...<% end %> <%# printed: form_with returns the <form> HTML %>
<% content_for :title do %>Hi<% end %> <%# not printed: content_for returns "" %>
L’affichage ou non du résultat du bloc suit la balise : <%= helper do |x| %> l’affiche, <% helper do |x| %> l’ignore. Exactement un paramètre de bloc est lié, toujours ; un bloc de helper ne reçoit jamais d’index ni de seconde valeur.
Blocs
Un appel avec receveur peut prendre un bloc, { |x| expr } ou do |x| ... end, avec zéro, un ou deux paramètres. Les méthodes qui en acceptent un sont fixées par type ; un bloc ailleurs est une SyntaxError levée à l’exécution de l’appel ("String#upcase takes no block"), et une méthode que le type n’a pas donne l’habituel "undefined method 'x' for Array", avec ou sans bloc.
| Receveur | Méthodes qui prennent un bloc | La valeur du bloc sert de |
|---|---|---|
Array |
map select reject find any? all? none? count sum sort_by min_by max_by group_by |
valeur transformée, test, terme de la somme, clé de tri, clé de groupe |
Hash |
map select reject find any? all? none? count sum sort_by min_by max_by group_by |
la même chose, le bloc voyant |key, value| (un seul paramètre reçoit la paire [key, value]) ; select/reject renvoient un Hash, les autres ce que la méthode d’Array renvoie sur les paires |
le constructeur tag |
chaque élément (tag.div do ... end) |
sa sortie est le contenu de l’élément (Le constructeur tag) |
<%= @items.map { |i| i.name }.join(", ") %>
<%= @line_items.sum { |li| li.price } %>
<% @items.group_by { |i| i.kind }.each do |kind, list| %>
<h2><%= kind %></h2> <%= list.size %>
<% end %>
<% total = @line_items.sum do |li| %>
<% li.price * li.quantity %>
<% end %>
- La valeur, pas la sortie. Pour les méthodes d’Array et de Hash, c’est la valeur du bloc qui compte : l’expression d’un bloc
{ }, ou la dernière instruction d’un blocdo, qui doit être une instruction-expression (<% x * 2 %>) ; sinon"map's block must end in a value"(une affectation, ou du texte). Ce qu’affichent les instructions précédentes d’un blocdoest ignoré. Un blocdosur une telle méthode occupe sa propre balise, affecté (<% total = items.sum do |li| %>) ou affiché (<%= items.map do |x| %>). - Pas de mutation. Les templates n’ont aucun moyen de modifier un accumulateur, donc
each_with_objectetinjectne sont pas dans la table ("undefined method 'each_with_object' for Array") : utilisezmap,select,sumougroup_by. - Deux paramètres déstructurent un élément d’Array, comme le fait
each(pairs.map { |a, b| a }). - La
sumd’un Array vide vaut0; des Integers donnent un Integer, un Float n’importe où donne un Float (additionné avec la même compensation que Ruby, donc[0.1, 0.2, 0.3].sumvaut0.6) ; les Strings sont refusées ("sum: use join for Strings"), comme tout ce qui n’est pas un nombre. sort_by,min_by,max_by(etsort,min,maxsans bloc) comparent comme<(nombres, Strings, Times ;"comparison of String with Integer failed"sinon).sort_byest stable : les clés égales gardent leur ordre.min_by/max_byd’un Array vide valentnil.group_byrenvoie un Hash de chaque clé sous forme de String (tout Hash de template a des clés String ::fruitet"fruit"forment un seul groupe) vers les éléments qui ont cette clé, dans l’ordre de première apparition.each,each_with_indexeteach_sliceprennent leur bloc dans une balise<% %>(Boucles) ;items.each { |x| x }est uneSyntaxError.- Un bloc sur une méthode de
FormBuilderou dePageest refusé de la même façon ("FormBuilder#label takes no block"), et les méthodes d’Array sans bloc ne prennent pas d’argument (nums.sum(10)donne"wrong number of arguments for 'sum'"). - Si un bloc lève une exception, ses paramètres et ses variables locales sont restaurés avant que l’erreur ne quitte l’appel.
- Un bloc
{ }a besoin d’un receveur :shout { |x| x }est uneSyntaxError(les appels de helpers prennentdo ... end). - Les paramètres de bloc masquent les noms externes pendant l’appel et sont restaurés ensuite ; une variable locale affectée pour la première fois dans un bloc
doest locale au bloc, comme danseach.
Affectation
<% total = 0 %><% total = total + 2 %><%= total %> <%# => 2 %>
Uniquement name = expr pour une seule variable locale simple — pas de @ivar = ..., pas de arr[0] = .../h[:k] = ..., pas de a, b = .... La même règle de localité au bloc que pour each s’applique aux affectations dans des if/unless imbriqués dans un bloc.
Table des méthodes par type
nil?, present? et blank? sont vérifiés avant le dispatch par type, ils fonctionnent donc sur toutes les valeurs, y compris les modèles et les objets renvoyés par des helpers (blank? vaut false pour tout sauf nil/false/une SafeString/String/Array/Hash/Errors/Params vide). L’arithmétique (+ - * / %) et la comparaison (== != < > <= >=) n’existent que comme opérateurs infixes, jamais comme appels .method — un symbole d’opérateur ne peut jamais suivre un . dans cette grammaire.
| Type | Méthodes | Exemple |
|---|---|---|
SafeString |
to_s html_safe? size/length empty? |
raw('<b>').size |
String |
upcase downcase capitalize strip size/length empty? to_s to_i html_safe html_safe? include?(s) start_with?(s) end_with?(s) |
title.strip.upcase |
Integer |
to_s to_i to_f zero? positive? negative? abs |
post.comments.size.zero? |
Float |
to_s to_i to_f zero? positive? negative? abs round round(n) floor ceil |
price.round(2) |
Time |
year month day hour min sec strftime(fmt) to_s to_i |
post.created_at.strftime('%Y-%m-%d') |
Array |
size/length/count empty? any? first last reverse include?(x) join(sep) to_a sum min max sort uniq compact flatten take(n) drop(n) each_slice(n) (un Array d’Arrays) zip(other), et les méthodes à bloc de Blocs |
post.comments.any? |
Hash |
key?(k) fetch(k, default) size/length/count empty? any? keys values to_a (les paires [key, value]), plus h[key] et les méthodes à bloc de Blocs |
flash.key?(:notice) |
Errors |
any? empty? count/size full_messages key?(a)/include?(a), plus errors[:attr] |
post.errors.full_messages.join(', ') |
Params |
key?(k) empty?, plus params[key] |
params[:id] |
Page (Relation#page) |
number per row_offset next? prev? next_number prev_number |
@page.next? |
true/false |
to_s |
published.to_s |
nil |
to_s (renvoie "") |
L’indexation (x[key]) est une production distincte de la grammaire (Expressions), pas un appel .[] : Array/String prennent un index entier, Hash fait correspondre n’importe quelle clé par son to_s (h[:k] et h["k"] sont la même entrée), Errors par symbole, Params par to_s.
Affichage (<%= %>/interpolation) au-delà du to_s ci-dessus : un Array s’affiche comme une liste à la manière d’inspect — [1, "a", nil] rend le texte [1, "a", nil] (puis est échappé, les guillemets deviennent donc ") ; un Hash se rabat sur le Hash#to_s de Ruby ; un Cybertrain::Model s’affiche #<Post id: 7> (jamais ses attributs) ; tout le reste s’affiche via son propre to_s. Une méthode non listée sur l’un de ces types est une RuntimeError ("undefined method 'first' for Time"). La division/le modulo d’un Integer par zéro donne "divided by 0" ; Float suit plutôt l’IEEE-754 (Infinity/NaN, sans erreur).
Les modèles dans les templates
Une sous-classe de Cybertrain::Model (un Post, un Note générés, ...) résout un nom nu dans cet ordre (Interpreter#model_method) :
- Cinq méthodes intégrées, toujours disponibles :
id,persisted?,new_record?,to_param(id.to_s),errors(unErrors, Table des méthodes par type). read_attribute(:name)— une colonne générée.read_association(:name)— unhas_many/belongs_togénéré.call_view_method(:name)— undefsans argument écrit à la main que le générateur de modèles a trouvé dansapp/models/**/*.rb(jamais d’arité).
<%= post.title %> <%# read_attribute %>
<% post.comments.each do |c| %>...<% end %> <%# read_association %>
<%= post.summary %> <%# call_view_method %>
<%= post.errors.full_messages.join(", ") %>
Si les quatre répondent nil, attribute_or_method?(:name) décide s’il s’agissait d’un nom légitime qui contient simplement nil (renvoie le nil) ou d’une faute de frappe ("undefined method 'bogus' for Post").
Les modèles générés y répondent d’après leur schéma. spin run gen émet attribute_or_method? dans chaque modèle sous la forme d’un case sur ses colonnes (une colonne renommée sous ses deux noms), ses associations et ses méthodes de vue publiques : <%= post.titel %> sur un modèle généré donne donc "posts/show:3: undefined method 'titel' for Post", tandis qu’une colonne qui contient nil s’affiche vide. Le Cybertrain::Model#attribute_or_method? de base (dans model.rb) renvoie toujours true : une sous-classe de Cybertrain::Model écrite à la main qui ne le redéfinit pas affiche un nom inconnu comme vide. Note de mise à niveau : un template qui lisait un nom que son modèle n’a jamais eu s’affichait vide jusqu’ici et lève une erreur après le prochain spin run gen (docs/design.md D71).
Deux modèles se comparent avec == par classe et par id (Model#==), accessible via l’opérateur == ordinaire (dispatch natif de l’égalité, pas call_method).
Helpers et constructeur de formulaires
Chaque appel sans receveur va à Helpers#helper_call (helpers.rb), qui fait correspondre l’une des méthodes intégrées ci-dessous ; dans le template d’un composant, essaie ensuite les méthodes de vue de ce composant ; traite un nom finissant par _path/_url comme un helper de route généré (via Cybertrain::Views.url_resolver, qui lève "no routes" tant que l’application n’en a pas installé un) ; essaie ensuite les helpers de l’application ; ou lève "undefined helper 'name'".
| Helper | Signature | Remarques / exemple |
|---|---|---|
link_to |
link_to(text, href, class:, id:, data_confirm:, data: {}) |
text est échappé sauf s’il est déjà une SafeString ; pas de method: — lève une erreur qui vous dit d’utiliser button_to (pas de liens DELETE simulés à la rails-ujs/turbo) |
button_to |
button_to(text, action, method: :post, class:, data: {}) |
un <form class="button_to"> à un seul bouton ; un _method caché pour tout verbe autre que get/post, plus le champ CSRF quand une session existe |
form_with |
form_with(model:, url:, scope:, method:, class:, data:, multipart:, local:) do |f| ... end |
exige un bloc ; model: nouveau → route de collection + POST, persisté → route de membre + PATCH ; [parent, child] pour une route imbriquée, [:admin, @article] pour une route dans un namespace ; url:/method: remplacent l’action/le verbe déduits ; scope: :q nomme les champs q[term] (avec model:, il remplace le préfixe du modèle) ; data: { turbo_frame: "f" } écrit des attributs data- ; local: est accepté et ne change rien ; multipart: true ajoute enctype="multipart/form-data" (requis pour f.file_field ; ce n’est jamais deviné à partir du bloc, et cela lève ArgumentError sur un formulaire GET) |
select_tag |
select_tag(name, option_tags = nil, include_blank:, prompt:, multiple:) |
select_tag "order", options_for_select([["Newest", "new"], ["Oldest", "old"]], "old") → <select name="order" id="order">...</select> ; un option_tags qui n’est pas une SafeString est échappé ; multiple: true le nomme order[] ; les autres mots-clés sont des attributs |
options_for_select |
options_for_select(choices, selected = nil) |
les lignes <option> des choix de f.select (ci-dessous) ; selected est une valeur ou un Array de valeurs, comparées comme des String |
options_from_collection_for_select |
options_from_collection_for_select(records, :id, :name, selected = nil) |
une <option> par enregistrement, sa valeur et son texte lus comme les lit f.collection_select |
t, translate |
t(key, default:, count:, locale:, name: value) |
le texte de key dans la locale de la requête, échappé ; t(".title") dans posts/index.html.erb lit posts.index.title, dans le partial posts/_form.html.erb posts.form.title ; une clé en _html écrit son HTML et échappe les valeurs (Internationalisation) |
l, localize |
l(time_or_date, format: :short, locale:) |
les time.formats / date.formats de la locale, ou un motif strftime avec les noms des jours et des mois de la locale (Dates et heures) |
label_tag, text_field_tag, hidden_field_tag, submit_tag |
label_tag(name, text = nil), text_field_tag(name, value = nil), hidden_field_tag(name, value = nil), submit_tag(value = "Save changes") |
les balises de formulaire sans modèle : label_tag(:term) → <label for="term">Term</label> ; hidden_field_tag écrit autocomplete="off" ; submit_tag s’appelle commit ; les autres mots-clés sont des attributs (id: remplace l’id tiré du nom) |
check_box_tag |
check_box_tag(name, value = "1", checked = false) |
une case à cocher sans modèle ni champ caché, si bien qu’une case non cochée n’envoie rien : check_box_tag :remember_me → <input type="checkbox" name="remember_me" id="remember_me" value="1"> ; les autres mots-clés sont des attributs |
render |
render "name" / render "name", k: v / render partial: "name", locals: { k: v } / render partial: "comment", collection: @comments / render @comments / render component: "card", k: v |
voir Layouts, yield, content_for, partiels, Collections et Composants |
h, escape |
h(text) |
échappe ; une SafeString passe sans être échappée |
raw |
raw(text) |
enveloppe le texte dans une SafeString (affiché sans échappement) |
pluralize |
pluralize(count, singular, plural = nil) |
pluralize(1, "comment") → "1 comment" ; pluralize(2, "mouse") → "2 mice" (les inflexions anglaises par défaut de Rails, via Cybertrain::Inflector, dans une page en anglais seulement : dans une autre locale le mot reste tel quel ; les inflexions définies par l’application ne sont pas prises en charge) ; un troisième argument explicite l’emporte toujours |
truncate |
truncate(text, length: 30, omission: "...") |
truncate("Hello world", length: 8) → "Hello..." |
number_with_delimiter |
number_with_delimiter(n, delimiter: ",", separator: ".") |
1234567 → "1,234,567" ; -1000 → "-1,000" ; 1234.5 → "1,234.5" |
number_with_precision |
number_with_precision(n, precision: 3, delimiter: "", separator: ".", strip_insignificant_zeros: false) |
111.2345 → "111.235" ; precision: 0 → "111" |
number_to_human |
number_to_human(n, precision: 3, units: {}) |
1234 → "1.23 Thousand", 1234567 → "1.23 Million" ; units: { thousand: "K" } remplace le nom d’une unité (unit, thousand … quadrillion) |
number_to_percentage |
number_to_percentage(n, precision: 3) |
100 → "100.000%" |
number_to_currency |
number_to_currency(n, unit: "$", precision: 2, format: "%u%n") |
1234.5 → "$1,234.50" ; un nombre négatif écrit - avant le format |
number_to_human_size |
number_to_human_size(n) |
1234 → "1.21 KB" (base 1024) ; 1 → "1 Byte" |
time_ago_in_words |
time_ago_in_words(time) |
Tranches à la Rails, sans précision à la seconde : "less than a minute" … "about 1 hour" … "3 days" … "about 1 year", tirées du datetime.distance_in_words de la locale (en japonais "2分") |
content_for / content_for? |
content_for(:key) do...end, content_for(:key, "text"), content_for?(:key) |
voir Layouts, yield, content_for, partiels |
csrf_meta_tags / csrf_token |
vide / absent sans session de contrôleur | |
csp_meta_tag / content_security_policy_nonce |
<meta name="csp-nonce" content="..."> / le nonce seul, le nonce de la Content Security Policy de cette requête ; "" quand aucune politique ne s’applique |
|
javascript_tag |
javascript_tag(nonce: true) do ... end, javascript_tag(js) |
le contenu dans un <script> (non échappé, comme dans Rails : n’y mettez jamais de données de la requête), avec le nonce quand nonce: true et qu’une politique s’applique ; id:, type:, data: sont des attributs |
asset_path |
asset_path("logo.svg") |
/assets/logo-1a2b3c4d.svg (voir Assets) ; une URL ou un chemin commençant par / est renvoyé tel quel |
stylesheet_link_tag |
stylesheet_link_tag("application", media:, nonce:) |
<link rel="stylesheet" href="/assets/application-1a2b3c4d.css"> (.css ajouté s’il manque) |
javascript_include_tag |
javascript_include_tag("legacy", nonce:) |
<script src="/assets/legacy-1a2b3c4d.js"></script> (.js ajouté s’il manque) |
image_tag |
image_tag(source, alt:, size:, class:) |
<img src="/assets/logo-1a2b3c4d.svg" alt="Logo" width="16" height="16"> pour size: "16x16" (ou "16") ; aucun alt n’est inventé, alt: "" est écrit |
javascript_importmap_tags |
javascript_importmap_tags(entry = "application") |
l’import map, un lien modulepreload par pin préchargé et import "application", chacun avec le nonce quand une politique s’applique (Assets) ; a besoin d’une requête |
flash |
à la manière d’un Hash : flash[:notice] |
|
params |
les Cybertrain::Params courants |
|
request_path |
le chemin courant, "" sans contrôleur |
|
url_for |
url_for(target, format:, anchor:, k: v) |
String tel quel, Model → route de membre, [parent, child] → route imbriquée, [:admin, record] → route dans un namespace ; les mots-clés sont ajoutés comme un helper de chemin les ajoute (url_for("/x", format: :csv) → /x.csv) |
current_page? |
current_page?(path) |
si cette requête GET ou HEAD vise path (à une barre oblique finale près ; avec une query dans path, la query doit aussi correspondre) ; un enregistrement ou un Array passe par url_for ; faux pour toute autre méthode ; a besoin d’une requête |
paginate |
paginate(page, path) |
page est un Cybertrain::Page (issu de Relation#page) ; rend <nav class="pager"> avec « Newer » (rel="prev"), <span class="pager-current">Page N</span> et « Older » (rel="next"), un lien étant omis quand la page correspondante n’existe pas. Chaque lien est path plus la chaîne de requête de la requête courante avec page remplacé (supprimé pour la page 1), réencodée et échappée pour le HTML ; un path avec sa propre ?query utilise plutôt celle-ci. Un Page répond aussi à number, per, row_offset, next?, prev?, next_number, prev_number dans un template (<% if @page.next? %>) |
*_path / *_url |
par ex. post_path(post), posts_path(page: 2, format: :json) |
générés par l’application, résolus via Cybertrain::Views.url_resolver ; les mots-clés vont dans la chaîne de requête, format: ajoute l’extension et anchor: le fragment (Redirections et chaînes de requête) |
tag |
tag.div(content, attrs) do ... end |
le constructeur tag : voir Le constructeur tag |
content_tag |
content_tag(name, content = nil, attrs), ou avec un bloc do |
content_tag "p", "<i>", class: "n" → <p class="n"><i></p> ; les mêmes règles que tag |
safe_join |
safe_join(array, sep = "") (sans arguments nommés) |
joint en une SafeString, en échappant chaque élément et le séparateur qui ne sont pas déjà des SafeString : safe_join([tag.b("a"), "<"], " ") → <b>a</b> < |
class_names |
class_names(*values) |
class_names/token_list de Rails : les mots des Strings et des Symbols, des Arrays (imbriqués aussi) et de chaque clé de Hash dont la valeur est vraie, chaque mot une fois ; les arguments nommés forment un Hash de plus : class_names("btn", active: @on, big: false) → "btn active" |
dom_id |
dom_id(record, prefix = "") (le préfixe est positionnel, comme dans Rails) |
"article_12", "new_article" pour un enregistrement non sauvegardé, dom_id(@article, "edit") → "edit_article_12" (Cybertrain::Html.dom_id en Ruby) |
turbo_stream_from |
turbo_stream_from(*streams, ws: false) |
un <turbo-stream-source> qui abonne la page aux flux (des Strings, ou des enregistrements nommés "articles:12") ; ws: true donne une URL ws:///wss:// et exige une requête. Voir Temps réel |
signed_stream_name |
signed_stream_name(*streams) |
le jeton signé seul, pour du JavaScript écrit à la main |
stream_source_path |
stream_source_path(*streams, mode: "json") |
le chemin du point d’entrée des flux avec le jeton et mode=json (ou "raw") |
turbo_frame_tag |
turbo_frame_tag(id_or_record, src:, loading:, target:, class:, data:) do ... end |
<turbo-frame id="article_3" src="...">...</turbo-frame> ; un enregistrement donne son dom_id ; chaque attribut seulement s’il est fourni |
turbo_stream |
turbo_stream.replace(target, partial:, locals:), .update(target, html:), .append(target) do ... end, .prepend, .before, .after, .remove(target) |
un élément <turbo-stream action="...">, pour un template *.turbo_stream.erb ; la cible est un id DOM ou un enregistrement ; exactement un parmi un bloc, partial: (avec locals:) et html: |
time_tag |
time_tag(time, text = nil, format:, class:, id:, title:, data:), ou avec un bloc |
<time datetime="2026-11-10T12:00:00Z">Tue, 10 Nov 2026 12:00:00 +0000</time> ; une Date donne 2026-11-10 ; sans format:, le texte est le format :default de la locale ; format: est un nom de format (:short, :long ou tout autre que contiennent les dictionnaires), formaté par l dans la locale de la requête, ou une String strftime (avec les noms anglais des jours et des mois ; une directive inconnue lève une erreur, de même qu’une largeur ou un drapeau que strftime lirait autrement : %6L, utilisez %6N ; : seulement dans %:z ; pas de drapeau de remplissage sur %F %T %D %R %r %c %x %X %v ; une largeur sur un nombre remplace son remplissage, %5e donne " 5") |
Chaque argument texte d’un helper suit une seule règle : une SafeString passe sans être échappée, tout le reste est échappé — link_to raw('<b>raw</b>'), post affiche la balise gras littéralement, mais link_to post.title, post l’échappe.
Les six helpers numériques sont ceux de Cybertrain::NumberHelper, que le code Ruby appelle comme des fonctions de module avec les mêmes mots-clés (Cybertrain::NumberHelper.number_to_currency(price, unit: "€")). Ils prennent un Integer, un Float ou une String numérique (les colonnes décimales sont des Float) et arrondissent au demi supérieur sur les chiffres de son texte décimal, si bien que le résultat est le même sur les deux runtimes ; toute autre valeur lève ArgumentError ("number_with_delimiter: \"abc\" is not a number"), tout comme une précision hors de 0 à 100. Dans un template, nil donne "" (une colonne décimale nullable s’affiche vide, comme dans Rails) ; Cybertrain::NumberHelper appelé depuis Ruby lève toujours ArgumentError pour nil ("number_with_delimiter: nil is not a number"). Dans un template, les valeurs par défaut viennent de la locale de la requête (number.* dans les dictionnaires : le number_to_currency(1234) japonais donne "1,234円"), et un mot-clé donné l’emporte ; depuis Ruby ce sont les valeurs anglaises montrées plus haut.
Le constructeur tag
tag s’évalue en un constructeur (Cybertrain::Html::TagBuilder) ; toute méthode appelée dessus est un élément, rendu par Cybertrain::Html.tag (appelable aussi depuis Ruby : Html.tag("a", { href: "/x" }, "Go")) :
<%= tag.div(class: "card") do %>
<%= tag.h2 @article.title, id: dom_id(@article) %>
<% end %>
<%= tag.input type: "text", name: "q", disabled: true %> <%# <input type="text" name="q" disabled> %>
<%= tag.path d: "M0 0 L10 10" %> <%# SVG elements work %>
<%= tag.my_widget data: { turbo_frame: "f" } %> <%# <my-widget data-turbo-frame="f"></my-widget> %>
<%= tag %>seul n’affiche rien.- Le nom de l’élément est le nom de la méthode avec
_changé en-; il doit correspondre à[a-z][a-z0-9-]*(sinon"invalid element name 'Div'", levé parHtml.tag). - Le contenu est l’unique argument positionnel (échappé sauf s’il s’agit d’une
SafeString, donctag.script("alert(1)")affiche son texte échappé) ou la sortie du bloc (do ... end, ou{ expr }dont la valeur est affichée échappée) ; le bloc l’emporte. Sans l’un ni l’autre,tag.divdonne<div></div>. - Les éléments vides (
area base br col embed hr img input link meta source track wbr) se rendent sans balise fermante ; leur donner un contenu ou un bloc est une erreur ("br is a void element"). - Les attributs sont les arguments nommés, dans l’ordre :
niletfalsesuppriment l’attribut,truele rend nu (disabled), un Array joint ses éléments nonnilpar des espaces (data: { ids: [1, 2] }donnedata-ids="1 2", pas le JSON de Rails),class:prend ce que prendclass_names(class: ["btn", { active: @on }]), les Hashsdata:etaria:s’imbriquent endata-key="v"/aria-key="v"avec les tirets bas changés en tirets (ettrue/falseécrits en toutes lettres) ; toute autre valeur Hash est une erreur ("attribute 'title' cannot be a Hash"). Chaque valeur est échappée, uneSafeStringaussi. Les noms d’attributs doivent correspondre à[a-zA-Z_:][-a-zA-Z0-9_:.]*("invalid attribute name 'data-a b'") ;onclick:et consorts sont permis, puisqu’ils viennent de l’auteur.
FormBuilder (f dans form_with ... do |f|)
Chaque méthode renvoie une SafeString ; une méthode non listée est une RuntimeError ("undefined method 'color_wheel' for FormBuilder").
| Méthode | Rendu |
|---|---|
f.label :title / f.label :title, "Text" |
<label for="post_title">Title</label> — le texte par défaut est l’attribut humanisé (published_at → « Published at », author_id → « Author ») ; un texte explicite est échappé sauf s’il est une SafeString |
f.text_field :title (aussi email_field, password_field, number_field, date_field, datetime_local_field, time_field, range_field, color_field, search_field, telephone_field, url_field, hidden_field) |
<input type="..." name="post[title]" id="post_title" value="..."> ; password_field n’émet jamais value= ; telephone_field est type="tel" ; un Time est écrit comme le lit le navigateur (2026-11-10, 2026-11-10T12:00:00, 12:00:00.000) |
f.select :status, ["draft", "published"] (aussi include_blank:, prompt:, selected:, disabled:, multiple:) |
<select name="post[status]" id="post_status"> avec une <option> par choix, la valeur actuelle sélectionnée ; les choix sont des valeurs, des paires [text, value], ou un Hash ou des groupes [label, [choices]] pour <optgroup> ; multiple: true le nomme post[status][] et écrit d’abord un input caché vide |
f.collection_select :author_id, @authors, :id, :name |
un <select> avec une <option> par enregistrement, sa valeur et son texte lus depuis les deux méthodes |
f.radio_button :status, "draft" |
<input type="radio" name="post[status]" id="post_status_draft" value="draft">, coché quand la valeur correspond (checked: prend le dessus) |
f.file_field :cover (aussi accept: "image/*", required: true) |
<input type="file" name="post[cover]" id="post_cover"> — jamais de value=, et l’attribut n’a pas besoin d’être une colonne ; le formulaire doit être form_with ..., multipart: true ; multiple: true lève ArgumentError (un fichier par champ) |
f.text_area :body |
<textarea name="post[body]" id="post_body">\n...</textarea> (\n initial, comme le fait Rails — les navigateurs absorbent le premier saut de ligne) |
f.check_box :published |
un input caché value="0" puis la vraie case à cocher, de sorte qu’une case non cochée envoie quand même "0" ; include_hidden: false omet l’input caché |
f.submit / f.submit "Text" |
texte par défaut "Create Post"/"Update Post" (selon persisted?), ou "Save changes" sans modèle |
Avec un modèle, les champs sont nommés post[title]/id="post_title" (avec Inflector.underscore(model.model_name) comme portée) ; form_with(..., scope: :q) utilise plutôt q[title]/id="q_title" ; avec form_with(url: ...) et sans modèle ni portée, le nom d’attribut nu est utilisé pour les deux. Chaque valeur d’attribut et chaque texte d’option est échappé une fois (une SafeString telle quelle). Les arguments nommés supplémentaires deviennent des attributs HTML dans l’ordre donné : true → attr="attr", false/nil omis, tout le reste → attr="value" (échappé), les tirets bas deviennent des traits d’union (data_confirm: "Sure?" → data-confirm="Sure?"), et class: est fusionné avec la classe automatique field_with_errors ajoutée quand model.errors.key?(attr).
Helpers de l’application
Un module sous app/helpers/ est un module de helpers, comme dans Rails : chacune de ses méthodes publiques peut être appelée depuis n’importe quel template, sans receveur.
module PricesHelper
def price(value, unit: "USD", precision: 2)
amount = Cybertrain::Cast.float(value).round(Cybertrain::Cast.int(precision))
Cybertrain::Html.tag("span", { class: "price" }, "#{amount} #{unit}")
end
def panel(title, &block)
Cybertrain::Html.tag("section", { class: "panel" }, Cybertrain::Html.safe_join([Cybertrain::Html.tag("h2", {}, title), yield]))
end
end
<%= price @item.cost %> <%# <span class="price">12.5 USD</span> %>
<%= price @item.cost, unit: "EUR" %>
<%= panel "Totals" do %><p><%= @total %></p><% end %>
- Dispatch généré. Les templates ne peuvent pas faire de
send, doncspin run genlitapp/helpers/**/*.rbcomme du texte et écritgen/helpers.rb: une classeApplicationHelpersqui inclut chaque module (et les helpers de route) et uncasesur les noms des helpers. Ajoutez un helper ou changez sa signature, et la compilation suivante le régénère (le serveur de développement fait les deux).cybertrain generate helper pricesécrit unPricesHelpervide et un test. - Ce qui est un helper. Les méthodes d’instance publiques d’un
module(pasdef self.x, ni les setters, ni tout ce qui suitprivateouprotected), quel que soit leur fichier. Un template passe des valeurs par position ou par mot-clé, donc chaque paramètre est nommé :*rest,**opts,...sont des erreurs du générateur, comme un paramètre obligatoire après un paramètre optionnel. Un helper prend au plus trois paramètres optionnels (lecasegénéré a une branche par combinaison donnée, si bien qu’un mot-clé omis prend la valeur par défaut de la méthode elle-même). Un mauvais appel est uneArgumentErrorau rendu :"wrong number of arguments for 'price' (given 0, expected 1)","unknown keyword 'cur' for 'price' (known: unit, precision)". - Noms réservés. Un helper ne peut pas porter le nom d’un helper du framework (
link_to,render,tag,dom_id,params,content, ...), d’une méthode deCybertrain::Template::Helpers(publique ou privée : l’includela remplacerait aussi pour le framework),yield, ni finir par_path/_url(ce sont les helpers de route qui y répondent) ; le même nom dans deux modules est aussi une erreur.spin run gens’arrête en indiquant le fichier, la ligne et la raison. - Valeurs. Les arguments arrivent comme des valeurs du template (String, Integer, Float,
nil, un enregistrement, un Array, un Hash) ; restreignez-les avecCybertrain::Cast(Cast.str,Cast.int,Cast.float) avant tout calcul. Ce que renvoie un helper est affiché comme toute valeur : uneStringest échappée, uneSafeStringnon, donc construisez le HTML avecCybertrain::Html.tag(name, attrs, content),Html.safe_join,Html.class_names,Html.dom_id,Html.escape,Cybertrain::SafeString.ofou les formes Ruby des helpers de lien,link_to_path(text, path, attrs)etbutton_to_path(text, path, attrs)(method:dansattrs). - Blocs. Un helper avec un paramètre
&blockprend un blocdo ... end;yield(sans argument) renvoie ce que le bloc a affiché, sous forme deSafeString.
Composants
Un composant est une classe à arguments nommés avec un template à côté, sur le modèle de ViewComponent :
class CardComponent < Cybertrain::Component
def initialize(title:, value: 0, tone: "neutral")
@title = title
@value = value
@tone = tone
end
def value_text = "#{@value} pts"
def tone_class = "card--#{@tone}"
end
<%= tag.div(class: class_names("card", tone_class)) do %>
<h3><%= title %></h3><p><%= value_text %></p><%= content %>
<% end %>
<%= render component: "card", title: "Visitors", value: @count %>
<%= render component: "card", title: "Notes", tone: "warm" do %>
<p><%= @note %></p>
<% end %>
- Le template voit les variables d’instance du composant comme des variables locales (
title), ses méthodes publiques sans paramètre par leur nom (value_text), etcontent, ce qu’a affiché le blocdo(""sans bloc). Il se rend sans layout, peut rendre des partiels et d’autres composants, et compte pourmax_render_depthcomme un partiel. Un partiel qu’il rend ne voit pas les méthodes du composant. Un nom de partiel sans répertoire dans le template d’un composant (render "chip") est cherché sousapp/components/(app/components/_chip.html.erb) ; un nom avec répertoire (render "shared/note") sousapp/views/, comme d’habitude. - Un composant est désigné par son nom en snake_case sans
_component, comme un partiel l’est par son chemin :"card"pourCardComponent,"admin/user_row"pourAdmin::UserRowComponent(app/components/admin/user_row_component.rb). Les templates ne peuvent pas nommer de constantes. spin run genécritgen/components.rbà partir d’une analyse lexicale, comme pour les helpers : la ligne de classe, les affectations@x =, lesdefsans paramètre et les mots-clés d’initialize.initializene prend que des mots-clés (au plus trois optionnels), et son template doit exister ; un mot-clé manquant ou inconnu est uneArgumentErrorau rendu. Un composant inconnu est unCybertrain::Component::Unknown:"no component 'crad' (app/components/crad_component.rb, then `spin run gen`)".contentest réservé : un mot-clé d’initializeou une variable d’instance@contentde ce nom serait écrasé par la sortie du bloc, doncspin run genle refuse en nommant le fichier et la ligne.app/views/components/reste un répertoire de vues comme un autre (celui d’unComponentsController) ; seulapp/views/__components/est réservé, les noms sous lesquels sont rangés les templates des composants.cybertrain generate component card title value:integerécrit la classe, son template et un test qui le rend avecCybertrain::Test.render_component.
Rendre hors d’une requête
Une diffusion, un job ou un corps de mail se rendent sans requête :
html = Cybertrain::Views.render_partial("articles/article", article: article) # app/views/articles/_article.html.erb
card = Cybertrain::Views.render_component(CardComponent.new(title: "Visitors", value: 12))
Les deux renvoient le HTML sous forme de String, avec les helpers de l’application. Les helpers de chemin fonctionnent (article_path(article)), les strict locals sont vérifiés, et les formulaires (form_with, button_to) se rendent sans le jeton d’authenticité (une page Turbo soumet celui de csrf_meta_tags). Un helper qui a besoin d’une requête lève Cybertrain::Views::OutsideRequest ("csrf_token needs a request") : csrf_token, csrf_meta_tags, params, flash, request_path, current_page?, content_security_policy_nonce (donc csp_meta_tag et un helper de balise auquel on passe nonce: true), javascript_importmap_tags, tout helper *_url et turbo_stream_from ... ws: true. Les liens de paginate ne portent que la query string propre au chemin. (Un Cybertrain::Template::Helpers.new(nil) nu, tel qu’un test unitaire peut en construire, y répond plutôt par des valeurs vides.)
Layouts, yield, content_for, partiels
Engine#render_with_layout(name, layout, env, helpers) rend name dans env["__content"] (une SafeString), puis rend layout avec le même env :
<title><%= yield :title %></title>
<%= yield %>
yield affiche env["__content"] ; yield :key affiche env["__content_key"], ou rien s’il n’est pas défini. yield est traité à part directement dans l’interpréteur et ne peut pas être redéfini comme helper. Une page remplit un emplacement avec content_for, n’importe où dans son corps (l’ordre par rapport à yield n’a pas d’importance — la page est entièrement rendue avant le layout) :
<% content_for :title do %>Post: <%= @post.title %><% end %>
<% content_for :title, " (draft)" %> <%# appends: calls accumulate, they don't replace %>
Layouts par contrôleur
Une action se rend dans app/views/layouts/application.html.erb (quand il existe) sauf si son contrôleur, un parent ou un concern qu’il inclut en choisit un autre :
class AdminController < ApplicationController
layout "print", only: [:receipt] # app/views/layouts/print.html.erb
layout :choose_layout # une méthode : un nom, false pour aucun, nil pour celui du parent
private
def choose_layout = request.header("Turbo-Frame").to_s.empty? ? "application" : "frame"
end
layout "admin" seul nomme un layout pour toutes les actions. spin run gen lit les lignes layout (un nom entre guillemets, false, ou le Symbol d’une méthode, avec only: / except:) et écrit le controller_layout(action) du contrôleur. Les déclarations sont essayées dans l’ordre et la première qui s’applique l’emporte (Rails laisse une déclaration ultérieure remplacer une antérieure) ; les lignes d’un concern comptent à son include. render layout: "x" utilise layouts/x pour un appel et render layout: false aucun ; un layouts/ initial est accepté (layout "layouts/x" vaut layouts/x). Une ligne layout ou un render layout: qui nomme un layout inexistant lève MissingTemplate ; seul le layout application par défaut est facultatif (l’action se rend alors sans layout). Seul le html est rendu dans un layout ; le template d’un autre format se rend sans. Tout autre argument de layout (nil, une lambda, une constante) est refusé par gen.
Partiels et render
<%= render "form", post: @post %>
<%= render partial: "form", locals: { post: @post } %>
<%= render "comments/comment", comment: c %>
- Un nom nu sans
/se résout dans le propre répertoire du template courant (via une clé d’env que définit la mécanique de rendu,__template_dir) :render "form"depuisposts/showchercheposts/_form.html.erb. Un nom contenant/est un chemin explicite ; seul son dernier segment reçoit le préfixe_("comments/comment"→comments/_comment.html.erb). - Le partiel reçoit une copie de tout l’environnement de l’appelant (ivars et toutes les variables locales déjà visibles) plus les variables locales explicitement passées à
render— il n’est pas cloisonné à ce qui lui a été passé. Les locals stricts ne valident que les noms explicitement passés à cet appel derenderpar rapport à la liste déclarée ; ils n’empêchent pas le partiel de lire aussi un autre nom qu’il hérite de l’environnement de l’appelant. - Seules les clés de
content_for(__content_*) sont recopiées de la portée d’un partiel vers celle de l’appelant ; les variables locales ordinaires qu’il affecte ne remontent pas. - Des variables locales manquantes/en trop par rapport à une déclaration
<%# locals: %>sont desRuntimeError:"missing local 'post' for posts/_form.html.erb","unknown local 'extra' for posts/_form.html.erb".
Collections
<%= render partial: "comment", collection: @comments, as: :comment, spacer_template: "divider" %>
<%= render @comments %> <%# each record's comments/_comment.html.erb %>
<%= render @comment %> <%# one record, no counter %>
<%= render component: "comment", collection: @comments %>
collection:rend le partiel une fois par élément d’un Array, sous la variable locale nommée paras:(par défaut le nom du partiel), avec<as>_counterqui compte à partir de 0, leslocals:donnés à chacun etspacer_template:(un partiel) entre les éléments ; une collection vide ne rend rien. Un partiel à locals stricts ne reçoit le compteur que s’il le déclare, et l’élément l’emporte sur une variable locale du même nom.render @commentschoisit le partiel de chaque enregistrement d’après son modèle,<plural>/_<singular>(admin/notes/_notepour unAdmin::Note), si bien qu’une liste peut mêler des modèles.- Un composant dont l’unique mot-clé requis porte son nom (
CommentComponentaveccomment:) reçoitCommentComponent.with_collection(items), etrender component: "comment", collection: @commentsle rend une fois par élément, en passantcomment_counter:quandinitializele déclare.collection:n’accepte aucun autre mot-clé (render component: "comment", collection: @comments, extra: 1est une erreur qui le nomme) ; le contenu du bloc n’est pas transmis.
Résolution des fichiers (engine.rb)
"posts/show" et "posts/show.html.erb" désignent le même template. Le développement lit app/views/ depuis le disque avec cache: false (un fichier est relu et réanalysé chaque fois que son mtime ou sa taille change, et cette réanalyse écrit dans le cache du moteur, si bien que le serveur de développement tourne toujours avec un seul worker et ignore SPINEL_WORKERS, ce que dit sa bannière de démarrage) ; l’environnement de test lit depuis le disque avec cache: true (analysé une fois). Un binaire de production ne touche jamais au disque : cybertrain build lance spin run gen -- --embed-views, qui écrit chaque *.erb de app/views/ (fichiers cachés et répertoires liés symboliquement exclus) dans gen/views.rb, et Engine.embedded(sources) analyse chaque entrée une fois, au démarrage du binaire (les messages d’erreur gardent la même forme posts/show.html.erb:12), si bien qu’un template avec une erreur de syntaxe arrête le démarrage au lieu de faire échouer sa page ; un binaire dont la table est vide refuse de démarrer en production. Un template absent lève Cybertrain::Template::MissingTemplate — "Missing template <full path>" depuis le disque, "Missing template posts/nope.html.erb (embedded)" depuis la table.
Les recherches de fichiers résolvent la racine des vues et le chemin du template à travers les liens symboliques, et ne chargent que des fichiers ordinaires situés dans cette racine. Les chemins qui en sortent (y compris via des liens symboliques) lèvent MissingTemplate ; exists? renvoie false pour ces chemins.
Erreurs
Deux classes d’exception, toutes deux dans l’espace de noms Cybertrain::Template de ast.rb (distinctes de ::SyntaxError/::RuntimeError) :
SyntaxError— levée pendant le découpage en lexèmes/l’analyse, avant toute interprétation. Forme :"<template>:<line>: <what>", par ex."posts/show:2: 'if' without 'end'","posts/show:1: unterminated <% tag","posts/show:1: unexpected ')' in 'foo(1))'". Levée directement parEngine#template(et donc par#render/#render_with_layout) quand un fichier de page ou de layout ne s’analyse pas — jamais attrapée ni réemballée par l’interpréteur.RuntimeError— levée pendant l’évaluation, même forme de message, mais<template>est le template en cours de rendu (Interpreter#renderpermute@nameà l’entrée et à la sortie) — l’erreur propre à un partiel garde le nom et la ligne du partiel, jamais ceux de l’appelant :"posts/_row:1: undefined method 'bogus' for String".
Toute StandardError ordinaire venant d’un helper ou d’un appel de méthode de FormBuilder/d’objet personnalisé (un simple raise "text", ArgumentError, KeyError, voire une Cybertrain::Template::RuntimeError venant d’un render imbriqué) est attrapée et « relocalisée » : réécrite en "<current template>:<current line>: <original message>", sauf si c’est déjà exactement le dernier message relocalisé (un render imbriqué a déjà apposé sa propre localisation, plus précise), auquel cas elle passe inchangée. Une Cybertrain::Template::SyntaxError levée par un helper (un partiel qui ne s’analyse pas, en plein rendu) n’est jamais réemballée — elle garde son propre message "<partial>:<line>: ..." et sa classe, de sorte qu’un partiel cassé est toujours signalé comme une SyntaxError le concernant, et non comme une RuntimeError concernant celui qui l’a rendu.
Cybertrain::Views::OutsideRequest et Cybertrain::Component::Unknown passent aussi sans être enveloppées, en gardant leur classe, pour que l’appelant de Views.render_partial puisse les rattraper.
MissingTemplate (StandardError, engine.rb) est levée sans emballage, sans préfixe template:line, depuis un appel de premier niveau à Engine#template/#render/#render_with_layout (par ex. un contrôleur qui rend un template d’action ou un layout absent) : "Missing template <path>". La même exception levée à l’intérieur d’un template via la recherche de partiel du helper render passe au contraire par la relocalisation et en ressort comme une RuntimeError : "posts/inline:1: Missing template test/fixtures/views/posts/_nope.html.erb".
Différences avec l’ERB de Rails
| ERB de Rails | Cybertrain |
|---|---|
| Compilé en méthode Ruby ; n’importe quel Ruby, n’importe quel objet, n’importe quelle méthode fonctionne | Interprété selon des tables de dispatch fixes par type ; seul ce que liste la table des méthodes par type peut être appelé |
ActiveSupport::SafeBuffer est une sous-classe de String |
SafeString est une classe d’enveloppe distincte — seuls to_s/html_safe?/size/length/empty? peuvent être appelés dessus |
Blocs : each, { }, map, n’importe quelle méthode d’Enumerable |
{ } et do...end sur une liste fixe de méthodes d’Array/Hash (pas each_with_object, inject), les boucles each/each_with_index/each_slice, les appels de helpers et tag |
xs.each { } — zéro paramètre de bloc, c’est permis |
each/each_with_index exigent de déclarer 1 ou 2 paramètres de bloc |
link_to text, path, method: :delete (piloté par JS) |
Pas de method: sur link_to — utilisez button_to pour un vrai formulaire autre que GET |
Les locals stricts acceptent name: default_expr (Rails 7.1) |
Uniquement un name: nu (obligatoire) ; une entrée avec valeur par défaut est une SyntaxError |
| Une ivar/variable locale non définie se résout via Ruby / les méthodes du contexte de vue | @x est une simple lecture de l’env qui n’échoue jamais ; une variable locale nue non définie est une tentative explicite et fermée d’appel de helper ("undefined helper" en l’absence de correspondance) |
case/when avec === (intervalles, classes, regex) |
case/when avec == seulement (les nombres par valeur) |
and/or/not, intervalles, regex, affectation multiple fonctionnent tous |
Rien de tout cela n’existe ; les mots réservés échouent avec un message spécifique « not supported in templates », pas une erreur d’analyse générique |
| Littéraux numériques : hexadécimal, octal, binaire, exposants, rationnels | Uniquement des entiers/flottants décimaux avec des séparateurs _ facultatifs |
:"quoted symbol", symboles d’opérateur :+ |
Les symboles ne contiennent que des caractères d’identifiant |
foo (x), foo [x] (espace toléré, parfois avec un avertissement) |
Les deux sont des SyntaxError franches — pas d’espace avant la ( d’un appel ni le [ d’une indexation |
| Appels imbriqués sans parenthèses résolus par le propre parseur de Ruby | Seul l’appel le plus externe d’une expression reçoit des arguments sans parenthèses |
Un attribut non déclaré/mal orthographié lève de façon fiable NoMethodError |
Un modèle généré lève "undefined method 'x' for Post" (une Template::RuntimeError) et affiche vide un attribut existant qui vaut nil ; un modèle écrit à la main qui ne redéfinit pas attribute_or_method? affiche un nom inconnu comme vide |
1 / 0 et 1.0 / 0 lèvent tous deux ZeroDivisionError |
La division/le modulo d’un Integer par zéro lève "divided by 0" ; Float suit l’IEEE-754 (Infinity/NaN), sans erreur |
distance_of_time_in_words/la pluralisation prennent en charge les locales i18n |
time_ago_in_words, distance_of_time_in_words, les helpers de nombres et time_tag lisent le dictionnaire de la locale ; pluralize n’infléchit que l’anglais (Internationalisation) |
Chaque module de app/helpers est mélangé dans la vue ; n’importe quelle signature ; un helper peut en remplacer un du framework |
Les modules sont analysés à la compilation en un case généré : paramètres nommés seulement, au plus trois optionnels, aucun nom de helper du framework et pas de terminaison _path/_url (Helpers de l’application) |
ViewComponent : render CardComponent.new(title: "x"), with_collection, slots |
render component: "card", title: "x" par nom, content venant du bloc, collection: pour un composant qui porte le nom de son unique mot-clé requis ; pas de slots (Composants, Collections) |
Une ligne layout ultérieure remplace une antérieure |
La première déclaration layout qui s’applique l’emporte (Layouts par contrôleur) |