bindux
v0.0.1-alpha
Published
Data-binding (like Angular, Ember, ...) + templating + DOM manipulation (like jQuery, jqLite, Zepto, ...). Only 7kb minified and gzipped
Downloads
1
Maintainers
Readme
Bindux - Bind the User eXperience
Powerful and modern data binding (like Angular, Ember, ...) + templating + DOM manipulation (like jQuery, Zepto, jqLite, ...) in only 23kb minified (7kb gzipped).
Bindux in a few words:
- Near of native JS and HTML5 / CSS3.
- DOM manipulation (if you prefer, you can use Bindux with jQuery).
- Native data-binding, Bindux use
Object.observe()
, you can use a polyfill for old browsers. - Some useful helpers to manipulate the DOM, data-binding, values, HTML, ...
- Standart compliant, no need for <%=foo%> or {{foo}} assignments.
- Templating based on HTML, HTML is a great markup langage and natively evaluated by the browser.
- Not brilliant meta language, hieroglyphic or any other symbol to remember. Only HTML we already know.
- DSL-free (Domain Specific Languages), if needed you can use with any template engine.
- Note: DOM templating with Domain Specific Languages (suck as <%=foo%> or {{foo}}) is SLOW. All template engines require parsing and rendering phases.
- Easy to use
- Extensible
This is the alpha version, the documentation is in progress.
Install
Download dist/bindux.min.js.
Usage
Bindux expose the variables bindux
and a shortcut ux
.
// true
console.log(bindux === ux);
bindux.noConflict()
to redefine in your sauce:
var ui = bindux.noConflict();
// now `ui` is `bindux` object
console.log(ui);
// now is undefined
console.log(bindux);
// now is undefined
console.log(ux);
DOM
Documentation in progress, the following is some quick examples:
ux.dom('div').css('color', 'green');
// or jQuery like
var $ = ux.dom;
$('div').css('color', 'green');
Some methods:
var $ = ux.dom;
var elements = $('div');
elements.attr('href', newLink);
elements.html('<b>great</b>');
elements.text('some text');
elements.append('<b>html</b>');
elements.appendText('text');
elements.appendChild(node);
elements.prepend('<b>html</b>');
elements.prependText('text');
elements.prependChild(node);
elements.insertBefore('added before');
elements.insertAfter('added after');
elements.parent();
elements.findParent('.someClass');
elements.addClass('btn-success');
elements.toggleClass('some-class');
elements.show();
elements.hide();
elements.on('click', listener);
elements.off('click', listener);
elements.trigger('click', data);
elements.css({
color: '#333',
// or 'background-color': '#f1f1f1'
backgroundColor: '#f1f1f1'
});
// each node
elements.each(function() {
$(this).next().addClass('selected');
this.remove();
});
Traverse the tree of node
and keep only the text nodes:
var textNodes = $.traverse(node, NodeFilter.SHOW_TEXT);
Observe DOM mutations and bind with the items
object:
var items = {};
$.observe({
// element
el: {
el: $('#list').get(),
observer: function(mutations, observer, context) {
console.log(mutations, observer, context);
}
},
// object
obj: {
obj: items,
observer: function(changes, context) {
console.log(changes, context);
}
}
});
... and more, see the API in the code source.
Binders
TODO: doc
Binders are used to make the link between the JS code and the HTML document. Like the AngularJS directives (ng-repeat, etc).
Each binding is linked by an attribute and an object (named the scope
).
All binding attributes are prefixed by n-
(n = node). You can change the prefix like this:
ux.opt.binder.prefix = 'ux-';
All scopes are stored in ux.scopes
object.
If a property passed from HTML to a binder is a function, then it will be executed and its return value will be used by the binder.
Init the binding with ux.init()
:
// define the controllers of your application
ux.ctrls.header = headerCtrl;
ux.ctrls.navBar = navBarCtrl;
ux.ctrls.chat = chatCtrl;
ux.ctrls.article = articleCtrl;
ux.ctrls.user = userCtrl;
// initialize the binding
ux.init();
ctrl
The controller which manages the scope.
The use of controllers is not mandatory, you can define directly a scope ux.scopes.something
but the controllers are convenient for code organization.
When defining a controller, a scope of the same name is automatically created if it does not exist.
HTML
<div n-ctrl="myCtrl"></div>
JS
/**
* My controller
*
* @param {object} scope The scope to handle.
* @param {Element} el The node element of the controller
*/
ux.ctrls.myCtrl = function(scope, el) {
};
each
Like ng-repeat
of AngularJS, the binder each
instantiates a template once per item from a collection. Each template instance gets its own scope, where the given loop variable is set to the current collection item.
HTML
<div n-ctrl="myCtrl">
<ul>
<li n-each="message messages" n-html="message"></li>
</ul>
</div>
If you prefer the Angular way (message in
messages):
<div n-ctrl="myCtrl">
<ul>
<li n-each="message in messages" n-html="message"></li>
</ul>
</div>
JS
scope.messages = [];
scope.messages.push('Hello');
scope.messages.push('Hi');
It's also possible to use an object or an array of objects.
Example with an array
of object
:
HTML
<div n-ctrl="myCtrl">
<ul>
<li n-each="user users">
<span n-text="user.name"></span>
<span n-text="user.email"></span>
<p n-html="user.bio"></p>
</li>
</ul>
</div>
JS
scope.users = [];
scope.users.push({
name : 'Nico',
email : '[email protected]',
bio : 'I eat <strong>pizza</strong>, miam!'
});
scope.users.push({
name : 'Sarah Connor',
email : '[email protected]',
bio : 'I am the mom of the future o_O I eat <strong>bullets</strong>!'
});
el
Handles directly an element.
HTML
<div n-ctrl="myCtrl">
<img n-el="src:logoUrl">
</div>
JS
scope.logoUrl = '/assets/img/logo.png';
Use only a callback which manages the element:
HTML
<div n-ctrl="myCtrl">
<div n-el="elHandler"></div>
</div>
JS
scope.elHandler = function(data) {
// current element
var node = data.node;
console.log(data);
};
html
Add the property value performed as HTML.
HTML
<div n-ctrl="myCtrl">
<div n-html="contents"></div>
</div>
JS
scope.contents = '<strong>Hello world</strong>';
Displays:
<div n-html="contents"><strong>Hello world</strong></div>
text
Add the property value performed as text. The HTML tags are natively escaped by the browser (TextNode).
HTML
<div n-ctrl="myCtrl">
<div n-text="contents"></div>
</div>
JS
scope.contents = '<strong>Hello world</strong>';
Displays:
<div n-text="contents"><strong>Hello world</strong></div>
on
Binds an event listener on the element using the event specified.
Attribute value: event:listener
.
HTML
<div n-ctrl="myCtrl">
<button on="click:onClick">Click me!</button>
</div>
JS
scope.onClick = function(event) {
$(this).text('clicked :)');
};
scope
Define the scope to bind in the HTML. It's useful to bind another scope easily.
HTML
<div n-ctrl="a">
<span n-text="scope a"></span>
</div>
<div n-ctrl="b">
<span n-scope="a" n-text="scope a"></span>
<span n-text="scope b"></span>
</div>
<!-- Without controller -->
<div n-scope="b">
<!-- Uses the scope "b" -->
<div n-html="user.name"></div>
</div>
Filters
Transform a value. Example, HELLO to Hello:
JS
scope.val = 'HELLO';
HTML
<span n-text="val|lc|ucFirst"></span>
List:
- lc Make a string lowercase
- lcFirst Make a string's first character lowercase
- uc Make a string uppercase
- lcFirst Make a string's first character uppercase
- rmSpace Remove space
- escape Escape a string (replace HTML tags and some character by HTML entities)
- e Shortcut of escape filter
- unescape Converts the HTML entities in escaped string (with escape / e filter), to their corresponding characters
Create a new filter:
ux.filters.strong = function(str) {
return '<strong>' + str + '</strong>';
};
Then use:
<span n-text="val|strong"></span>
Parser
Parsing:
var value = ux.expr.parse(expression, scope);
Note: expression
is passed to all parsers (by default Bindux have only one parser pipe
).
use a specific parser:
var value = ux.expr.parser('pipe').parse(expression, scope);
Create a new parser:
ux.expr.parsers.something = function(expression, scope, context) {
// parse ...
return str;
};
Note: context
is an optional argument to pass context data.
Then use:
var value = ux.expr.parser('something').parse(expression, scope, context);
When calling ux.expr.parse()
, all parsers are used (also the new parser something
).
If needed, you can pass the context
:
var value = ux.expr.parse(expression, scope, context);
events
Bindux inherits of evemit.
ux.on('say-hello', function(hello) {
console.log(hello); // Hello World!
});
ux.emit('say-hello', 'Hello World!');
Methods:
- ux.on(event, fn, [context])
- ux.once(event, fn, [context])
- ux.emit(event, [...arg])
- ux.off(event, fn)
- ux.listeners([event])
See the doc of Evemit.
Internal events
preLoad
Emitted by ux.init()
on preloading.
load
Emitted by ux.init()
on loading.
postLoad
Emitted by ux.init()
on postloading.
scopes.{scope name}.changes
Emitted when a scope object was changed.
Example a scope defined with ux.scopes.user
emit scopes.user.changes
.
ctrls.{controller name}.preLoaded
Emitted on preloading of a controller.
Example a controller defined with ux.ctrls.user
emit ctrls.user.preLoad
.
ctrls.{controller name}.preBoot
Emitted on prebooting of a controller.
ctrls.{controller name}.postBoot
Emitted on postbooting of a controller.
binders.each.scopes.{scope name}.{property name}.changes
Emitted by ux.binders.each
when a property (or an array
key) of a scope was changed.
Example, consider a scope named app
(ux.scopes.app
):
Scope object:
// if this code is in a controller,
// `scope` variable is passed by argument
var scope = ux.scopes.app;
scope.users = {
nico: {
job: 'developer',
age: '32',
country: 'France',
avatar: '/img/avatars/default.png'
}
};
Binder:
<ul>
<li n-each="user in users"></li>
</ul>
When scope.users
changes:
scope.users.nico.avatar = '/img/avatars/tux.png';
The event emitted is binders.each.scopes.app.users.changes
ux.color
In a application it is common to manipulate the colors via hexa and RGB(A).
The ux.color
object is an handy helper to facilitate the transition from one to the other.
toRgb(color, alpha)
Convert a given color
to RGB(A).
// rgb(255,255,255)
ux.color.toRgb('#ffffff');
// rgb(255,255,255)
ux.color.toRgb('white');
// rgb(255,255,255)
ux.color.toRgb('255,255,255');
// rgb(255,255,255)
ux.color.toRgb('#fff');
// rgb(255,255,255,0.8)
ux.color.toRgb('#fff', 0.8)
toHex(color)
Convert a given color
to Hexa.
// #ffffff
ux.color.toHex('#fff');
// #ffffff
ux.color.toHex('white');
// #ffffff
ux.color.toHex('rgb(255,255,255)');
// #ffffff
ux.color.toHex('rgb(255,255,255,0.8)');
// #ffffff
ux.color.toHex('rgba(255,255,255,0.8)');
names
Some color names.
// #008000
console.log(ux.color.names.green);
// see all colors
console.log(ux.color.names);
ux.html
getFirstTag(str)
Get the first HTML tag.
Returns the tag (lowercase) if found, null
otherwise.
var attr, str;
str = 'some text before <div id="layout" class="active">' +
'<span class="something">contents</span>' +
'</div> some text after';
attr = ux.html.getFirstTag(str);
// div
console.log(attr);
getAttrs(str)
Get attributes from a string. Returns attribute(s) name=value pairs in object.
var attrs, str;
str = '<div id="layout" class="active">' +
'<span class="something">contents</span>' +
'</div>';
attrs = ux.html.getAttrs(str);
// Object {id: "layout", class: "active"}
console.log(attrs);
toNode(str)
Convert a given string / HTML to Node
instance (Element
or TextNode
).
var node;
// TextNode
// (node.nodeType === Node.TEXT_NODE)
node = ux.html.toNode('hello');
console.log(node.data);
// Element (strong)
// (node.nodeType === Node.ELEMENT_NODE)
// (node.nodeName === 'STRONG')
node = ux.html.toNode('<strong>hello</strong>');
console.log(node.innerHTML);
stripTags(str, allowed)
Returns the string (str
) without HTML tag, or only with allowed
tag(s).
Remove all tags:
// Who are you
ux.html.stripTags('<p>Who</p> <br /><b>are</b> <i>you</i>');
Remove all tags except <i>
and <b>
:
// Who <b>are</b> <i>you</i>
ux.html.stripTags('<p>Who</p> <br /><b>are</b> <i>you</i>', '<i><b>');
Browser support
Bindux is near of the native features and standart compliant. Bindux is based on the native capabilities of standarts supported by the major modern browsers: Chrome 29+, Firefox 24+, Opera 24+, IE 11+, Safari 6.1+ and browsers based on its.
No hack imposed to the modern browsers, so it's very well for the performance. The hacks are only necessary for the old browsers and should be handled independently.
For make that the old browsers support the modern features you can use polyfills:
- es5-shim, provides ES5 (EcmaScript 5)
- DOM4, provides DOM4 spec
- es6-collections, provides WeakMap, Map and Set
Development of Bindux core
Bindux is developped in ES6 (EcmaScript6) in src directory and is compiled to ES5 in the dist/bindux.min.js.
Build a minified distributable, in the terminal:
gulp
Develop with the automatic rebuilds (the distribulable and the unit tests):
gulp dev
Unit tests
Bindux is unit tested with Unit.js and Mocha.
TODO: There are still things to test.
LICENSE
MIT (c) 2014, Nicolas Tallefourtane.
Author
Bindux is designed and built with love by
| | |---| | Nicolas Talle | | |