Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

rich-component

1.6.0 • Public • Published

GitHub npm Travis Codecov Codacy

Summary

rich-component provides a set of means to easily manage WebComponents with HTML template.

Terms component and custom element are 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.

It helps order and cleanness freaks like myself to separate easily the HTML/CSS from the JavaScript.

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-component is 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-component requires minimalistic effort - it's not binding you to anything
  • when template needs to be fetched over the network, the custom element definition 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.

Last versions (full changelog is here)

  • 1.6.0

    • updated dependencies versions
    • adjusted the repo and the dist to the better practice (dist is not committed but published only)
  • 1.3.0

    • implemented issue #4 - added domType component's property support to allow adding the template's DOM as light rather then shadow
  • 1.2.0

    • implemented issue #2 - getTemplate is part of the ComponentBase, still not documented
    • implemented issue #3 - template getter may now provide a function to resolve the template dynamically
    • added docs and tests

Usage

The workflow is ultimately simple:

  • import rich-component's API
  • define your component's class extending library's ComponentBase class, which extends HTMLElement
  • part of your class implementation should include a template for your custom element (see API documentation for the details)

Example. Let's assume that we build a complex component, willing to externalize the HTML (with CSS) part out of JavaScript code.

Thus we have the markup in, say, my-element.html file. Its content may look like this (abbreviated):

<style>
  :host { ... }
  
  .content { ... }
</style> 
 
<div class="header"></div>
<div class="content"></div>
<div class="footer"></div>

Now we can define the my-element component in the my-element.js, assuming its location beside the my-element.html file above:

import { initComponent, ComponentBase } from './dist/rich-component.min.js';
...
 
initComponent('my-element', class extends ComponentBase {
 
  ...
 
  static get htmlUrl() {
        return import.meta.url.replace(/js$/, 'html');
    }
});

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 template element.

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 fetchTemplate API.

Using the rich-component with '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-component at all in such a cases, but fall-back to the native API.

Detailed API is here.

Install

npm i rich-component

DownloadsWeekly Downloads

96

Version

1.6.0

License

MIT

Unpacked Size

14 kB

Total Files

5

Last publish

Collaborators

  • avatar