The Template Element
<Template name="template_name" [args="a_list_of_arguments"] [description="a_description"]>
The Template
element defines a template. A template will be compiled to a Dart function. The signature is as follows:
List<View> tempalte_name({View parent, a_list_of_arguments});
The name
attribute will become the function's name. The list of arguments specified in the args
attribute will become to the function's arguments. Notice that you shall not specify parent
in the args
argument. It is always generated.
The function will return a list of the top-level views being instantiated. In other words, it has the same content as parent.children
, if parent
is given.
If you want to add the created views as child views of a particular view, you can pass the view as the parent
argument. If you don't, you can simply ignore the parent
argument and retrieve them from the returned list.
For example,
<Template name="Simple" args="user">
<Panel layout="type: linear">
${user.name} <Button text="Profile"/>
</Panel>
</Template>
will generate
List<View> Simple({View parent, user}) {
...
}
Furthermore, Simple
will return a list with a single element, an instance of Panel
, since Panel
is the only top-level view.
Nested Templates
you can put one template inside another:
<Template name="Foo1">
<Template name="Foo2">...</Template>
...
</Template>
It will generate one global function, Foo1
and one local function, Foo2
as follows.
List<View> Foo1({parent}) {
List<View Foo2({parent}) {
...
}
...
}
Notice that Foo2
is accessible only inside Foo1
:
<Template name="Foo1">
<View data-foo="Foo2"/> <!-- Wrong! Foo2 is not accessible here -->
<Template name="Foo2">...</Template>
<View data-foo="Foo2"/> <!-- Correct! Foo2 is accessible here -->
</Template>
<Template name="Foo3">
<View data-foo="Foo2"/> <!-- Wrong! Foo2 is not accessible here -->
<View data-foo="Foo1"/> <!-- Correct! Foo1 is accessible here -->
</Template>
args: beforeChild
By default, the created views will be appended to the given parent if any. If you prefer to allow the caller to control whether to insert, you can specify beforeChild
as one of your arguments. For example,
<Tempalte name="Foo" args="beforeChild, whatever">
...
Then, the caller can pass a child as beforeChild
such that all created views will be inserted before it:
Foo(parent: parent, beforeChild: refChild);
Since
beforeChild
is interpreted specially, you can use it for other purposes.