Hierarchy of components

This guide helps you build your own interface from scratch.

The main purpose of the @labirthermal/webcomponents library is to work with multiple files at once. For that reason, there is an obligatory hierarchy of webcomponents.

• a) context providers expose internal control objects
• b) context consumers inherit the controls from their parents

Context providers

When building an interface from scratch, you will need to use all the following context provider elements:

• manager-provider
• registry-provider
• group-provider
• file-provider

See the manager-provider, registry-provider, group-provider, and file-provider references for details about each provider.

The following schema explains their roles:

The manager-provider handles the global cache and also some display properties such as the palette property.

The registry-provider handles file loading, thermal range and histogram.

The group-provider synchronises the cursor position between the nested files.

The file-providerexecutes the file load and exposes its properties in as context.

The file-providerexecutes the file load and exposes its properties in as context.

If the context providers are missing or composed incorrectly, the context consumers won't work.

Internal hierarchy

Every context provider is bound internally to an object within the hierarchy of @labirthermal/core:

context provider webcomponent	corresponding `@labirthermal/core` class
manager-provider	ThermalManager
registry-provider	ThermalRegistry
group-provider	ThermalGroup
file-provider	ThermalFileInstance

Therefore, the hierarchy of context providers will create a tree of @labirthermal/core internal objects.

<manager-provider>
    <registry-provider>
        <group-provider>
            <file-provider></file-provider>
        </group-provider>
    </registry-provider>
</manager-provider>

ThermalManager
⮑ ThermalRegistry
    ⮑ ThermalGroup
        ⮑ ThermalFileInstance

What do the context providers do with their internal control objects?

• expose internal objects as lit context which is then consumed by context consumers
• translate the internal state to HTML attributes and translate internal properties into HTML attributes.

Identity of internal objects

Every internal object is identified by a unique identificator. By default, identificators are random hashes. But you can optionally specify the internal names using *-slug attributes:

<manager-provider manager-slug="default">
    
    <registry-provider registry-slug="some-id">

        <group-provider group-slug="first-group-id"></group-provider>

    </registry-provider>

</manager-provider>

The example above will create this internal hierarchy:

ThermalManager #default
⮑ ThermalRegistry #some-id
    ⮑ ThermalGroup #first-group-id

Sharing internal objects

If you use the same identificator for multiple context providers, they will share one internal object.

<manager-provider manager-slug="default">
    
    <registry-provider registry-slug="some-id">
        <group-provider group-slug="first-group-id"></group-provider>
    </registry-provider>

    <registry-provider registry-slug="some-id">
        <group-provider group-slug="second-group-id"></group-provider>
    </registry-provider>

</manager-provider>

The example above will create this internal hierarchy:

ThermalManager #default
⮑ ThermalRegistry #some-id
    ⮑ ThermalGroup #first-group-id
    ⮑ ThermalGroup #second-group-id

This is practical if you want to display one internal context in two branches of the DOM tree.

The example below shows two registry-providers that control one internal context.

• The first instance of registry-provider contains a group and loads a file.
• The other instance of registry provider contains some control elements.

By sharing the registry-slug attribute, both branches in the DOM tree share one control object and therefore their internal attributes are synchronised.

Try to play with the controls below - they will modify the thermal range also in the DOM tree above.

You do not need to provide identificators - in case the *-slug attributes are empty, internal IDs will be random hashes.

Context consumers

Once the main hierarchy is created, you can add context consumer elements inside.

The context consumer elements inherit the control objects from their ancestors and use it to display and modify internal states.

The context consumers may be nested anywhere in the DOM tree, but they still share the same context. The following example shows that multiple manager-palette-dropdown elements can be placed anywhere in the DOM tree while still controlling the same context;

Applications

Applications such as thermal-file-app create their own manager, registry, group and file context. You do not need to wrap them in provider elements.

The example below loads the same thermal file and visible image in two independent viewers with the same initial settings:

• Left: each provider exposes the attributes belonging to its own context.
• Right: one application exposes those attributes together, on the same HTML element. The internal objects still follow the manager → registry → group → file hierarchy; only the HTML API is flat.

Click an attribute value in either HTML label to edit it, or use the controls and watch the values update. The viewers are independent, so changes in one do not affect the other. thermal loads the file together with visible; changing only visible does not reload it.

Separate providers

Create context hierarchically.

All providers in one application

*-app webcomponents do not use context providers. Instead, they expose the entire context on their own. These webcomponents also comes with a fully-featured UI.

The essential HTML difference is:

<manager-provider palette="iron">
    <registry-provider from="-10" to="5" opacity="0.6">
        <group-provider>
            <file-provider
                visible="/files/les_visual.png"
                thermal="/files/les_thermal.lrc"
            >
                <file-canvas></file-canvas>
            </file-provider>
        </group-provider>
    </registry-provider>
</manager-provider>

<thermal-file-app
    palette="iron"
    from="-10"
    to="5"
    opacity="0.6"
    visible="/files/les_visual.png"
    thermal="/files/les_thermal.lrc"
></thermal-file-app>

The application also supplies its own controls, canvas and analysis interface. See the application reference for all public attributes.