View component
Library for building user interfaces with smart event system, strict component props and clear way of defining view hierarchy. Works great with server side rendered html. Weighs around 3.7 KB.
Designed to be versatile for small widgets and complete web applications. Best companion of server rendered applications where frameworks like Vue and React are difficult to adopt. Requires no build setup and can be easily integrated to existing project. Supports all browsers that are ES5-compliant (IE8 and below are not supported).
Features
- delegated event listeners with automatic cleanup
- one time event listeners for lazy loading anything
- props definition and validation with simple schema setup
- publish and subscribe api for component to component communication
- hierarchy api for mapping child views to parent view html tree
- extending api for sub-classing components with prototype and static properties
- mixins for sharing reusable functionality across components
npm install view-component --save
Examples
Dropdown component with toggle UI
Component html:
...
Component javascript:
// define Dropdown componentvar Dropdown = ViewComponent; // create dropdown instanceel: '.dropdown';
List component with view tree
Component html:
... ...
// define List item componentvar ListItem = ViewComponent; // define List componentvar List = ViewComponent; // create list instanceel: 'ul';
Api and options
ViewComponent.extend(prototypeProperties, [staticProperties])
Used to define view types / constructor functions. Define prototype methods for view via object hash. Static properties are optional.
var View = ViewComponent; // prototype method call; // static method callView;
Subclassing components:
var Animal = ViewComponent; var Dog = Animal; var Cat = Animal;
mixins: Array
Used to inject reusable functionality into components. Mixins can contain hooks (initialize, beforeRemove and afterRemove), events, and prototype properties. Multiple mixins can be attached to component.
var dropdownMixin = { console; } events: 'click .dropdown': 'toggle' { thiselclassList ? this : this ; } { thiselclassList; } { thiselclassList; }; var View = ViewComponent; ; // outputs "Dropdown mixin inside"
props: object
Validate component props. Set expectations for valid property types. Mark properties as required and provide default values. Custom validation logic can also be used when simple type checks are not enough.
ViewComponent;
initialize()
Method / hook called on view bootstrap.
var View = ViewComponent;
beforeRemove()
Method / hook called before view removal.
var View = ViewComponent;
events: object | function
Declare events with object hash or custom function. Event delegation is used so there is no need to rebind events when view html content is updated (with ajax or otherwise). All declared listeners are removed when view is removed.
// with object definitionViewComponent;// with function definitionViewComponent;
addDismissListener(listener)
When escape key is pressed or element outside view is clicked listener will be called.
var dismissListener = ; ViewComponent;
removeDismissListener(listener)
Remove dismiss listener.
mapView(selector, View, [props])
Create View instance with first html element inside current view found via selector. Returns mapped instance. Optional component props can be set as object or function returning object.
var Controller = ViewComponent; var MainHeader = ViewComponent; el: 'body';
View components can be lazyloaded via view provider function which will be executed only if element is found via selector. mapView will return promise which resolves to view intance (if element is found) or undefined if not. Requires promise browser support or polyfill.
ViewComponent;
mapViews(selector, View, [props])
Map View instances to all elements inside current view found via selector. Returns mapped instances array. Optional component props can be set as object or function returning object.
... ...
// define List componentvar List = ViewComponent; // define List item componentvar ListItem = ViewComponent; // create list instanceel: 'ul';
View components can be lazyloaded via view provider function which will be executed only if elements are found via selector. mapViews will return promise which resolves to view intances array (if elements are found) or empty array if not. Requires promise browser support or polyfill.
ViewComponent;
addView(viewInstance)
Adds view instance to sub view registry. This binding enables effective cleanup of view hierarchy.
ViewComponent;
trigger(eventName, [data])
Trigger custom event and optionally provide data to handler callback.
ViewComponent;
on(eventName, callback)
Subscribe to custom view events
ViewComponent;
once(eventName, callback)
Subscribe to one time custom view events
ViewComponent;
off([eventName, [callback]])
Removes listeners to custom view events.
ViewComponent;
listenTo(publisher, eventName, callback)
Listen to other object events.
ViewComponent;
listenToOnce(publisher, eventName, callback)
Listen to other object events one time.
ViewComponent;
stopListening([publisher, [eventName, [callback]]])
Removes listeners to custom publisher events.
ViewComponent;
find(selector)
Returns single html element found via selector inside current component element context.
ViewComponent;
findAll(selector)
Returns array of html elements found via selector inside current component element context.
ViewComponent;
validateData(schema, obj)
Validate object properties against schema (identical to props validation)
removeViews()
Removes all registered sub views (added with mapView, mapViews and addView methods).
remove()
Removes view from DOM and does cleanup of all bound events.
Installation
View component is packaged as UMD library and can be used in client and server environments.
// install via npmnpm install view-component --save // if you use bundlervar ViewComponent = ; // or use browser globalsvar ViewComponent = windowViewComponent;