bespoke

DIY Presentation Micro-Framework

Bespoke.js

Bespoke.js is a super minimal (1KB min'd and gzipped), modular presentation library for modern browsers, designed to foster a rich plugin ecosystem.

The core library sets up the presentation, provides a simple control API and manages events.

Any other functionality, from keyboard and touch interactions to CSS classes, bullet lists and hash routing, is implemented as a plugin. Joining the Bespoke.js plugin ecosystem is simple with Bespoke.js Plugin Generator.

Due to the highly modular nature of Bespoke.js, the quickest way to get started is with Bespoke.js Generator, a Yeoman generator that scaffolds a boilerplate presentation with a Grunt build system.

Assuming you have Node.js installed, in a blank directory:

$ npm install -g generator-bespoke
$ yo bespoke

In your newly scaffolded project, you can use the following Grunt tasks:

  • $ grunt server to run a preview server with LiveReload.
  • $ grunt deploy to deploy to GitHub Pages.
  • $ grunt to compile static assets to 'public'.

For more detailed instructions, check out the Bespoke.js Generator repo.

If you'd prefer to craft a new presentation from scratch, you can install Bespoke.js from npm with npm install bespoke, Bower with bower install bespoke.js, or manually download either the production version or the development version. The Bespoke.js core is extremely lightweight, so you'll probably want to include some plugins.

Bespoke.js is shipped in a UMD format, meaning that bespoke and its plugins are available as CommonJS/AMD modules or browser globals.

It's completely up to you which tags you use, but the following is a good starting point:

<article id="presentation">
  <section>Slide 1</section>
  <section>Slide 2</section>
  <section>Slide 3</section>
</article>

To create a new presentation, Bespoke.js provides the from(selector[, plugins]) method, which takes a selector or element reference and an array of plugins, and returns a deck instance.

var deck = bespoke.from('#presentation', [plugins]);
 
// Next slide 
deck.next();
 
// Previous slide 
deck.prev();
 
// Go to a specific slide 
deck.slide(0);
 
// Get the active slide index 
deck.slide(); // 0 

All official plugins can be installed from npm or Bower, e.g. $ npm install bespoke-keys or $ bower install bespoke-touch

All official plugins are provided in a UMD format, meaning they are available as CommonJS/AMD modules or browser globals.

For example, if you're using CommonJS modules via browserify or webpack, it would look something like this:

var bespoke = require('bespoke'),
  classes = require('bespoke-classes'),
  keys = require('bespoke-keys'),
  touch = require('bespoke-touch');
 
var deck = bespoke.from('#presentation', [
  classes(),
  keys(),
  touch()
]);

If you're using browser globals, all official plugins are added to the bespoke.plugins object, for example:

var deck = bespoke.from('#presentation', [
  bespoke.plugins.classes(),
  bespoke.plugins.keys(),
  bespoke.plugins.touch()
]);

If you already have a reference to a DOM node, you can pass it directly to the from method.

bespoke.from(element);

Deck instances are provided to plugins and returned when instantiating a presentation. The following properties are available on each instance.

Note: The optional eventData parameter is an object that will be merged with the event object in subsequent event handlers.

next([eventData]) Next slide.
prev([eventData]) Previous slide.
slide([index[, eventData]]) Get or set the active slide index.
on(event, callback) Attach event handlers
fire(event[, eventData]) Fire custom events. This method is primarily designed for plugin authors.
parent The deck's parent element
slides An array of slide elements

Events are bound via the deck instance. Each event is passed an event object containing a reference to the relevant slide and its index.

deck.on(eventName, function(event) {
  event.slide; // Relevant slide 
  event.index; // Index of relevant slide 
 
  // Prevent default functionality (for deck interaction events only) 
  return false;
});

In most cases, you will only need to use these standard events.

activate A slide has been activated. event.slide is the activated slide.
deactivate A slide has been deactivated. event.slide is the deactivated slide.

These events are fired when the deck has been interacted with, but before the interaction has had any effect.

This allows you to intercept the default behaviour by returning false from the event handler.

next The next slide has been requested, even if last slide is active. event.slide is the current slide.
prev The previous slide has been requested, even if first slide is active. event.slide is the current slide.
slide A specific slide has been requested. event.slide is the requested slide.

When binding events, the on method returns a function that can be used to remove the event handler.

var off = deck.on('activate', function() {
  // ... 
});
 
// Unbind event 
off();

Want a boilerplate plugin? Use the official Bespoke.js Plugin Generator.

If you'd like to learn by example, check out the list of existing plugins.

Plugins are simply functions that are called when presentations are created. They are passed a deck instance which allows you to interact with the deck's state, bind events and modify its elements.

To be consistent with the suite of official Bespoke.js plugins, it is highly recommended that you implement your plugin as a function that takes configuration and returns a plugin function.

// Creating the plugin 
var myPlugin = function() {
  return function() {
    deck.on('activate', function(e) {
      console.log('Activated slide ' + (e.index + 1) + ' of ' + deck.slides.length);
    });
  }
};

The plugin can now be provided in the plugins array when using the from(selector[, plugins]) method.

// Using the plugin 
bespoke.from('#presentation', [
  myPlugin()
]);

If your plugin needs some configurability, your plugin factory function can take options and return a configured plugin function.

// Creating the plugin with options 
var myPlugin = function(options) {
  return function(deck) {
    var showTotal = options && options.showTotal;
 
    deck.on('activate', function(e) {
      console.log('Activated slide ' + (e.index + 1) +
        (showTotal ? ' of ' + deck.slides.length : ''));
    });
  }
};
 
// Using the plugin with options 
bespoke.from('#presentation', [
  myPlugin({ showTotal: true })
]);

Additional event data can be supplied to next, prev and slide, which is merged with the final event object in subsequent event handlers.

This functionality is particularly useful if you need to differentiate between events caused by your plugin, and those caused by your end users or other plugins.

var myPlugin = function() {
  return function(deck) {
 
    // Differentiating our plugin's events 
    deck.on('activate', function(event) {
      if (event.foo === 'bar') {
        // Triggered by my plugin... 
      } else {
        // Triggered by end user, or another plugin... 
      }
    });
 
    // Providing custom event data 
    deck.next({
      foo: 'bar'
    });
 
  };
}

Made a presentation with Bespoke.js? Let me know.

Contact me on GitHub or Twitter: @markdalgleish

MIT License