rich-component provides a set of means to easily manage WebComponents with HTML template.
custom elementare used interchangeably here.
Its call is to fill up some functional gap when there is a need to conveniently manage HTML template for Web Component.
Myself took it as a best practice to separate those for better readability, Dev tools support (when HTML/CSS mixed into JS their support usually becomes very limited, if any) and future extensibility easiness. It is only when I'm absolutely sure, that the component will stay small and simple, I'm inlining the template, and even then I'm half hearted.
rich-component ensures that template for your custom element is provided correctly, fetches/caches the templates when needed and finally injects the templated
HTML into the
shadowRoot of each newly created component instance.
Few points to stress:
rich-componentis very small in itself and has very narrow defined functionality, it's more like a utility or a micro-framework, than a full blown beast
- simplicity is one of the primary things the author concerned with
- APIs designed to second the native component definition APis, so migration to & from
rich-componentrequires minimalistic effort - it's not binding you to anything
- when template needs to be fetched over the network, the
custom elementdefinition postponed to that, thus making the component available to the application only when ready to use
- template's content defaultly added as an open shadow DOM to the component instance; it is possible to override this and add it as a light DOM.
Customized built-in elements are not yet supported, will extend the library upon first such a use-case.
here)Last versions (full changelog is
- updated dependencies versions
- adjusted the repo and the dist to the better practice (dist is not committed but published only)
- implemented issue #4 - added
domTypecomponent's property support to allow adding the template's DOM as
- implemented issue #4 - added
The workflow is ultimately simple:
- define your
component's class extending library's
ComponentBaseclass, which extends
- part of your class implementation should include a template for your
custom element(see API documentation for the details)
Thus we have the markup in, say,
my-element.html file. Its content may look like this (abbreviated):
Now we can define the
my-element component in the
my-element.js, assuming its location beside the
my-element.html file above:
Of course, URL of HTML may be given any other way, even hardcoded, but I've found myself typically using the above pattern, which makes my components look uniformly.
Having the code as above,
rich-component will first ensure that you have a properly defined template source, failing as fast as possible. It will then fetch the template and cache it during initialization. It will inject the above HTML into the
shadowRoot each time
my-element is constructed.
Example above provides component's template via
htmlUrl getter pointing to an external HTML/CSS resource.
If the component has relatively small HTML part, one can provide an 'inline' template by
template getter, which looks very similar to the
htmlUrl, but is expected to return already crafted
Another use case for the
template API flavor is a need to dynamically preprocess the fetched template if, for example, it is shared between few slightly different components.
For such a cases
rich-component exports an otherwise internal
rich-componentwith 'inline' templates may still be convenient and provide some kind of a future proofness, making it an easy task to externalize HTML/CSS part when overgrown. Yet, IMHO it would also be perfectly right to not use
rich-componentat all in such a cases, but fall-back to the native API.
Detailed API is here.