JavaScript widget toolkit, for the creation and distribution of third-party web widgets.
JavaScript
Permalink
Failed to load latest commit information.
src bump sqwidget version Dec 13, 2013
test expose core but don't conflict Dec 13, 2013
.bowerrc tests working again + new optimization stage Nov 11, 2013
.gitignore add src Dec 2, 2013
.npmignore produce optimized rjs blob Oct 2, 2013
Gruntfile.js update to latest youarei Dec 2, 2013
Makefile
README.md Remove postinstall; update docs Jul 25, 2014
bower.json Remove postinstall; update docs Jul 25, 2014
index.html namespace rjs + don't use almond(no remote support) + working index Nov 11, 2013
karma.conf.js Remove postinstall; update docs Jul 25, 2014
package.json Remove postinstall; update docs Jul 25, 2014
sqwidget.js updated youarei Dec 13, 2013

README.md

Sqwidget

Sqwidget is a framework for adding components to a page in a way that ensures they are self contained and namespaced. It is great for buliding third party widgets.

A typical embed code looks like the following:

<div data-sqwidget data-sqwidget-url="//example.com/my-widget"></div>
<script src="//example.com/sqwidget.js"></script>

Features

  1. Easy configurations and customisations: An embed code can have any number of optional parameters that are passed to the constructer your widget.
  2. Sandboxed JavaScript: All your JS is completely sandboxed from the rest of page not allowing you to leak any globals by default. It uses RequireJS to call your widget.
  3. Widgets are RequireJS modules.
  4. Yeoman Generator: A Yeoman generator allows you to scaffold your widget very quickly. The scaffold includes some libraries that we've found great for building high-performance widgets:
    1. RactiveJS
    2. Lodash
    3. RequireJS

The only hard dependency is RequireJS, since sqwidget expects to find a RequireJS module to initialise.

Getting Started

The easiest way to get started with using Sqwidget in your project is to use the Yeoman generator that builds a project layout for you.

First, install Yeoman using:

$ npm install -g yo

Next, install the sqwidget-generator:

$ npm install -g generator-sqwidget

Finally, initiate your project in a new directory where you want to create your widget:

$ mkdir my-awesome-project
$ cd my-awesome-project
$ yo sqwidget

This will create your project for you and install all the dependencies. See your widget in action by doing:

$ grunt

The Basic Widget

At the minimum, your widget will have a src/main.js which is a RequireJS module. This module should return a function that accepts one options parameter (object).

Example:

define([], function() {
    return function(options) {
        // DOM element to append your content is available at options.el
        // Config params are available at options.config
    };
});

Configuration and Custom Parameters

The embed code can also accept any number of parameters like:

<div data-sqwidget data-sqwidget-url="//example.com/my-widget"
    data-sqwidget-title="My Title" data-sqwidget-user="johndoe"
    data-sqwidget-age="20"></div>

All parameters that begin with data-sqwidget- will be passed to the function called in your widget during initialisation.

In this case, the options object from above will have a config object that looks like:

options = {
    el: <DOM NODE>,
    config = {
        "title": "My Title",
        "user": "johndoe",
        "age": "20"
    },
    ...

Development

Building sqwidget

npm install grunt-cli -g
npm install bower -g
bower install
npm install
grunt test