Template Limitations

The framework considers any attribute other than theme or one of the HTML 5 global attributes for server-side initialization. However, if the attribute value is not a constant, that is, it contains bindings such as ${…} and {{…}}, it is not parsed and the property is not initialized on the server side. Only attributes are parsed. Properties defined by nested elements, such as grid columns and items, are not parsed from the template but must be initialized on the server side.
You can add components and elements to a template structure, but you cannot remove anything present in the original template. However, overriding component properties is possible.
For LitTemplate, you cannot configure the column renderers for Grid, TreeGrid or GridPro in HTML. The column configuration and driving of data needs to happen from Java to the @Id-mapped component. LitTemplate differs from PolymerTemplate in this regard.
Calling setText() from Java on a template-based component causes the removal of child elements. For example, if the template is <div id="myDiv">Some text<vaadin-button id="myButton">My Button</vaadin-button></div>, calling myDiv.setText() causes the myButton element to be removed. To keep children, instead wrap the text content in a separate child alongside myButton, and call setText() on that element: <div id="myDiv"><span id="myTest">Some text</span><vaadin-button id="myButton">My Button</vaadin-button></div>.

Out-of-Sync Methods

Example: MainPage JavaScript Polymer template file.

class MainPage extends LitElement {

    render() {
        return html`
            <div id="header">Main page</div>
            <div id="content"></div>
            <hr>
            <div id="footer">
                <a href="mailto:someone@example.com?Subject=Hello" target="_top">Send Mail</a>
            </div>`;
    }
}

customElements.define("main-page", MainPage);

Example: Mapped Java template class.

@Tag("main-page")
@JsModule("./com/example/main-page.js")
public class MainPage extends LitTemplate {

    @Id("content")
    private Div content;

    public void setContent(Component content) {
        this.content.removeAll();
        this.content.add(content);
    }
}

In the previous template class example, you could additionally map the div element with a "footer" identifier using the Div component and @Id("footer") annotation. However, the hierarchical structure will not be available on the server side using the Java API.

The injected Div instance does not have a server-side child, even though the a (anchor) element is available on the client side. The getChildren() method in the injected instance returns an empty Stream. Similarly, the getText() method of the Div instance injected using the @Id("header") annotation returns an empty string.

To summarize:

Server-side Component or Element read methods are not always in sync with the client side.
You can still use mutation API methods, such as appendChild(), setProperty() or setAttribute() from the server side, without issues.
Getter methods return values that are set from the server side only.

Enabled State

Since the hierarchical structure in the template is not reflected on the server side, the setEnabled() method called on an @Id injected component does not disable any other @Id injected component, even though such a component may be a descendant in the shadow DOM. (See also Component Enabled State).

Example: Disable an @Id injected component.

@Tag("main-layout")
@JsModule("./com/example/main-layout.js")
public class MainLayout extends LitTemplate {

    @Id("layout")
    private VerticalLayout layout;
    @Id("textfield")
    private TextField textField;
    @Id("button")
    private Button button;

    public void onSomeAction() {
        layout.setEnabled(false);

        System.out.println(textField.isEnabled()); // prints "true"
        System.out.println(button.isEnabled()); // prints "true"
        // call explicitly setEnabled(false) to disable a component
        button.setEnabled(false);
        System.out.println(button.isEnabled()); // prints "false"
    }
}

class MainLayout extends LitElement {

    render() {
        return html`
           <div>
             <vaadin-vertical-layout id="layout">
               <vaadin-text-field id="textfield"></vaadin-text-field>
               <vaadin-button id="button"></vaadin-button>
             </vaadin-vertical-layout>
            </div>`;
    }
}

customElements.define("main-layout", MainLayout);

Template Disabled Attribute

LitTemplate does not support using the disabled attribute for an id-mapped component and throws an IllegalAttributeException with information on where it is used. Id-mapped components should always be disabled from the server side using the setEnabled(false) method.

Faulty sample

class MainLayout extends LitElement {
 render() {
   return html`
       <div>
         <vaadin-button id="button" disabled></vaadin-button>
       </div>
     `;
 }
}

customElements.define("main-layout", MainLayout);

@Tag("main-layout")
@JsModule("./com/example/main-layout.js")
public class MainLayout extends LitTemplate {

   @Id("button")
   private Button button;
}

This throws an IllegalAttributeException with the message:

Lit template 'com.example.MainLayout' injected element 'vaadin-button' with id 'button' uses the disabled attribute.
Mapped components should instead be disabled using the 'setEnabled(false)' method on the server side.

Note	PolymerTemplate does not throw an exception for using the `disabled` attribute, but only stores it as a property of the element, leaving the element enabled on the server side.

Removing Mapped Elements

A virtually mapped Element is connected to the ShadowRoot of the LitTemplate, even if it actually resides deeper in the shadow tree. You cannot remove virtually mapped components from the DOM by removing them on the server side.

Note	You can detect whether a component is used in a `LitTemplate` by using the `isTemplateMapped()` method. See the Detecting Component Mappings for more.

Note	The same limitations apply to Polymer template classes.

CDBCA1D4-E735-4258-9AB6-3BE9C36482A9

Documentation