# Getting Started

Note: This is a pino in-house module!

For basic usage, just make sure that your application frontend is able to download piweb, import it in your HTML and use
its components (find available ones in `./components`):

    <script type="module" src=".../piweb/index.js"></script>
    ...
    <piweb-rating></piweb-rating>

Usage inside scripts:

    import * as piweb from ".../piweb/index.js";
    ...
    await piweb.conversation.messageDialog({ message: "Hi!" });

Some features require 3rd party modules (component documentation will then mention that fact).
If you use them, unpack relevant parts of `./3rdparty.tar.gz` into `./3rdparty`.
In either case, you should remove `./3rdparty.tar.gz`.
PiGet will be fine with all of that.

# Custom Components

Custom components should be derived from `PiwebElement` instead of `HTMLElement`. The former one is just a thin layer
around the latter one, but it provides a slightly friendlier API, with less boilerplate code. It also improves stuff
like styling consistency (see chapter below).

The implementation of a simple custom component could look like this:

    import * as piweb from "../piweb/index.js";

    export class Foo extends piweb.PiwebElement {
        static templateHTML = `
            <div id="box"></div>
        `;

        static properties = {
            "text": piweb.property({
                setter: function (value) { this.shadowRoot.querySelector("#box").textContent = value; },
            }),
        };

        registerEventHandlers() {
            // arbitrary initialization stuff here, like adding event listeners to some internal elements
        }

        /**
        * The foo text.
        */
        get text() {}
        set text(v) {}
    }

    customElements.define("myapp-foo", Foo);

Note that the `text` property getter and setter have empty bodies. At runtime, they are automatically generated based on 
the defined properties - even if you do not define them at all. The class definition only keeps stubs for them in order 
to make properties known to the IDE.

# Styling

There is only a minimal amount of styling included in piweb.

In general, styling is done by means of the `::part()` selector, like this:

    ::part(piweb-tab-bar) { ... }

For a complete stylesheet template to use for customization, copy the content of that variable (or parts of it) to the
application's stylesheet:

    (await import(".../piweb/index.js")).styling.defaultPartsCss

Custom web components that internally use piweb components but are NOT derived from `PiwebElement` (see below) should 
export all these parts (`exportedparts` html attribute).

Any web component, no matter whether it is derived from `HTMLElement` or `PiwebElement`, should assign these part names
to internal elements (e.g. buttons) as appropriate.
