drab v0.6.3 Drab.Live.EExEngine
This is an implementation of EEx.Engine that injects Drab.Live
behaviour.
It parses the template during compile-time and inject Drab markers into it. Because of this, template must be a proper HTML. Also, there are some rules to obey, see limitations below.
Limitations
Because Drab.Live
always tries to update the smallest portion of the html, it has some limits described below.
It is very important to understand how Drab re-evaluates the expressions with the new assign values. Consider the
comprehension with the condition as below:
<%= for u <- @users do %>
<%= if u != @user do %>
<%= u %> <br>
<% end %>
<% end %>
The template above contains two Drabbable expression: for
comprehension and if
condition. When the new
value of @users
is poked, all works as expected: the list is refreshed. But when you poke the @user
assign,
system will return an error that the u()
function is not defined. This is because Drab tries to re-evaluate
the expression with the @user
assign - the if
statement, and the u
variable is defined elsewhere.
But what was your goal when poking the @user
assign? You wanted to update the whole for
expression, because
the displayed users list should be refreshed. In the current version of Drab, the only way to archive it
is to move @user
assign to the parent expression. In this case it would be a filter on the comprehension:
<%= for u <- @users, u != @user do %>
<%= u %> <br>
<% end %>
In this case the whole for
expression is evaluated when the @user
assign is changed.
Avalibility of assigns
To make the assign avaliable within Drab, it must show up in the template with “@assign
” format. Passing it
to render
in the controller is not enough.
Also, the living assign must be inside the <%= %>
mark. If it lives in <% %>
, it will not be updated by
Drab.Live.poke/2
. This means that in the following template:
<% local = @assign %>
<%= local %>
poking @assign
will not update anything.
Local variables
Local variables are only visible in its do...end
block. You can’t use a local variable from outside the block.
So, the following is allowed:
<%= for user <- @users do %>
<li><%= user %></li>
<% end %>
and after poking a new value of @users
, the list will be updated.
But the next example is not valid and will raise undefined function
exception while trying to update an @anything
assign:
<% local = @assign1 %>
<%= if @anything do %>
<%= local %>
<% end %>
Attributes
The attribute must be well defined, and you can’t use the expression as an attribute name.
The following is valid:
<button class="btn <%= @button_class %>">
<a href="<%= build_href(@site) %>">
But following constructs are prohibited:
<tag <%="attr='" <> @value <> "'"%>>
<tag <%=build_attr(@name, @value)%>>
The above will compile (with warnings), but it will not be correctly updated with Drab.Live.poke
.
The tag name can not be build with the expression.
<<%= @tag_name %> attr=value ...>
Nested expressions are not valid in the attribute pattern. The following is not allowed:
<tag attribute="<%= if clause do %><%= expression %><% end %>">
Do a flat expression instead:
<tag attribute="<%= if clause, do: expression %>">
Scripts
Tag name must be defined in the template as <script>
, and can’t be defined with the expression.
Nested expressions are not valid in the script pattern. The following is not allowed:
<script>
<%= if clause do %>
<%= expression %>
<% end %>>
</script>
Do a flat expression instead:
<script>
<%= if clause, do: expression %>
</script>
Properties
Property must be defined inside the tag, using strict @property.path.from.node=<%= expression %>
syntax.
One property may be bound only to the one assign.
Link to this section Summary
Functions
Callback implementation for EEx.Engine.handle_begin/1
Callback implementation for EEx.Engine.handle_end/1
Link to this section Functions
Callback implementation for EEx.Engine.handle_begin/1
.
Callback implementation for EEx.Engine.handle_end/1
.