Why another widget set?
The current RichWidget architecture is centered around the jQuery UI widget factory with LESS & Bootstrap for styling and theming. Candidate widgets that do not use the widget factory will be wrapped with the widget factory to provide a consistent widget API.
Using the widgets
Preview the widgets and see some sample use cases on our demo site: http://richwidgets.io.
To consume Richwidgets in your application/framework, you will currently have to build the widget assets.
(Note: In the time-frame of our 0.1 release we will provide RichWidgets as a Bower package.)
Executing a RichWidget
RichWidgets are jQuery plugins (built using the jQuery UI Widget Factory). Executing a plugin to include the widget's functionality is as simple as:
For a list of available widgets and their associated options check out the API Docs.
Invoking public methods
A widget's public methods are available through the jQuery UI Widget factory API. Accessing a public API method in this way looks like:
$('#myDiv').widgetName('methodName', param1, parma2, ....);
Accessing private methods is discouraged, but can be done so as follows:
var widget = $('myDiv').data('widgetName'); widget._privateMethod(params);
Acessing private methods can be handy for testing purposes, or for extending a widget. However the private method API has not contract of stability. If you find yourself needing to access a private method consider filing an issue requesting that the functionality be exposed via a public method.
Mutating widget options
The options used to initialize a widget via the
options parameter can be mutated using the
option public API method of the jQuery UI widget factory:
$('#myDiv').widgetName('option', 'optionName', param1, parma2, ....);
All widgets support the
destroy method. Invoking this method will remove the widget and restore your DOM to it's initial state:
Build from source
Along with cloning the project you will need to install the following tools:
- Node and NPM: instructions, official website
- recommended version: Node 0.10.22
- Grunt: instructions, official website
- Bower: instructions on official website
Once installed, go to the project root and run the following commands:
This should drop a bunch of logs in your shell and use up some bandwith. Once it's completed, you will have built the
dist folder which contains both
demos of the widgets, as well as all the compiled widgets'
Run the demo
Now that widgets and demo have been built with the
grunt command, you can view the widgets by either:
- Navigating your browser to the
- Run the command
grunt connect:demo:keepaliveand navigate your browser to http://localhost:9000/
Have a problem with one of our widgets? Is there a particular widget you'd like to see incorporated in the project? File an issue in our issue tracker.
RichWidgets is very much an open source project, your contributions are valued! Learn how to get involved with the project in our CONTRIBUTING.md guide.
Read about our approach to testing in the TESTS.md guide.