@converse/skeletor 0.0.5 → 0.0.6

package/README.md

@@ -1,16 +1,27 @@
 # Skeletor
 
-[![XMPP Chat](https://inverse.chat/badge.svg?room=discuss@conference.conversejs.org)](https://inverse.chat/#converse/room?jid=discuss@conference.conversejs.org)
+[![XMPP Chat](https://conference.conversejs.org/muc_badge/discuss@conference.conversejs.org)](https://inverse.chat/#converse/room?jid=discuss@conference.conversejs.org)
 [![Travis](https://api.travis-ci.org/conversejs/skeletor.png?branch=master)](https://travis-ci.org/conversejs/skeletor)
 
-Skeletor is a [Backbone](http://backbonejs.org) fork.
+Skeletor is a [Backbone](http://backbonejs.org) fork that adds various improvements and features.
 
-Its goal is to modernize and componentize Backbone.
+## Introduction
 
-Original Backbone Views can't be rendered in a nested and declarative way,
-similarly to how components are rendered in React and other frameworks.
+The goal of Skeletor is to modernize Backbone and to allow you to stop
+writing imperative view code (e.g. manually adding and removing DOM nodes)
+and instead start writing declarative, component-based code that automatically
+updates only the changed parts of the DOM, similarly to basically all modern
+JavaScript frameworks.
 
-We can solve this by making Views web components. Check out the `ElementView` class, which does this.
+The original Backbone Views aren't components can't be rendered in a nested and
+declarative way. Instead, it's up to you to manually make sure that these views
+are rendered in the correct place in the DOM. This approach becomes unwieldy,
+difficult and fragile as your site becomes larger and more complex.
+
+Skeletor solves this by creating a new type of View, called `ElementView`,
+which is very similar to the original Backbone `View` but which is also a web
+component that gets instantiated automatically as soon as its rendered in the
+DOM.
 
 ## Why bother?
 
@@ -18,7 +29,7 @@ The goal of this fork is to allow the Converse team to gradually update the [Con
 XMPP webchat client to use web components (using [LitElement](https://lit-element.polymer-project.org/))
 without requiring us to put everything on hold in order to do a massive rewrite.
 
-The end-goal is to not have any Backbone/Skeletor Views at all, only LitElement components.
+The end-goal is to not have any Skeletor Views at all, only LitElement components.
 
 We can cheat a little by letting the existing Views also be web components
 (more accurately, "custom elements"), this allows us to declaratively render the
@@ -60,3 +71,55 @@ UI, while we're progressively getting rid of the views.
 5. The `partition` and `invokeMap` methods have been removed.
 
 ![](https://raw.githubusercontent.com/conversejs/skeletor/master/images/skeletor3.jpg)
+### ElementView example
+
+The ElementView looks very similar to a normal Backbone View.
+
+Since it's a web component, you need to call `CustomElementRegistry.define` to
+register it.
+
+The `this` variable for the ElementView is the custom DOM element itself,
+in this case, `<my-custom-button>`.
+
+So there is no `el` attribute and `this.el` will be undefined. Whereever in a
+Backbone View you'd use `this.el`, with an ElementView you'd just use `this`.
+
+
+```javascript
+
+import { ElementView } from '@converse/skeletor/src/element.js';
+import { render } from 'lit';
+import { html } from 'lit';
+
+export default class MyCustomButton extends ElementView {
+    events = {
+        'click .button': 'onButtonClicked'
+    }
+
+    async initialize () {
+        this.model = new Model({ count: 0 });
+        this.listenTo(this.model, 'change', this.render)
+    }
+
+    render () {
+      return render(html`<button class="button">I've been clicked ${model.get('count')} times!</button>`, this);
+    }
+
+    onButtonClicked () {
+      this.model.save('count', this.model.get('count')+1);
+    }
+}
+
+CustomElementRegistry.define('my-custom-button', MyCustomButton);
+```
+
+You can now put your custom element in the DOM, and once the DOM is loaded by
+the browser, your ElementView will automatically be instantiated and
+`initialize` will be called.
+
+
+```html
+  <div>
+    <my-custom-button></my-custom-button>
+  </div>
+```