#About
farbs is a Framework Agnostic Registry Based Skeleton for decoupled UI widgets or components.
It allows you to declaratively setup your UI components and configure them from within HTML without any JavaScript.
#Why
The benefit farbs offers is a clean separation between generic UI components and application logic, independent of any framework.
And it's only 948 bytes in size (457 bytes gzip'ed).
#How it works
farbs is a singleton object that holds registries for classes, instances and methods and offers a pub/sub mechanism.
Classes are registered with farbs like this:
farbs.registerClass('FancyCheckbox', TheFancyCheckboxClass);
To instantiate an instance of the class, add a data-farbs_type
attribute to an HTML element:
<checkbox id="myFancyCheckbox" data-farbs_type="FancyCheckbox">
The farbs object has a parse()
method, that will look for the data-farbs_type
attribute and create instances of found types:
farbs.parse();
farbs will register the created instances by their id in it's instance registry:
var myFancyCheckboxInst = farbs.instRegistry.myFancyCheckbox;
See the basic example (source) for an example of how it works.
#What else?
farbs mixes all attributes that start with data-farbs_
into the created instance. This way you can inject configuration options into your component.
<div id="myComponent" data-farbs_type="SomeComponent" data-farbs_color="green">
leads to:
farbs.instRegistry.myComponent.color; // 'green'
farbs has a method registry that can be used to access methods that are declared elsewhere (typically, you have a generic component and specific methods). An example:
farbs.registerMethod('notifyUser', function(value){ alert('foo: ' + value); });
You can pass the method's registry id to an instance using data attributes:
<checkbox
id="myFancyCheckbox"
data-farbs_type="FancyCheckbox"
data-farbs_onchange="notifyUser"
>
and then obtain a reference to it in your component through the method registry:
var changeHandler = farbs.method.Registry[this.onchange];
if (changeHandler) {
// we have have a handler, let's call it
changeHandler(this.domNode.checked);
}
See the basic example (source) for an example of usage of the method registry.
#More decoupling
If you want to go the whole way, farbs also comes with a pub/sub mechanism.
A topic is published like this:
farbs.publish('/Checkbox/change', ['checkbox', this.domNode.checked]);
publish()
takes two arguments: first, the topic to be published, and second, the data payload (optional).
Subscribing to a topic works like this:
farbs.subscribe('/Checkbox/change', this.changeSubscriber);
The first argument is the topic to subscribe two, the second is the function to call when that topic is published. The callback function will recieve the data payload as only argument.
To unsubscribe, just call farbs' unsubscribe()
method and pass the topic and function to unsubscribe:
farbs.unsubscribe('/Checkbox/change', this.changeSubscriber);
See the pubsub example (source) for an example of how it works.
#Accessing the farbs object
farbs comes as an AMD module. To access it, you need to require()
it.
The only exception from this are instances created by farbs: They get two arguments passed to their constructor: first, the DOM node of the element that had the data-farbs_type
attribute, and second, the farbs object itself, which you can, e.g., store on the instance:
function FancyCheckbox (domNode, farbs) {
this.domNode = domNode;
this.farbs = farbs;
}
As you probably create your UI components as modules, you could also leverage function scope to hold the reference to farbs:
var farbs;
function FancyCheckbox (domNode, _farbs) {
this.domNode = domNode;
farbs = _farbs;
}
#Frameworks
If you want to use, e.g., jQuery for your UI components or Underscore for tooling, that's perfectly fine - farbs does not stand in your way. Check the jquery example (source) to see how to startup a jQuery UI widget via farbs.
#Docs
API docs are minimal, but existing: http://jensarps.github.io/farbs/jsdoc/farbs.html
#Tests
Tests are in the tests
directory and are using the intern. To run them, clone the intern repository as a sibling to farbs, start a local webserver and point your browser to http://localhost/path/to/intern/client.html?config=farbs/tests/intern
. Test results appear in the console.
#License
MIT
#Questions?