Skip to content

Latest commit

 

History

History
118 lines (78 loc) · 5.24 KB

README.md

File metadata and controls

118 lines (78 loc) · 5.24 KB
Raw

RichWidgets Build Status devDependency Status

A JavaScript project containing standalone javascript widgets based on Bootstrap, jQuery UI and other third-party widgets, styled with LESS.

Why another widget set?

In the RichWidgets project we are curating a set of OSS responsive javascript widgets. Existing OSS widgets are leveraged wherever possible, either consuming them directly as widgets, or by composing them into new widgets. These widgets are then made available through this project with a consistent API and Look and Feel - making it easier for you to add rich functionality to your web apps (or web frameworks!).

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:

$('#myDiv').widgetName(options);

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, ....);

Cleanup

All widgets support the destroy method. Invoking this method will remove the widget and restore your DOM to it's initial state:

$('#myDiv').widgetName('destroy');

Build from source

Along with cloning the project you will need to install the following tools:

Once installed, go to the project root and run the following commands:

  • npm install
  • grunt bower
  • grunt

This should drop a bunch of logs in your shell and use up some bandwith. Once it's completed, you will have built the richwidgets dist folder which contains both demos of the widgets, as well as all the compiled widgets' assets.

Run the demo

Now that widgets and demo have been built with the grunt command, you can view the widgets by either:

  1. Navigating your browser to the dist/demo folder
  2. Run the command grunt connect:demo:keepalive and navigate your browser to http://localhost:9000/
Remember! The demos are also available [online](http://richwidgets.io).

Reporting Bugs

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.

Contributors

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.

License

Apache License Version 2.0.