Component Template Arguments and Parameters

Default argument

A component can receive DOM arguments by declaring them as child nodes of its element. By default all inner DOM nodes of the component element are regarded as a single argument:

<div data-montage-id="list">
    <span data-montage-id="name">Name</span>
    <span data-montage-id="address">Address</span>
</div>

In this example the list component has a single argument with the two span nodes:

<span data-montage-id="name">Name</span>
<span data-montage-id="address">Address</span>

We call the default single argument the star (*) argument (as in wildcard). This is the easiest way to pass a DOM argument to a component as it is the natural way to do composition in HTML.

Multiple Arguments

A single argument works in most simple cases but for more complex components it is desirable to receive more than one argument. Multiple arguments need to have names associated with each one, the argument names are declared with a data-arg attribute.

Let's take the List from the previous example and imagine that we also want to receive a header to insert before the items.

<div data-montage-id="list">
    <h1 data-arg="header" data-montage-id="header">Header</h1>
    <div data-arg="item">
        <span data-montage-id="name">Name</span>
        <span data-montage-id="address">Address</span>
    </div>
</div>

The List now receives two arguments, the header and the item.

Accessing the arguments

The arguments of a component are available to the component at the time of the first enterDocument() call. There are two functions to work with the arguments:

• getDomArgumentNames() returns an array with the names of the arguments. In the first example with the default argument this function returns ["*"]. In the second example with multiple arguments this function returns ["header", "item"].

• extractDomArgument(name) returns the DOM node corresponding to the argument. In the first example with the default argument this function returns [<span data-montage-id="name"...>, <span data-montage-id="address"...>] for extractDomArgument("*"). In the second example with multiple arguments this function returns <h1 data-arg="header"...> for extractDomArgument("header"). The elements returned are removed from the DOM document.

The arguments can be manipulated at will by the component, but the most common usage is to insert them into specific parts of the component's template. To automate this task the templates have the concept of template parameters.

Template Parameters

Template parameters allows a component to define slots in its template to be filled with the template arguments that the component received.

We call this Dynamic Component Composition. It is component composition where not all the pieces are known when developing the component.

An example of this is the List. The List needs to repeat some kind of content that it does not know about, it's up to whoever is using the List to define this content and pass it to the list. In this sense each list object might repeat completely different things, it needs to be dynamically defined.

The "slots" in the template are defined with the data-param attribute with the name of the desired argument to be replaced in. These elements will be replaced at runtime by the element with the respective data-arg attribute, or elements in the case of the star (*) argument. Using the List as an example, its template can be defined with:

<div data-montage-id="owner">
    <div data-montage-id="repetition">
        <div data-param="*"></div>
    </div>
</div>

This is the simple case of using the entire contents of the component element. If the component receives more than one argument, for instance, if the List also receives a header argument to be placed just before the repeated elements, and accepts the content to be repeated as the item argument then we just add aditional data-param's.

<div data-montage-id="owner">
    <div data-param="header"></div>
    <div data-montage-id="repetition">
        <div data-param="item"></div>
    </div>
</div>

How it looks like when rendered

Using the previous examples of the list let's see how they will be rendered when the parameters are replaced with the arguments:

Default argument

Template

<div data-montage-id="list">
    <span data-montage-id="name">Name</span>
    <span data-montage-id="address">Address</span>
</div>

Rendered

<div data-montage-id="list">
    <div data-montage-id="repetition">
        <span data-montage-id="name">Name</span>
        <span data-montage-id="address">Address</span>
    </div>
</div>

Multiple arguments

Template

<div data-montage-id="list">
    <h1 data-arg="header" data-montage-id="header">Header</h1>
    <div data-arg="item">
        <span data-montage-id="name">Name</span>
        <span data-montage-id="address">Address</span>
    </div>
</div>

Rendered

<div data-montage-id="list">
    <h1 data-montage-id="header">Header</h1>
    <div data-montage-id="repetition">
        <div>
            <span data-montage-id="name">Name</span>
            <span data-montage-id="address">Address</span>
        </div>
    </div>
</div>