Этот документ описывает ровно то, что этот конвейер принимает и выполняет. Там, где он расходится с разделом 7 docs/design.md (исходным черновиком спецификации) или с ожиданиями разработчика на Rails, прав код, и этот документ об этом говорит (ищите «As built»).
Что здесь является Ruby, а что нет
Шаблоны не являются Ruby. В Spinel (AOT-компиляторе Ruby от Matz, на который нацелен cybertrain) нет eval, поэтому вариант «интерпретировать собственный Ruby представления во время запроса» даже не рассматривался (D9 в docs/design.md); вместо этого выполняется небольшая замкнутая грамматика, которая лишь внешне похожа на синтаксис ERB/Ruby. Внутри тега нет произвольного Ruby — только то, что ExprParser (parser.rb) распознаёт как инструкцию или выражение. Нет eval, send, instance_eval, определений методов/классов/модулей, require, исключений (begin/rescue), диапазонов, регулярных выражений и множественного присваивания. Блоки есть только там, где их перечисляет этот документ: циклы each/each_with_index/each_slice, фиксированный набор методов Array и Hash (map, select, sum, group_by ... — см. Блоки), вызовы хелперов (form_with(...) do |f| ... end) и построитель tag. Каждый вызов метода (recv.name) разрешается написанными вручную таблицами диспетчеризации case в interpreter.rb по классу Ruby получателя во время выполнения; имя, которого нет в таблице этого типа, приводит к RuntimeError — нет ни method_missing, ни рефлексии, и (согласно Interpreter#call_method) именно отсутствие send в Spinel объясняет, почему это case, а не поиск через метапрограммирование. Шаблон может делать только то, что описано в этом документе.
Где это находится в исходникахвосемь файлов конвейера шаблонов
Конвейер находится в cybertrain/template/:
| Файл | Роль |
|---|---|
lexer.rb |
Делит исходный текст на теги <% %>/<%= %>/<%== %>/<%# %> и обычный текст |
parser.rb |
TreeBuilder вкладывает теги в AST; ExprParser разбирает грамматику выражений внутри одного тега |
ast.rb |
Классы узлов AST, которые создаёт парсер |
inode.rb |
Compile уплощает AST в мономорфные INode (целочисленный «вид» плюс типизированные слоты) для быстрой интерпретации |
interpreter.rb |
Обходит INode по env (Hash<String, value>); содержит все таблицы «какие методы существуют» для каждого типа |
helpers.rb |
link_to, form_with, render, pluralize, ... — всё, что шаблон вызывает без получателя |
form_builder.rb |
f, передаваемый в form_with(...) do |f| ... end |
engine.rb |
Загружает исходники .html.erb — с диска из корневого каталога или из встроенной таблицы gen/views.rb (Engine.embedded), — разбирает их (и при необходимости кэширует), отрисовывает с макетом |
Теги
| Тег | Значение |
|---|---|
<% code %> |
Выполняет инструкцию; ничего не выводит |
<%= expr %> |
Вычисляет expr и выводит его с HTML-экранированием |
<%== expr %> |
Вычисляет expr и выводит его без экранирования |
<%# comment %> |
Игнорируется (кроме формы locals: в строке 1, см. ниже) |
Управление пробельными символами (Lexer.tokenize):
- Тег
<% %>/<%# %>, который является единственным содержимым своей строки (по обе стороны до переводов строки — только пробелы/табуляции), молча поглощает свой отступ и завершающий перевод строки, как режим обрезки ERB в Rails.<%= %>/<%== %>никогда не обрезаются так автоматически, даже если стоят на строке одни. <%-явно удаляет пробелы/табуляции перед тегом, а-%>удаляет один перевод строки сразу после него — для тега любого вида. Оба ничего не делают, если с этой стороны строки есть что-то кроме пробельных символов.<%%в тексте — буквальный<%;%%>внутри тега — буквальный%>, который не закрывает тег.<% # a Ruby-style comment %>(тег кода, содержимое которого начинается с#) игнорируется, как<%# %>. Комментарий после настоящего кода в том же теге не поддерживается —<% x = 1 # note %>даётSyntaxError.- Незакрытые теги вызывают ошибку на этапе лексического анализа:
"posts/show:2: unterminated <% tag".
Комментарий строгих локальных переменных
Тег комментария, содержимое которого начинается с locals: и который является самым первым тегом файла, в строке 1, объявляет единственные локальные переменные, которые принимает шаблон (почти всегда партиал):
<%# locals: (post:, comment:) %>
<%= post.title %>
<%# locals: () %>(пустой список) означает «этот партиал не принимает локальных переменных».- Каждая запись должна быть голым
name:в нижнем регистре (Lexer.identifier?принимает только[a-z_][a-z0-9_]*). As built: в отличие от Rails 7.1, записи не могут иметь значение по умолчанию —<%# locals: (post:, comment: nil) %>, ровно та форма, которую поддерживает Rails 7.1, даётSyntaxError:"t:1: bad strict locals entry 'comment: nil' (expected name:)", потому чтоcomment: nilне оканчивается на:. Фактически каждая объявленная локальная переменная обязательна. Некорректная спецификация (без скобок) вызывает"t:1: bad strict locals comment (expected locals: (name:, ...))". - Без этого комментария шаблон не объявляет списка локальных переменных:
renderпередаёт любые полученные локальные переменные без проверки, и шаблон может также читать всё, что уже есть в окружении вызывающего (см. Макеты,yield,content_for, партиалы). - Если перед комментарием на более ранней строке что-то есть (даже одна пустая строка), это просто обычный, ни на что не влияющий комментарий, а не объявление локальных переменных.
Выражения
Литералы
| Литерал | Синтаксис | Примечания |
|---|---|---|
| Integer | 1, 1_000 |
подчёркивания разрешены; нет шестнадцатеричной/восьмеричной/двоичной записи и экспоненты |
| Float | 2.5, 12_3.4_5 |
цифра обязательна с обеих сторон .; экспоненциальной формы нет |
| String | "...", '...' |
двойные кавычки поддерживают интерполяцию и escape-последовательности; одинарные понимают только \' и \\ |
| Symbol | :title |
только символы идентификатора — нет :"quoted" и символов-операторов вроде :+ |
nil / true / false |
||
| Array | [1, "a", :b], [] |
элементы — полноценные выражения |
| Hash | { a: 1, b: "x" }, {} |
только ключи в стиле символов, той же формы, что и именованные аргументы; без "key" => value (hashrocket) |
Строки в двойных кавычках интерполируют #{...} (любое полноценное выражение, допускается вложение) и поддерживают \n \t \r \0 \e \s, \", \\; любой другой экранированный символ проходит без изменений. Строка без #{} компилируется в простой литерал; строка с интерполяцией — в последовательность литеральных фрагментов и выражений.
Переменные
@ivarнапрямую читаетenv["ivar"]—@лишь внешний синтаксис; согласно D9, «post — это и@post, и локальнаяpost» в одном Hash окружения. Отсутствующая переменная экземпляра — простоnil:[<%= @missing %>]выводит[], никогда не ошибку.- Голое имя локальной переменной (
post,title) тоже читаетenv["name"], но если такого ключа вовсе нет, интерпретатор считает это вызовом хелпера без аргументов. Если ключ существует (даже привязанный кnil— скажем, объявленная, но не переданная строгая локальная переменная), возвращается его значение, без перехода к хелперу. Поэтому<%= csrf_meta_tags %>и<%= flash %>работают без скобок, а<%= nope %>завершается ошибкой"undefined helper 'nope'", а не «нет такой локальной переменной». - Локальные переменные берутся из параметров блоков
each/each_with_index, параметра блокаform_with, строгих локальных переменных партиала и<% name = expr %>.
Вызовы методов
recv.method
recv.method(arg1, key: value)
recv&.method # безопасно для nil: если recv равен nil, сразу даёт nil, аргументы не вычисляются
method(arg1, key: value) # вызов хелпера: без получателя
method arg1, key: value # тот же вызов без скобок («командный» синтаксис)
- Список аргументов без скобок («командный») открывается только для самого внешнего вызова в выражении:
link_to "Show", post_path(post)работает, аlink_to "Show", post_path postдаётSyntaxError— внутренним вызовам нужны собственные скобки. - Между целью вызова и её открывающей
(пробел не допускается: работают иlink_to("x"), иlink_to "x";link_to ("x")даётSyntaxError. yieldиyield :keyвсегда разбираются как вызовы (см. Макеты,yield,content_for, партиалы).- Голое слово с заглавной буквы сразу отвергается —
"constants are not supported: 'Time'": шаблоны не могут обращаться к константам Ruby. - Эти слова зарезервированы и отвергаются с отдельным сообщением (
"'x' is not supported in templates") везде, где ожидается выражение:and or not do end if unless elsif else then while until def class module begin rescue return.caseиwhen— самостоятельные инструкции (case); внутри выражения (<%= case x %>) они отвергаются так же.
Операторы, приоритет (от низкого к высокому)
?: ternary, right-associative on both branches
||
&&
== !=
< > <= >=
+ -
* / %
! - (unary, prefix)
. &. [] (method call / safe-nav / indexing, left-to-right chaining)
&&/|| возвращают операнд, а не приведённое булево значение (nothing || title вычисляется в title, а не в true). Условия проверяют истинность: ложны только nil и false, как в Ruby, — 0, "" и пустые массивы/хеши истинны (<% if 0 %>yes<% end %> выводит yes).
Индексирование — это target[index] без пробела перед [ (items [0] — синтаксическая ошибка, items[0] — нет), и оно образует цепочки, как любой постфикс: h["k"].first, params[:id].
Инструкции
Тег <% %> содержит ровно одну инструкцию: присваивание или выражение, вычисляемое ради побочного эффекта (значение отбрасывается). <%= %>/<%== %> всегда содержат только выражение — <%= x = 1 %> даёт SyntaxError.
Условия
<% if cond %>...<% elsif other %>...<% else %>...<% end %>
<% unless cond %>...<% else %>...<% end %>
unless/else/elsif следуют правилам Ruby; elsif после else, лишние else/elsif/end или блок, так и не закрытый end, — всё это SyntaxError с указанием строки открытия.
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 %>
- Предмет вычисляется один раз; значения каждого
when(одно или несколько, через запятую) по порядку сравниваются оператором==шаблона, и выполняется первая ветка с равным значением. Числа сравниваются по значению (1совпадает с1.0); String и Symbol — по значению и типу ("a"не совпадает с:a); записи — как это делает==(класс иid); Array и Hash — как это делает==(по значению, поэлементно);SafeStringиStringс одинаковым текстом равны.===нет: послеwhenне бывает диапазонов, классов или регулярных выражений. elseвыполняется, когда ни одно значение не совпало; безelseи без совпадения ничего не выводится.- Между
caseи его первымwhenможет стоять только пустой текст (отступы, переводы строк); он отбрасывается. Всё остальное там —SyntaxError("text between 'case' and its first 'when'"). whenвнеcase("'when' without 'case'"),caseбез предмета или безwhen,whenбез значения или послеelse, а такжеcase, так и не закрытыйend, — этоSyntaxErrorс номером строки.thenпо-прежнему зарезервировано:<% when :a then x %>—SyntaxError.- Локальная переменная, впервые присвоенная внутри ветки, подчиняется правилу локальности того блока, в котором стоит, как и с
if.
Циклы
<% @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_indexраспознаются только как суффикс заголовка блока (x.each do |...|); коллекцией может быть любое выражение, в том числе вызов с блоком (<% items.group_by { |i| i.kind }.each do |kind, list| %>). As built: оба требуют объявить один или два параметра блока —xs.each do endдаётSyntaxError(«takes one or two block parameters»), тогда как обычный Ruby допускает ноль.<% x.each_slice(n) do |slice| %>...<% end %>перебирает срезы поnэлементов (последний может быть короче) и тоже требует одного или двух параметров; с двумя срез разбирается на части (do |a, b|), а второй равенnil, если срез короткий.- Array + один параметр: элемент. Array + два параметра: элемент-
Arrayдеструктурируется (a, b = item[0], item[1]); иначе второй —nil. each_with_indexна Array:item, i. На Hash: первый параметр — пара[key, value], второй — индекс.eachна Hash с двумя параметрами: непосредственноkey, value; с одним параметром — пара[key, value].- Перебор
nil,Timeили любого скаляра — этоRuntimeError("undefined method 'each' for Time"), никогда не молчаливое бездействие. - Параметр блока затеняет одноимённую внешнюю локальную переменную только на время цикла и после него удаляется (
refute env.key?("item")после окончания цикла). Переменная, существовавшая до блока, внутри него — та же самая переменная (видна и после цикла); переменная, впервые присвоенная внутри блока, локальна для блока —nilв начале каждой итерации и исчезает после.
Вызовы с блоком (хелперы)
do ... end — это также способ передать блок вызову хелпера без получателя (о вызове с получателем см. Блоки):
<%= 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 "" %>
Выводится ли результат блока, зависит от тега: <%= helper do |x| %> его выводит, <% helper do |x| %> отбрасывает. Привязывается всегда ровно один параметр блока; блок хелпера никогда не получает индекс или второе значение.
Блоки
Вызов с получателем может принимать блок, { |x| expr } или do |x| ... end, с нулём, одним или двумя параметрами. Какие методы его принимают, задано для каждого типа; блок в любом другом месте — это SyntaxError, возбуждаемый при выполнении вызова ("String#upcase takes no block"), а метод, которого у типа нет, — обычное "undefined method 'x' for Array", с блоком или без.
| Получатель | Методы, принимающие блок | Значение блока используется как |
|---|---|---|
Array |
map select reject find any? all? none? count sum sort_by min_by max_by group_by |
преобразованное значение, проверка, слагаемое, ключ сортировки, ключ группы |
Hash |
map select reject find any? all? none? count sum sort_by min_by max_by group_by |
то же самое, блок видит |key, value| (один параметр получает пару [key, value]); select/reject возвращают Hash, остальные — то, что метод Array возвращает для пар |
построитель tag |
каждый элемент (tag.div do ... end) |
его вывод становится содержимым элемента (Построитель 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 %>
- Значение, а не вывод. Для методов Array и Hash важно значение блока: выражение блока
{ }или последняя инструкция блокаdo, которая должна быть инструкцией-выражением (<% x * 2 %>); иначе —"map's block must end in a value"(присваивание или текст). То, что выводят предыдущие инструкции блокаdo, отбрасывается. Блокdoу такого метода стоит в собственном теге, с присваиванием (<% total = items.sum do |li| %>) или с выводом (<%= items.map do |x| %>). - Никаких изменений. У шаблонов нет способа изменить аккумулятор, поэтому
each_with_objectиinjectв таблице нет ("undefined method 'each_with_object' for Array"): используйтеmap,select,sumилиgroup_by. - Два параметра разбирают элемент Array на части, как это делает
each(pairs.map { |a, b| a }). sumпустого Array равна0; сумма Integer — Integer, Float где угодно делает её Float (складывается с той же компенсацией, что в Ruby, так что[0.1, 0.2, 0.3].sumравно0.6); String отвергаются ("sum: use join for Strings"), как и всё, что не число.sort_by,min_by,max_by(иsort,min,maxбез блока) сравнивают так же, как<(числа, String, Time; иначе"comparison of String with Integer failed").sort_byустойчива: равные ключи сохраняют порядок.min_by/max_byпустого Array равныnil.group_byвозвращает Hash из каждого ключа в виде String (у всех Hash шаблона ключи — String::fruitи"fruit"— одна группа) в элементы с этим ключом, в порядке первого появления.each,each_with_indexиeach_sliceпринимают блок в теге<% %>(Циклы);items.each { |x| x }—SyntaxError.- Блок у метода
FormBuilderилиPageотвергается так же ("FormBuilder#label takes no block"), а методы Array без блока не принимают аргументов (nums.sum(10)—"wrong number of arguments for 'sum'"). - Если блок возбуждает исключение, его параметры и локальные переменные восстанавливаются до того, как ошибка покинет вызов.
- Блоку
{ }нужен получатель:shout { |x| x }—SyntaxError(вызовы хелперов принимаютdo ... end). - Параметры блока затеняют внешние имена на время вызова и восстанавливаются после него; локальная переменная, впервые присвоенная в блоке
do, локальна для блока, как вeach.
Присваивание
<% total = 0 %><% total = total + 2 %><%= total %> <%# => 2 %>
Только name = expr для одной простой локальной переменной — нет @ivar = ..., нет arr[0] = .../h[:k] = ..., нет a, b = .... То же правило локальности для блока, что и у each, применяется к присваиваниям внутри if/unless, вложенных в блок.
Таблица методов по типам
nil?, present? и blank? проверяются до диспетчеризации по типу, поэтому работают на любом значении, включая модели и объекты, возвращённые хелперами (blank? равен false для всего, кроме nil/false/пустых SafeString/String/Array/Hash/Errors/Params). Арифметика (+ - * / %) и сравнение (== != < > <= >=) существуют только как инфиксные операторы, никогда как вызовы .method — в этой грамматике символ оператора не может стоять после ..
| Тип | Методы | Пример |
|---|---|---|
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) (Array из Array) zip(other), а также методы с блоком из раздела Блоки |
post.comments.any? |
Hash |
key?(k) fetch(k, default) size/length/count empty? any? keys values to_a (пары [key, value]), а также h[key] и методы с блоком из раздела Блоки |
flash.key?(:notice) |
Errors |
any? empty? count/size full_messages key?(a)/include?(a), а также errors[:attr] |
post.errors.full_messages.join(', ') |
Params |
key?(k) empty?, а также 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 (возвращает "") |
Индексирование (x[key]) — отдельное правило грамматики (Выражения), а не вызов .[]: Array/String принимают целочисленный индекс, Hash сопоставляет любой ключ по его to_s (h[:k] и h["k"] — одна и та же запись), Errors — по символу, Params — по to_s.
Вывод (<%= %>/интерполяция) помимо to_s выше: Array выводится как список в духе inspect — [1, "a", nil] выводит текст [1, "a", nil] (затем экранируется, поэтому кавычки становятся "); Hash откатывается к собственному Hash#to_s Ruby; Cybertrain::Model выводится как #<Post id: 7> (никогда не его атрибуты); всё остальное выводится через собственный to_s. Неперечисленный метод у любого из этих типов — это RuntimeError ("undefined method 'first' for Time"). Целочисленное деление или остаток от деления на ноль для Integer — "divided by 0"; Float вместо этого следует IEEE-754 (Infinity/NaN, без ошибки).
Модели в шаблонах
Подкласс Cybertrain::Model (сгенерированный Post, Note, ...) разрешает голое имя в таком порядке (Interpreter#model_method):
- Пять встроенных, доступных всегда:
id,persisted?,new_record?,to_param(id.to_s),errors(Errors, Таблица методов по типам). read_attribute(:name)— сгенерированный столбец.read_association(:name)— сгенерированная ассоциацияhas_many/belongs_to.call_view_method(:name)— написанный вручнуюdefбез аргументов, который генератор моделей нашёл вapp/models/**/*.rb(никогда с аргументами).
<%= post.title %> <%# read_attribute %>
<% post.comments.each do |c| %>...<% end %> <%# read_association %>
<%= post.summary %> <%# call_view_method %>
<%= post.errors.full_messages.join(", ") %>
Если все четыре отвечают nil, attribute_or_method?(:name) решает, было ли это допустимым именем, которое просто содержит nil (возвращается nil), или опечаткой ("undefined method 'bogus' for Post").
Сгенерированные модели отвечают на это по своей схеме. spin run gen выводит attribute_or_method? в каждой модели как case по её столбцам (переименованный столбец под обоими именами), ассоциациям и публичным методам представления, поэтому <%= post.titel %> для сгенерированной модели даёт "posts/show:3: undefined method 'titel' for Post", а столбец, содержащий nil, выводится пустым. Базовый Cybertrain::Model#attribute_or_method? (в model.rb) по-прежнему возвращает true: написанный вручную подкласс Cybertrain::Model, который его не переопределяет, выводит неизвестное имя пустым. Замечание при обновлении: шаблон, читавший имя, которого у модели никогда не было, раньше выводил пустоту, а после следующего spin run gen возбуждает ошибку (docs/design.md D71).
Две модели сравниваются через == по классу и id (Model#==), доступному как обычный оператор == (встроенная диспетчеризация равенства, а не call_method).
Хелперы и построитель форм
Каждый вызов без получателя идёт в Helpers#helper_call (helpers.rb), который сопоставляет его с одним из встроенных хелперов ниже; внутри шаблона компонента затем пробует методы представления этого компонента; считает имя, оканчивающееся на _path/_url, сгенерированным хелпером маршрута (через Cybertrain::Views.url_resolver, возбуждая "no routes", пока приложение его не установит); затем пробует хелперы приложения; или возбуждает "undefined helper 'name'".
| Хелпер | Сигнатура | Примечания / пример |
|---|---|---|
link_to |
link_to(text, href, class:, id:, data_confirm:, data: {}) |
text экранируется, если это ещё не SafeString; нет method: — возбуждает ошибку, предлагая использовать button_to (никакой имитации ссылок DELETE через rails-ujs/turbo) |
button_to |
button_to(text, action, method: :post, class:, data: {}) |
<form class="button_to"> с одной кнопкой; скрытый _method для любого глагола, кроме get/post, плюс поле CSRF, когда есть сессия |
form_with |
form_with(model:, url:, scope:, method:, class:, data:, multipart:, local:) do |f| ... end |
нужен блок; новая model: → маршрут коллекции + POST, сохранённая → маршрут элемента + PATCH; [parent, child] для вложенного маршрута, [:admin, @article] для маршрута в пространстве имён; url:/method: переопределяют выведенные действие/глагол; scope: :q называет поля q[term] (с model: заменяет префикс модели); data: { turbo_frame: "f" } пишет атрибуты data-; local: принимается и ничего не меняет; multipart: true добавляет enctype="multipart/form-data" (обязательно для f.file_field; никогда не угадывается по блоку и возбуждает ArgumentError на 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>; option_tags, не являющийся SafeString, экранируется; multiple: true называет его order[]; остальные именованные аргументы — атрибуты |
options_for_select |
options_for_select(choices, selected = nil) |
строки <option> для вариантов f.select (ниже); selected — значение или массив значений, сравниваемых как String |
options_from_collection_for_select |
options_from_collection_for_select(records, :id, :name, selected = nil) |
по <option> на запись, значение и текст читаются так же, как в f.collection_select |
t, translate |
t(key, default:, count:, locale:, name: value) |
текст по key в локали запроса, экранированный; t(".title") в posts/index.html.erb читает posts.index.title, в partial posts/_form.html.erb — posts.form.title; ключ на _html выводит свой HTML и экранирует значения (Интернационализация) |
l, localize |
l(time_or_date, format: :short, locale:) |
time.formats / date.formats локали или шаблон strftime с названиями дней и месяцев локали (Даты и время) |
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") |
теги форм без модели: label_tag(:term) → <label for="term">Term</label>; hidden_field_tag пишет autocomplete="off"; submit_tag называется commit; остальные именованные аргументы — атрибуты (id: заменяет id, взятый из имени) |
check_box_tag |
check_box_tag(name, value = "1", checked = false) |
флажок без модели и без скрытого поля, так что неотмеченный ничего не отправляет: check_box_tag :remember_me → <input type="checkbox" name="remember_me" id="remember_me" value="1">; остальные ключевые аргументы — атрибуты |
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 |
см. Макеты, yield, content_for, партиалы, Коллекции и Компоненты |
h, escape |
h(text) |
экранирует; SafeString проходит без экранирования |
raw |
raw(text) |
оборачивает текст в SafeString (выводится без экранирования) |
pluralize |
pluralize(count, singular, plural = nil) |
pluralize(1, "comment") → "1 comment"; pluralize(2, "mouse") → "2 mice" (английские правила словоизменения Rails по умолчанию, через Cybertrain::Inflector, только на английской странице: в другой локали слово остаётся как есть; правила, определённые приложением, не поддерживаются); явный третий аргумент всегда побеждает |
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" } заменяет название единицы (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"; отрицательное число пишет - перед форматом |
number_to_human_size |
number_to_human_size(n) |
1234 → "1.21 KB" (основание 1024); 1 → "1 Byte" |
time_ago_in_words |
time_ago_in_words(time) |
интервалы в стиле Rails, без точности до секунд: "less than a minute" … "about 1 hour" … "3 days" … "about 1 year", из datetime.distance_in_words локали (по-японски "2分") |
content_for / content_for? |
content_for(:key) do...end, content_for(:key, "text"), content_for?(:key) |
см. Макеты, yield, content_for, партиалы |
csrf_meta_tags / csrf_token |
пусто / отсутствует без сессии контроллера | |
csp_meta_tag / content_security_policy_nonce |
<meta name="csp-nonce" content="..."> / сам nonce — nonce Content Security Policy этого запроса; "", когда политика не действует |
|
javascript_tag |
javascript_tag(nonce: true) do ... end, javascript_tag(js) |
содержимое в <script> (без экранирования, как в Rails: никогда не помещайте туда данные запроса), с nonce при nonce: true, когда действует политика; id:, type:, data: — атрибуты |
asset_path |
asset_path("logo.svg") |
/assets/logo-1a2b3c4d.svg (см. Ассеты); URL или путь, начинающийся с /, возвращается как есть |
stylesheet_link_tag |
stylesheet_link_tag("application", media:, nonce:) |
<link rel="stylesheet" href="/assets/application-1a2b3c4d.css"> (.css добавляется, если его нет) |
javascript_include_tag |
javascript_include_tag("legacy", nonce:) |
<script src="/assets/legacy-1a2b3c4d.js"></script> (.js добавляется, если его нет) |
image_tag |
image_tag(source, alt:, size:, class:) |
<img src="/assets/logo-1a2b3c4d.svg" alt="Logo" width="16" height="16"> при size: "16x16" (или "16"); alt не придумывается, alt: "" записывается |
javascript_importmap_tags |
javascript_importmap_tags(entry = "application") |
import map, ссылка modulepreload на каждый предзагружаемый pin и import "application", каждый с nonce, когда действует политика (Ассеты); нужен запрос |
flash |
похож на Hash: flash[:notice] |
|
params |
текущие Cybertrain::Params |
|
request_path |
текущий путь, "" без контроллера |
|
url_for |
url_for(target, format:, anchor:, k: v) |
String как есть, Model → маршрут элемента, [parent, child] → вложенный маршрут, [:admin, record] → маршрут в пространстве имён; именованные аргументы добавляются так же, как их добавляет хелпер пути (url_for("/x", format: :csv) → /x.csv) |
current_page? |
current_page?(path) |
относится ли этот GET- или HEAD-запрос к path (без учёта завершающего слеша; если в path есть query, она тоже должна совпасть); запись или массив проходит через url_for; false для любого другого метода; нужен запрос |
paginate |
paginate(page, path) |
page — это Cybertrain::Page (из Relation#page); выводит <nav class="pager"> с «Newer» (rel="prev"), <span class="pager-current">Page N</span> и «Older» (rel="next"); ссылка опускается, если такой страницы нет. Каждая ссылка — это path плюс строка запроса текущего запроса с заменённым page (для страницы 1 он убирается), заново закодированная и HTML-экранированная; path с собственным ?query использует вместо этого его. Page в шаблоне также отвечает на number, per, row_offset, next?, prev?, next_number, prev_number (<% if @page.next? %>) |
*_path / *_url |
например, post_path(post), posts_path(page: 2, format: :json) |
генерируются приложением, разрешаются через Cybertrain::Views.url_resolver; именованные аргументы уходят в строку запроса, format: добавляет расширение, а anchor: — фрагмент (Редиректы и строки запроса) |
tag |
tag.div(content, attrs) do ... end |
построитель tag: см. Построитель tag |
content_tag |
content_tag(name, content = nil, attrs) или с блоком do |
content_tag "p", "<i>", class: "n" → <p class="n"><i></p>; те же правила, что у tag |
safe_join |
safe_join(array, sep = "") (без именованных аргументов) |
соединяет в SafeString, экранируя каждый элемент и разделитель, которые ещё не SafeString: safe_join([tag.b("a"), "<"], " ") → <b>a</b> < |
class_names |
class_names(*values) |
class_names/token_list из Rails: слова из String и Symbol, из Array (в том числе вложенных) и из каждого ключа Hash с истинным значением, каждое слово один раз; именованные аргументы — ещё один такой Hash: class_names("btn", active: @on, big: false) → "btn active" |
dom_id |
dom_id(record, prefix = "") (префикс позиционный, как в Rails) |
"article_12", "new_article" для несохранённой записи, dom_id(@article, "edit") → "edit_article_12" (Cybertrain::Html.dom_id в Ruby) |
turbo_stream_from |
turbo_stream_from(*streams, ws: false) |
один <turbo-stream-source>, подписывающий страницу на потоки (String или записи с именами вида "articles:12"); ws: true даёт URL ws:///wss:// и требует запроса. См. Реальное время |
signed_stream_name |
signed_stream_name(*streams) |
только подписанный токен, для написанного вручную JavaScript |
stream_source_path |
stream_source_path(*streams, mode: "json") |
путь точки входа потоков с токеном и mode=json (или "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>; запись даёт свой dom_id; каждый атрибут — только если задан |
turbo_stream |
turbo_stream.replace(target, partial:, locals:), .update(target, html:), .append(target) do ... end, .prepend, .before, .after, .remove(target) |
один элемент <turbo-stream action="..."> для шаблона *.turbo_stream.erb; цель — DOM id или запись; ровно одно из: блок, partial: (с locals:) или html: |
time_tag |
time_tag(time, text = nil, format:, class:, id:, title:, data:) или с блоком |
<time datetime="2026-11-10T12:00:00Z">Tue, 10 Nov 2026 12:00:00 +0000</time>; Date даёт 2026-11-10; без format: текст — формат :default локали; format: — имя формата (:short, :long или любое другое из словарей), которое форматирует l в локали запроса, или String для strftime (с английскими названиями дней и месяцев; неизвестная директива вызывает исключение, как и ширина или флаг, которые strftime прочитал бы иначе: %6L, используйте %6N; : только в %:z; никаких флагов заполнения у %F %T %D %R %r %c %x %X %v; ширина у числа заменяет его заполнение, %5e даёт " 5") |
Каждый текстовый аргумент хелпера следует одному правилу: SafeString проходит без экранирования, всё остальное экранируется — link_to raw('<b>raw</b>'), post выводит тег жирного шрифта буквально, а link_to post.title, post его экранирует.
Шесть числовых хелперов — это хелперы Cybertrain::NumberHelper, которые код на Ruby вызывает как функции модуля с теми же именованными аргументами (Cybertrain::NumberHelper.number_to_currency(price, unit: "€")). Они принимают Integer, Float или числовую String (десятичные столбцы — Float) и округляют половину вверх по цифрам её десятичного текста, поэтому результат одинаков в обоих рантаймах; любое другое значение вызывает ArgumentError ("number_with_delimiter: \"abc\" is not a number"), как и точность вне диапазона от 0 до 100. В шаблоне nil даёт "" (десятичный столбец, допускающий null, выводится пустым, как в Rails); Cybertrain::NumberHelper, вызванный из Ruby, по-прежнему вызывает ArgumentError для nil ("number_with_delimiter: nil is not a number"). В шаблоне значения по умолчанию берутся из локали запроса (number.* в словарях: японский number_to_currency(1234) — "1,234円"), а переданный ключевой аргумент побеждает; из Ruby это английские значения, показанные выше.
Построитель tag
tag вычисляется в построитель (Cybertrain::Html::TagBuilder); любой вызванный у него метод — это элемент, который отрисовывает Cybertrain::Html.tag (его можно вызвать и из 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 %>сам по себе ничего не выводит.- Имя элемента — имя метода с
_, заменёнными на-; оно должно соответствовать[a-z][a-z0-9-]*(иначеHtml.tagвозбуждает"invalid element name 'Div'"). - Содержимое — единственный позиционный аргумент (экранируется, если это не
SafeString, так чтоtag.script("alert(1)")выводит свой текст экранированным) или вывод блока (do ... endили{ expr }, чьё значение выводится экранированным); блок побеждает. Без того и другогоtag.div— это<div></div>. - Пустые элементы (
area base br col embed hr img input link meta source track wbr) отрисовываются без закрывающего тега; содержимое или блок для них — ошибка ("br is a void element"). - Атрибуты — это именованные аргументы, по порядку:
nilиfalseубирают атрибут,trueотрисовывает его без значения (disabled), Array соединяет свои элементы, кромеnil, пробелами (data: { ids: [1, 2] }даётdata-ids="1 2", а не JSON, как в Rails),class:принимает то же, чтоclass_names(class: ["btn", { active: @on }]), Hash вdata:иaria:раскрываются вdata-key="v"/aria-key="v"с подчёркиваниями, заменёнными на дефисы (иtrue/falseтам записываются словами); любое другое значение-Hash — ошибка ("attribute 'title' cannot be a Hash"). Каждое значение экранируется,SafeStringтоже. Имена атрибутов должны соответствовать[a-zA-Z_:][-a-zA-Z0-9_:.]*("invalid attribute name 'data-a b'");onclick:и подобные разрешены, раз их пишет автор.
FormBuilder (f в form_with ... do |f|)
Каждый метод возвращает SafeString; неперечисленный — это RuntimeError ("undefined method 'color_wheel' for FormBuilder").
| Метод | Выводит |
|---|---|
f.label :title / f.label :title, "Text" |
<label for="post_title">Title</label> — текст по умолчанию — «очеловеченный» атрибут (published_at → «Published at», author_id → «Author»); явный текст экранируется, если это не SafeString |
f.text_field :title (также 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 никогда не выводит value=; telephone_field — это type="tel"; Time записывается так, как его читает браузер (2026-11-10, 2026-11-10T12:00:00, 12:00:00.000) |
f.select :status, ["draft", "published"] (также include_blank:, prompt:, selected:, disabled:, multiple:) |
<select name="post[status]" id="post_status"> с <option> на каждый вариант, текущее значение выбрано; варианты — значения, пары [text, value] или Hash либо группы [label, [choices]] для <optgroup>; multiple: true называет его post[status][] и сначала пишет пустой скрытый input |
f.collection_select :author_id, @authors, :id, :name |
<select> с <option> на каждую запись, значение и текст читаются из двух методов |
f.radio_button :status, "draft" |
<input type="radio" name="post[status]" id="post_status_draft" value="draft">, отмечен, когда значение совпадает (checked: имеет приоритет) |
f.file_field :cover (также accept: "image/*", required: true) |
<input type="file" name="post[cover]" id="post_cover"> — никогда не выводит value=, и атрибут не обязан быть столбцом; форма должна быть form_with ..., multipart: true; multiple: true возбуждает ArgumentError (один файл на поле) |
f.text_area :body |
<textarea name="post[body]" id="post_body">\n...</textarea> (ведущий \n, как в Rails, — браузеры съедают первый перевод строки) |
f.check_box :published |
скрытый input с value="0", затем настоящий флажок, поэтому неотмеченный флажок всё равно отправляет "0"; include_hidden: false не пишет скрытый input |
f.submit / f.submit "Text" |
текст по умолчанию "Create Post"/"Update Post" (по persisted?) или "Save changes" без модели |
С моделью поля называются post[title]/id="post_title" (Inflector.underscore(model.model_name) как область видимости); form_with(..., scope: :q) использует вместо этого q[title]/id="q_title"; с form_with(url: ...) без модели и области видимости для обоих используется голое имя атрибута. Каждое значение атрибута и каждый текст варианта экранируется один раз (SafeString — как есть). Дополнительные именованные аргументы становятся HTML-атрибутами в заданном порядке: true → attr="attr", false/nil отбрасываются, всё остальное → attr="value" (с экранированием), подчёркивания становятся дефисами (data_confirm: "Sure?" → data-confirm="Sure?"), а class: объединяется с автоматическим классом field_with_errors, который добавляется, когда model.errors.key?(attr).
Хелперы приложения
Модуль в app/helpers/ — это модуль хелперов, как в Rails: каждый его публичный метод можно вызвать из любого шаблона без получателя.
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 %>
- Сгенерированная диспетчеризация. Шаблоны не умеют
send, поэтомуspin run genчитаетapp/helpers/**/*.rbкак текст и пишетgen/helpers.rb: классApplicationHelpers, который включает каждый модуль (и хелперы маршрутов), иcaseпо именам хелперов. Добавьте хелпер или измените его сигнатуру — и следующая сборка сгенерирует его заново (сервер разработки делает и то, и другое).cybertrain generate helper pricesпишет пустойPricesHelperи тест. - Что считается хелпером. Публичные методы экземпляра
module(неdef self.x, не сеттеры и не всё послеprivateилиprotected), в каком бы файле они ни были. Шаблон передаёт значения по позиции или по ключу, поэтому каждый параметр именован:*rest,**opts,...— ошибки генератора, как и обязательный параметр после необязательного. У хелпера не больше трёх необязательных параметров (у сгенерированногоcaseпо ветке на каждое переданное сочетание, так что опущенный ключ получает значение по умолчанию самого метода). Неправильный вызов — этоArgumentErrorпри отрисовке:"wrong number of arguments for 'price' (given 0, expected 1)","unknown keyword 'cur' for 'price' (known: unit, precision)". - Зарезервированные имена. Хелпер нельзя назвать как хелпер фреймворка (
link_to,render,tag,dom_id,params,content, ...), как методCybertrain::Template::Helpers(публичный или приватный:includeзаменил бы его и для фреймворка),yieldили с окончанием_path/_url(на них отвечают хелперы маршрутов); одно и то же имя в двух модулях — тоже ошибка.spin run genостанавливается, указывая файл, строку и причину. - Значения. Аргументы приходят как значения шаблона (String, Integer, Float,
nil, запись, Array, Hash); сужайте их черезCybertrain::Cast(Cast.str,Cast.int,Cast.float) перед арифметикой. То, что возвращает хелпер, выводится как любое значение:Stringэкранируется,SafeString— нет, поэтому собирайте HTML с помощьюCybertrain::Html.tag(name, attrs, content),Html.safe_join,Html.class_names,Html.dom_id,Html.escape,Cybertrain::SafeString.ofили Ruby-форм хелперов ссылок,link_to_path(text, path, attrs)иbutton_to_path(text, path, attrs)(method:внутриattrs). - Блоки. Хелпер с параметром
&blockпринимает блокdo ... end;yield(без аргументов) возвращает то, что вывел блок, в видеSafeString.
Компоненты
Компонент — это класс с именованными аргументами и шаблон рядом с ним, в духе 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 %>
- Шаблон видит переменные экземпляра компонента как локальные (
title), его публичные методы без параметров по имени (value_text) иcontent— то, что вывел блокdo(""без него). Он отрисовывается без макета, может отрисовывать партиалы и другие компоненты и учитывается вmax_render_depth, как партиал. Партиал, который он отрисовывает, методов компонента не видит. Имя партиала без каталога в шаблоне компонента (render "chip") ищется вapp/components/(app/components/_chip.html.erb); имя с каталогом (render "shared/note") — вapp/views/, как обычно. - Компонент называют по его имени в snake_case без
_component, как партиал называют по пути:"card"дляCardComponent,"admin/user_row"дляAdmin::UserRowComponent(app/components/admin/user_row_component.rb). Шаблоны не могут называть константы. spin run genпишетgen/components.rbпо лексическому разбору, как для хелперов: строка класса, присваивания@x =,defбез параметров и ключиinitialize.initializeпринимает только именованные аргументы (из них не больше трёх необязательных), и его шаблон должен существовать; отсутствующий или неизвестный ключ — этоArgumentErrorпри отрисовке. Неизвестный компонент —Cybertrain::Component::Unknown:"no component 'crad' (app/components/crad_component.rb, then `spin run gen`)". Имяcontentзарезервировано: ключinitializeили переменная экземпляра@contentс этим именем были бы перезаписаны выводом блока, поэтомуspin run genотказывается от них, называя файл и строку.app/views/components/остаётся обычным каталогом представлений (например, дляComponentsController); зарезервирован толькоapp/views/__components/— имена, под которыми хранятся шаблоны компонентов.cybertrain generate component card title value:integerпишет класс, его шаблон и тест, который отрисовывает его черезCybertrain::Test.render_component.
Отрисовка вне запроса
Рассылка, задача или тело письма отрисовываются без запроса:
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))
Оба возвращают HTML в виде String, с хелперами приложения. Хелперы путей работают (article_path(article)), strict locals проверяются, а формы (form_with, button_to) отрисовываются без токена подлинности (страница с Turbo отправляет токен из csrf_meta_tags). Хелпер, которому нужен запрос, возбуждает Cybertrain::Views::OutsideRequest ("csrf_token needs a request"): csrf_token, csrf_meta_tags, params, flash, request_path, current_page?, content_security_policy_nonce (а значит, csp_meta_tag и теговый хелпер с nonce: true), javascript_importmap_tags, любой хелпер *_url и turbo_stream_from ... ws: true. Ссылки paginate несут только собственную строку запроса пути. (Голый Cybertrain::Template::Helpers.new(nil), какой может построить модульный тест, вместо этого отвечает на них пустыми значениями.)
Макеты, yield, content_for, партиалы
Engine#render_with_layout(name, layout, env, helpers) отрисовывает name в env["__content"] (SafeString), затем отрисовывает layout с тем же env:
<title><%= yield :title %></title>
<%= yield %>
yield выводит env["__content"]; yield :key выводит env["__content_key"] или ничего, если значение не задано. yield обрабатывается особо прямо в интерпретаторе и не может быть переопределён как хелпер. Страница заполняет слот через content_for в любом месте своего тела (порядок относительно yield не важен — страница полностью отрисовывается раньше макета):
<% content_for :title do %>Post: <%= @post.title %><% end %>
<% content_for :title, " (draft)" %> <%# appends: calls accumulate, they don't replace %>
Макеты контроллера
Действие отрисовывается внутри app/views/layouts/application.html.erb (когда он есть), если только его контроллер, родитель или включённый concern не выбирает другой:
class AdminController < ApplicationController
layout "print", only: [:receipt] # app/views/layouts/print.html.erb
layout :choose_layout # метод: имя, false — без макета, nil — макет родителя
private
def choose_layout = request.header("Turbo-Frame").to_s.empty? ? "application" : "frame"
end
layout "admin" сам по себе задаёт один макет для всех действий. spin run gen читает строки layout (имя в кавычках, false или Symbol метода, с only: / except:) и пишет controller_layout(action) контроллера. Объявления перебираются по порядку, и побеждает первое подходящее (в Rails более позднее объявление заменяет более раннее); строки concern считаются на месте его include. render layout: "x" использует layouts/x для одного вызова, а render layout: false — никакого; начальный layouts/ допускается (layout "layouts/x" — это layouts/x). Строка layout или render layout:, называющие несуществующий макет, вызывают MissingTemplate; необязателен только макет application по умолчанию (действие тогда рендерится без макета). В макете отрисовывается только html; шаблон другого формата отрисовывается без него. Любой другой аргумент layout (nil, лямбда, константа) gen отклоняет.
Партиалы и render
<%= render "form", post: @post %>
<%= render partial: "form", locals: { post: @post } %>
<%= render "comments/comment", comment: c %>
- Голое имя без
/разрешается в собственном каталоге текущего шаблона (через ключ окружения, который устанавливает механизм отрисовки,__template_dir):render "form"изposts/showищетposts/_form.html.erb. Имя, содержащее/, — явный путь; префикс_получает только его последний сегмент ("comments/comment"→comments/_comment.html.erb). - Партиал получает копию всего окружения вызывающего (переменные экземпляра и все локальные переменные, уже находящиеся в области видимости) плюс явные локальные переменные, переданные в
render, — он не изолирован только тем, что было передано. Строгие локальные переменные проверяют по объявленному списку лишь имена, явно переданные в этот вызовrender; они не мешают партиалу читать и какое-то другое имя, унаследованное из окружения вызывающего. - Из области видимости партиала в область вызывающего копируются обратно только ключи
content_for(__content_*); обычные локальные переменные, которые он присваивает, наружу не утекают. - Отсутствующие или лишние локальные переменные относительно объявления
<%# locals: %>— этоRuntimeError:"missing local 'post' for posts/_form.html.erb","unknown local 'extra' for posts/_form.html.erb".
Коллекции
<%= 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:отрисовывает партиал один раз на каждый элемент массива, как локальную переменную с именем изas:(по умолчанию — имя самого партиала), с<as>_counter, считающим от 0,locals:, переданными каждому, иspacer_template:(партиал) между элементами; пустая коллекция ничего не выводит. Партиал со строгими локальными переменными получает счётчик, только если объявляет его, а элемент важнее локальной переменной с тем же именем.render @commentsвыбирает партиал каждой записи по её модели,<plural>/_<singular>(admin/notes/_noteдляAdmin::Note), поэтому список может смешивать модели.- Компонент, единственный обязательный именованный аргумент которого назван по нему (
CommentComponentсcomment:), получаетCommentComponent.with_collection(items), иrender component: "comment", collection: @commentsотрисовывает его по разу на элемент, передаваяcomment_counter:, когдаinitializeего объявляет.collection:не принимает других именованных аргументов (render component: "comment", collection: @comments, extra: 1— ошибка, называющая его); содержимое блока не передаётся.
Разрешение файлов (engine.rb)
"posts/show" и "posts/show.html.erb" называют один и тот же шаблон. Режим разработки читает app/views/ с диска с cache: false (файл перечитывается и заново разбирается, когда меняются его mtime или размер, и этот разбор пишет в кэш движка, поэтому сервер разработки всегда работает с одним воркером и игнорирует SPINEL_WORKERS, о чём сообщает в баннере при запуске); тестовое окружение читает с диска с cache: true (разбор один раз). Продакшен-бинарник никогда не обращается к диску: cybertrain build запускает spin run gen -- --embed-views, который записывает каждый *.erb из app/views/ (скрытые файлы и каталоги-символические ссылки пропускаются) в gen/views.rb, а Engine.embedded(sources) разбирает каждую запись один раз, при запуске бинарника (сообщения об ошибках сохраняют ту же форму posts/show.html.erb:12), так что шаблон с синтаксической ошибкой останавливает запуск, а не ломает свою страницу; бинарный файл с пустой таблицей отказывается запускаться в production. Отсутствующий шаблон возбуждает Cybertrain::Template::MissingTemplate — "Missing template <full path>" с диска, "Missing template posts/nope.html.erb (embedded)" из таблицы.
Поиск файлов разрешает корень представлений и путь к шаблону через символические ссылки и загружает только обычные файлы внутри этого корня. Пути, выходящие за его пределы (в том числе через символические ссылки), возбуждают MissingTemplate; exists? возвращает для таких путей false.
Ошибки
Два класса исключений, оба в пространстве имён Cybertrain::Template из ast.rb (отличны от ::SyntaxError/::RuntimeError):
SyntaxError— возбуждается при разбиении на токены и разборе, до какой-либо интерпретации. Форма:"<template>:<line>: <what>", например"posts/show:2: 'if' without 'end'","posts/show:1: unterminated <% tag","posts/show:1: unexpected ')' in 'foo(1))'". Возбуждается напрямую вEngine#template(а значит, в#render/#render_with_layout), когда файл страницы или макета не удаётся разобрать, — интерпретатор никогда его не перехватывает и не переоборачивает.RuntimeError— возбуждается при вычислении, та же форма сообщения, но<template>— это шаблон, который отрисовывается в данный момент (Interpreter#renderподменяет@nameна входе и выходе), — собственная ошибка партиала сохраняет имя и строку партиала, никогда не вызывающего:"posts/_row:1: undefined method 'bogus' for String".
Любая обычная StandardError из вызова хелпера или метода FormBuilder/пользовательского объекта (голый raise "text", ArgumentError, KeyError, даже Cybertrain::Template::RuntimeError из вложенного render) перехватывается и «перемещается»: переписывается в "<current template>:<current line>: <original message>", если только это уже не в точности последнее перемещённое сообщение (вложенный render уже проставил своё, более точное место), — в этом случае оно проходит без изменений. Cybertrain::Template::SyntaxError, возбуждённая хелпером (партиал, который не удалось разобрать посреди отрисовки), никогда не переоборачивается — она сохраняет собственное сообщение "<partial>:<line>: ..." и класс, поэтому сломанный партиал всегда сообщается как SyntaxError о нём самом, а не как RuntimeError о том, кто его отрисовал.
Cybertrain::Views::OutsideRequest и Cybertrain::Component::Unknown тоже проходят без обёртки, сохраняя свой класс, так что вызывающий Views.render_partial может их перехватить.
MissingTemplate (StandardError, engine.rb) возбуждается без обёртки, без префикса template:line, из вызова верхнего уровня Engine#template/#render/#render_with_layout (например, когда контроллер отрисовывает отсутствующий шаблон действия или макет): "Missing template <path>". То же исключение, возбуждённое внутри шаблона при поиске партиала хелпером render, проходит через перемещение и выходит как RuntimeError: "posts/inline:1: Missing template test/fixtures/views/posts/_nope.html.erb".
Отличия от ERB в Rails
| ERB в Rails | Cybertrain |
|---|---|
| Компилируется в метод Ruby; работает любой Ruby, любой объект, любой метод | Интерпретируется по фиксированным таблицам диспетчеризации для каждого типа; вызывать можно только то, что перечислено в таблице методов по типам |
ActiveSupport::SafeBuffer — подкласс String |
SafeString — отдельный класс-обёртка: у него можно вызывать только to_s/html_safe?/size/length/empty? |
Блоки: each, { }, map, любой метод Enumerable |
{ } и do...end у фиксированного списка методов Array/Hash (без each_with_object, inject), циклы each/each_with_index/each_slice, вызовы хелперов и tag |
xs.each { } — ноль параметров блока допустим |
each/each_with_index требуют объявить 1 или 2 параметра блока |
link_to text, path, method: :delete (через JS) |
У link_to нет method: — используйте button_to для настоящей не-GET формы |
Строгие локальные переменные принимают name: default_expr (Rails 7.1) |
Только голое name: (обязательное); запись со значением по умолчанию — SyntaxError |
| Неопределённая переменная экземпляра/локальная разрешается через Ruby / методы контекста представления | @x — простой, никогда не падающий поиск в окружении; голая неопределённая локальная — явная попытка вызова хелпера из замкнутого набора ("undefined helper", если совпадения нет) |
case/when с === (диапазоны, классы, регулярные выражения) |
case/when только с == (числа по значению) |
and/or/not, диапазоны, регулярные выражения, множественное присваивание — всё работает |
Ничего этого нет; зарезервированные слова дают конкретное сообщение «not supported in templates», а не общую ошибку разбора |
| Числовые литералы: шестнадцатеричные, восьмеричные, двоичные, экспоненты, рациональные | Только десятичные целые/дробные с необязательными разделителями _ |
:"quoted symbol", символы-операторы :+ |
Символы состоят только из символов идентификатора |
foo (x), foo [x] (пробел допускается, иногда с предупреждением) |
Оба — жёсткие SyntaxError: никаких пробелов перед ( вызова или [ индекса |
| Вложенные вызовы без скобок разрешает собственный парсер Ruby | Аргументы без скобок получает только самый внешний вызов в выражении |
Необъявленный атрибут или атрибут с опечаткой надёжно возбуждает NoMethodError |
Сгенерированная модель возбуждает "undefined method 'x' for Post" (Template::RuntimeError), а существующий атрибут со значением nil выводит пустым; написанная вручную модель, не переопределяющая attribute_or_method?, выводит неизвестное имя пустым |
1 / 0 и 1.0 / 0 оба возбуждают ZeroDivisionError |
Целочисленное деление/остаток на ноль для Integer возбуждает "divided by 0"; Float следует IEEE-754 (Infinity/NaN), без ошибки |
distance_of_time_in_words/плюрализация поддерживают локали i18n |
time_ago_in_words, distance_of_time_in_words, числовые хелперы и time_tag читают словарь локали; pluralize склоняет только по-английски (Интернационализация) |
Каждый модуль из app/helpers подмешивается; любая сигнатура; хелпер может переопределить хелпер фреймворка |
Модули разбираются при сборке в сгенерированный case: только именованные параметры, не больше трёх необязательных, никаких имён хелперов фреймворка и окончаний _path/_url (Хелперы приложения) |
ViewComponent: render CardComponent.new(title: "x"), with_collection, слоты |
render component: "card", title: "x" по имени, content из блока, collection: для компонента, названного по единственному обязательному именованному аргументу; без слотов (Компоненты, Коллекции) |
Более поздняя строка layout заменяет более раннюю |
Побеждает первое подходящее объявление layout (Макеты контроллера) |