Template

Clones a <template> part and fills it with data that doesn't exist when the server renders the page.

Use it for anything the client adds after hydration: async search results, previews of uploaded files, or the rows of a recurring field. The markup of the item stays in your Fluid template, so it is styled and translated like the rest of the component.

Usage

Declare the <template> with ui:template inside the component. It needs exactly one root element:

<ui:combobox.list>
    <ui:template name="itemTemplate" context="combobox">
        <ui:combobox.item>
            <ui:combobox.itemText>
                <span {ui:ref(name: 'title')}></span>
            </ui:combobox.itemText>
        </ui:combobox.item>
    </ui:template>
</ui:combobox.list>

Then clone it from the component with its hydrator, fill it and insert it:

import { Template } from 'fluid-primitives';

for (const { value, title } of cities) {
    const instance = new Template(combobox.hydrator, 'itemTemplate', { value });

    const titleEl = instance.query<HTMLElement>('title');
    if (titleEl) titleEl.textContent = title;

    listEl.appendChild(instance);
}

instance is a DocumentFragment, so it can be appended as it is. instance.root keeps pointing at the item after the insertion has emptied the fragment.

With value the clone represents one real item: data-value is set on it and on the parts inside it that exist once per item, and independent components inside it, such as a Field with an Input, are prepared. Call the mountAll() of each name in instance.componentNames after you insert the clone.

Options

The options of a Template.

Name	Description	Required	Default
`value`	`string` Makes the clone represent one real item: sets `data-value` on its root and on every part inside it that exists once per item, and prepares independent root components inside it, such as a `Field` with an `Input`, so `mountAll()` can mount them. Leave it out for a template without a per-item value.	No	-
`attributes`	`Record<string, boolean \| string>` Data attributes to set next to `value`, on the same elements. A boolean toggles a bare `data-x` attribute, `{ disabled: true }` sets `data-disabled` and `false` removes it. A string sets `data-x="value"`. Only has an effect together with `value`.	No	-

API

Clones the content of a <template> part, which must have exactly one root element, and throws otherwise. It is a DocumentFragment, so you can append it directly: root stays a valid reference to the element after the fragment has been emptied by the insertion.

It works for any "clone a <template> and fill it with data that doesn't exist at server render time" case, such as async search results, file upload previews or the rows of a FieldArray.

class Template extends DocumentFragment

Constructor

Name	Description	Required	Default
`hydrator`	`ComponentHydrator` The hydrator of the component that owns the `<template>`.	Yes	-
`part`	`string` The name of the `<template>` part.	Yes	-
`options`	`TemplateOptions` See `TemplateOptions`.	No	{}

Properties

Name	Description
`root`	`HTMLElement` The one root element of the clone.
`componentNames`	`string[]` The client names of the independent root components found inside the clone, empty without `options.value` or when there are none. Call their `mountAll()` after you insert the clone into the document.

Methods

query()

Finds the first element of part inside the clone.

query<T extends Element = HTMLElement>(part: string): T | null

Name	Description	Required	Default
`part`	`string`	Yes	-

queryAll()

Finds every element of part inside the clone.

queryAll<T extends Element = HTMLElement>(part: string): T[]

Name	Description	Required	Default
`part`	`string`	Yes	-