base-element
An element authoring library for creating standalone and performant elements.
View this example List element in use with:
Or other examples:
example usage
You can construct your element API however you choose. A way that I prefer is by inheriting prototypes:
var BaseElement = { BaseElement}Bearprototype = Object// Or inherits(Bear, BaseElement)// Or class Bear extends BaseElement
Then build your elements:
Bearprototype { // Create a virtual DOM tree var vtree = this // Call afterRender with your vtree when returning your vtree return this}
Prefer just functions?
If you prefer just functions, an alternative interface is available:
var createElement = // Create an element on a parentvar el = el
data down, events up
DOMs work best (in the opinion of myself and many) when data goes down and event (or actions) go up.
A simple example is a button element that changes when clicked. How it changes is up to the element but what it changes to is up to the user.
This is our Button element:
var BaseElement = { BaseElement}Buttonprototype = Object// Or inherits(Button, BaseElement)// Or class Button extends BaseElement Buttonprototype { var self = this // The "label" data is coming down var vtree = this return this}
and this is the user's implementation, creates a button and on every click it changes to a random number:
var button = button
nested architecture
Elements created using base-element
are intended on being shared and extended
by others. Each element should not require an additional library/framework to
run it or be injected into it in order to be ran. Elements should be standalone.
For example if you create an input-box
element and published on npm:
var BaseElement = { BaseElement}InputBoxprototype = Objectmoduleexports = InputBox InputBoxprototype { // Builds an <input value="{value}: /> return this}
Later yourself or another user can extend input-box
to add functionality on
top, such as email-input
:
var InputBox = { InputBox // When we receive a "changed" event from InputBox, handle it here this}EmailInputprototype = Objectmoduleexports = EmailInput EmailInputprototype { data = data || {} var vtree = this // Return the virtual DOM tree return this}
Both input-box
and email-input
can be ran on their own. When input-box
updates over time, email-input
can stay on a previous version until an upgrade
can be made.
install
npm with browserify, webpack, etc
npm install base-element
var BaseElement = require('base-element')
standalone
- copy/download/etc dist/base-element.js
<script src="base-element.js"></script>
<script>var element = new BaseElement()</script>
api
var element = new BaseElement([attachTo])
attachTo
is a DOM element you want to append to such as document.body
By default, the element will not attach itself to a parent node. This is useful for handling the rendering on your own.
element.send(name[, params...])
Sends an event up with a given name
and params
.
element.addEventListener(name, function)
Register an event listener for a given name:
element
element.afterRender([params...])
This method needs to be called when returning a constructed virtual tree. It will detect if we are at the top of the render tree and perform the DOM diff and patching.
Buttonprototype { var vtree = this return this}
element.html(tag[, options], value)
A convenience wrapper for creating virtual-hyperscript nodes, i.e.:
var h = var vtree = // is the same asvar vtree = this
element.toString([data...])
For rendering your element as a string of HTML. data
is any initial data
passed to your render
function.
element.element
The root DOM node the virtual tree resides on.
element.vtree
The current virtual DOM tree of the base element.
default events
load
and unload
events will be sent by default if your top level element
registers this
as it's properties:
var BaseElement = { BaseElement this this}Buttonprototype { // The top level element is provided with `this`, events will be fired return this}
license
(c) 2015 Kyle Robinson Young. MIT License