virtual-dom-component
v0.2.0
Published
A virtual DOM component (view).
Downloads
3
Readme
virtual-dom-component
A virtual DOM component (view).
Virtual components expose events
, state
, and a render
function.
The state returned by a component acts as a lens meant to be embedded in the "top level" state atom. Component state is not mutated directly. It's a black box mutated by methods exposed on the component.
Events returned by a component are used to communicate with the application or other components. For example, a component may have a "login button pressed" event but no logic for handling login. Instead, another component can listen for this event and mutate state.
These ideas are taken from Raynos' mercury component documentation.
Installation
Using npm:
npm install --save virtual-dom-component
Using bower:
bower install --save alexmingoia/virtual-dom-component
Using browser script tag and global (UMD wrapper):
// Available via window.VirtualComponent
<script src="dist/virtual-dom-component.js"></script>
Usage
Create a component:
var LoginForm = VirtualComponent.extend({
render: function (state) {
return h('form', [
h('input', { name: "username", type: "text" }),
h('input', { name: "password", type: "password" }),
h('button', { type: "submit" })
]);
}
});
var loginForm = LoginForm(); // use of `new` keyword optional
Embed component state in application state:
appState.loginState = loginForm(...).state;
Once embedded call the component's render method:
function appRender (state) {
return h('div', [
loginForm.render(state.loginState);
]);
};
Events
Wire up geval events via the prototype events
array:
var LoginForm = VirtualComponent.extend({
events: ['login'],
render: function (state) { ... }
});
var loginForm = LoginForm();
// listen for event by passing a listener function
loginForm.events.login(function listener (...) { ... });
// emit/broadcast/trigger event by passing a non-function value
loginForm.events.login(value);
Lifecycle
initialize
If an initialize
function is provided it will be called with the constructor
arguments when components are created.
var LoginForm = VirtualComponent.extend({
initialize: function(options) {
console.log(options.foo) // => "bar"
}
});
var loginForm = new LoginForm({ foo: "bar" });
Extending
Extend the component by passing additional properties or methods:
var LoginForm = VirtualComponent.extend({
validate: function() { ... },
render: function (state) { ... }
});
var loginForm = LoginForm();
loginForm.validate();
Components can have children that inherit from their parent:
var Form = VirtualComponent.extend({
validate: function () { ... },
render: function (state) { ... }
});
var LoginForm = Form.extend({
render: function (state) { ... }
});
var loginForm = LoginForm();
loginForm.validate();
Contributing
Please submit all issues and pull requests to the alexmingoia/virtual-dom-component repository!
Support
If you have any problem or suggestion please open an issue here.
License
The BSD License
Copyright (c) 2014, Alex Mingoia
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Alex Mingoia nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.