kumu-widgets

Widgets

The official Kumu markdown widget collection.

We've extended the marked markdown library to support custom widgets through a simple [[widget]] syntax. Widgets are ridiculously easy to write and we'd love to accept pull requests for new ones! (See the contributing guide at the bottom.)

Basics

Widgets are handled through a simple uri-based router. Required parameters are handled through named parameters, with optional parameters handled through the query string.

[[vimeo/86389108?aspect=hd]]

Defining Widgets

All you need is a function to render the widget and a route to attach it to.

Here's the full vimeo widget as an example:

// lib/widgets/vimeo/vimeo.js
function render(id, options) {
  return this.template("vimeo/vimeo", {
    src: "//player.vimeo.com/video/" + id + "?title=0&byline=0&portrait=0",
    aspect: options.aspect
  });
}

module.exports = function(widgets) {
  widgets.add("vimeo/:id", render, {aspect: "hd"});
};

<!-- lib/widgets/vimeo/vimeo.jst -->
<div class="widget-container" data-aspect-ratio="<%- aspect %>">
  <div class="widget-content">
    <iframe src="<%- src %>" frameborder="0" width="100%" height="100%"
      webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
  </div>
</div>

(Note: Templates are rendered using underscore templates.)

Contributing

We'd love for you to add your own custom widgets. It's easy to get started.

// Step 1. Make sure node / npm installed
node --version
npm --version

// Step 2. Install mocha globally (for testing, may require sudo)
npm install -g mocha

Basic process for adding new widgets:

• Fork the project
• Create a feature branch git checkout -b add-mywidget
• Install dependencies make install
• Add your widget (see test/widgets/vimeo for example)
• Add some tests
• Submit a pull request

Please limit each pull request to a single widget.

Testing

Run make test to run the test suite.