module Bezel::Templates

The template compiler: HEEx-like templates (*.html.bz) made into Quarz code over the HTML DSL (Bezel.html), which bezel templates writes to src/views/generated/ and the application compiles as its own code. Nothing is interpreted at run time; the generated code is type-checked as any other, and escapes as the DSL does.

src = Bezel::Templates::Source.new("src/views/user/show.html.bz", "show",
  "{@args name: String}\n<h1 class=\"title\">Hello, {name}!</h1>\n")
Bezel::Templates.compile(src).lines[1].strip   # => "def self.show(name: String) -> Bezel::Html"

A template is HTML with:

• {expr}: the value of a Quarz expression, in a text or as an attribute's value (href={Routes.user_path(id: user.id)}). A String (or any value, by to_s) is escaped, a Bezel::Html is written as it is, nil writes nothing. {raw(expr)} writes a String unescaped, as does a Bezel::Html the code made with Html.raw: nothing else is unescaped, and the caller vouches for what these write. A { in a text is written {"{"}.
• {@args name: Type, ...} first: the parameters of the method the template becomes (as a def's, defaults and a block included). With one named conn, the page is Bezel.html(conn), whose forms carry the CSRF token. h is the builder's name in the generated code, so no parameter or variable is named h.
• :for={pattern <- expr} and :if={expr} on an element or a component: the element written for each element of expr (each, the pattern its block's parameters), or only when expr holds; with both, the condition is tested for each element.
• <.card title="x">...</.card>: the component class Card (including Bezel::Component; .admin.user_card is Admin::UserCard, names in lowercase), made with the attributes as keyword arguments (Card.new(title: "x"), class as class_name, a - as _, a bare one true) and given the content as its content. A slot <:footer>...</:footer> directly inside one is the keyword argument footer:, a Bezel::Html.
• <!-- ... -->: a comment of the template, left out of the page (but in textarea and title, whose content is text).

Elements are the DSL's (an unknown one is an error) and are closed explicitly (<br> or <br/> for a void element, <div/> for an empty one). An attribute is one of the element's own, a global one, class, data-* and aria-*, or a name with a - or a : (written as it is, attrs:); another name is an error, as a misspelled one would be. A boolean attribute is written bare (<input required>) or with an expression (disabled={locked}), an integer one with digits or an expression. script and style hold their text as it is (what the DSL would refuse in it is an error here); textarea and title hold text and expressions. Entities in texts and attribute values are decoded (the DSL escapes again): the numeric ones, and the named ones of Templates::ENTITIES (another is an error; write the character). Whitespace (ASCII: not  ) with a line break is one line break (all of it is kept inside pre and textarea), and the whitespace at the template's start and end is dropped, as at a component's or a slot's (but inside pre and textarea).

An expression's code goes in the generated code as written, in parentheses, so it is one expression without # comments, heredocs, lines starting with __END__ or =begin, or backslashes outside literals; a / (or a % that could start a percent literal, %w[) is an operator with a space on each side after a value (a.size / 2, n % 3), or starts a regular expression or a percent literal after (, [, a comma, the opening brace, or one of = == =~ !~ => && || or a keyword argument's colon spaced ({name.gsub(/\s/, "")}, {%w[a b]}, {s =~ /x/}): the compiler must see where the code ends as Quarz will, and refuses what it cannot. The generated code names the builder h and the slots' contents __bz_slot_<n>, which the template's own names avoid.

A template that cannot compile is a Templates::Error naming its path and line.

src/templates.qz:76

Classes and modules

• Bezel::Templates::Error A template that cannot compile: the message names its path and line (src/views/user/show.html.bz:3: <span> is not closed).
• Bezel::Templates::Source A template: its path (named in errors and in the generated file's header), the name of the method it becomes, and its text.

Constants

Class methods