fwebc.js

Toy framework for learning web components
git clone git://git.finwo.net/lib/fwebc.js
Log | Files | Refs | README

README.md (2640B)

      1 # fwebc
      2 
      3 Simple web component framework to teach myself about web components
      4 
      5 ## Install
      6 
      7 This package is intended for direct use in the browser, although wrappers like
      8 browserify and/or webpack *should* work.
      9 
     10 ```js
     11 npm install --save fwebc
     12 ```
     13 
     14 ```html
     15 <script src="https://unpkg.com/fwebc"></script>
     16 ```
     17 
     18 Upon load, fwebc returns within `module.exports` if support for that is
     19 detected, else it attaches itself to `window.fwebc`.
     20 
     21 ## Usage
     22 
     23 fwebc makes use of `window.customElements`, so initialization is not needed,
     24 only configuration.
     25 
     26 ### fwebc.cfg( configuration? )
     27 
     28 For now, only the default file extension and the base uri (location to your
     29 templates) are configurable.
     30 
     31 ```js
     32 fwebc.cfg({
     33   ext : 'tag',
     34   base: '/partial',
     35 });
     36 ```
     37 
     38 ### fwebc.install( callback:fn &lt;component&gt; )
     39 
     40 Adds a callback to the creation process of an element. The shadow root (a.k.a.
     41 component) is given as the first -and only- argument to the callback.
     42 
     43 This functionality allows you to add mixins or other features to components.
     44 
     45 ### fwebc.uninstall( callback )
     46 
     47 When given the exact same callback as you installed, removes it from the calls
     48 to perform upon component creation.
     49 
     50 ### fwebc.register(name, source)
     51 
     52 Registers a new component, based on the source string you give. The name must
     53 include a hyphen `-` because fwebc is built directly on top of
     54 `window.customElements`.
     55 
     56 **CAUTION**: this method will **NOT** throw an error if a name has already been
     57 registered.
     58 
     59 ### fwebc.load(name)
     60 
     61 Loads the template identified by the given name, surrounded by the configured
     62 `base` and `ext`, and registers it.
     63 
     64 ### component.render()
     65 
     66 Re-renders the component the function is called on as a template literal, using
     67 `component.state` as it's data input.
     68 
     69 ## Templates
     70 
     71 Loaded templates are attached to elements as shadow roots after being rendered
     72 as template literals using your template's `.state` property as data input.
     73 Top-level script tags are all merged together and are used as the initialization
     74 code for your custom element (`this` = the element, `.root` = shadow root).
     75 
     76 Basic data-binding is supported. In your template, during initialization (so in
     77 the root of your scripts), you're allowed to overwrite the `this.state`
     78 property. Do **NOT** overwrite this property after initialization or the binding
     79 will cease to work. The template will be re-rendered whenever your state
     80 updates.
     81 
     82 More advanced data-binding can be added by including a package like
     83 [rivets](https://www.npmjs.com/package/rivets) and installing it like a plugin
     84 as follows:
     85 
     86 ```js
     87 fwebc.install(component => {
     88   rivets.bind(component.root, component.state);
     89 });
     90 ```