Auto-Initialization from DOM

Qite does not create components manually. It scans the DOM and instantiates components automatically based on data-component attributes.

This is triggered by calling:

Qite.init(root_element);

where root_element defines the subtree that will be scanned. This line should typically appear last in your init.js file, after you import all components you're going to be using.

What Qite.init() actually does

When Qite.init(root_element) is called, Qite:

Walks the DOM subtree starting at root_element
Finds every element that has data-component
Looks up the corresponding class in Qite.components
Creates a ComponentDomTreeNode for that element.
Instantiates the component with new ComponentClass(tree_node)
Builds the component hierarchy (parent / children).
Resolves mounted for each component.

All of this happens synchronously.

Hierarchy is built after instantiation

During scanning, components are created first.

After all component instances exist, Qite links them together into a tree:

component.parent
component.children

Only once this structure is complete does Qite resolve each component’s mounted promise.

This guarantees that when mounted resolves:

The component knows its parent.
Its children array is populated.
Event subscriptions between parent and child are active.

Nested components

Consider this structure:

<div data-component="Parent">
    <div data-component="Child"></div>
</div>

When Qite scans this subtree:

A ParentComponent instance is created.
A ChildComponent instance is created.
ChildComponent.parent is set to ParentComponent instance.
ParentComponent.children includes ChildComponent instance.

The component hierarchy mirrors the DOM structure, but only for elements that have data-component. For example, this HTML structure:

<div data-component="Parent">
    <div class="children-wrapper">
      <div data-component="Child"></div>
    </div>
</div>

still results in ParentComponent instance having ChildComponent instance as a child.

Missing component classes

If Qite encounters:

<div data-component="DoesNotExist"></div>

and Qite.components.DoesNotExist is not defined, it throws ComponentClassNotFound. Component registration must (and does) happen before Qite.init() is called.

If you dynamically insert HTML that contains data-component, Qite will not automatically detect it. You shouldn't want to do that, however, because you normally move components from one parent to another by calling Component.addChild() or, alternatively, you may create a completely new component with Component.create({ parent, template_name }={})

Scanning proceeds in DOM order and parents are created before their nested children in traversal order, but hierarchy linking happens after instantiation of the full subtree.

You should not assume parent-child wiring is complete inside the constructor. Use this.mounted.then(...) if you depend on the final hierarchy.

What to read next

Now that you understand how components are created from DOM, the next page explains how Qite instantiates components from <template> elements.