rad-reveal

#RadReveal RadReveal is a JavaScript library to help you extend Reveal.js - the HTML Presentation Framework.

Check out the demo slideshow to see how RadReveal works.

##Why isn't everybody hacking Reveal.js?

Reveal.js rocks! Web Developers seem to love Reveal.js, as evidenced by the fact that every other presentation on JavaScript seems to use it. Personally, I love Reveal.js because it is hackable.

But not a lot of people customize or extend it -- despite the fact that Reveal.js builds in extensibility. Or, if people are extending Reveal.js, they aren't sharing!

Maybe that's because, the out of the box, Reveal.js is not easy to extend...

##The solution? RadReveal

I put together RadReveal after noticing that every presentation I was doing had some level of customization, and the types of things I was doing had a lot in common. So I consolidated what I'd done into a simple to use library, RadReveal.

RadReveal provides these benefits.

• Makes customizing Reveal.js easy.
• Attach behaviors to slides using data attributes.
• Encourages small, shareable packages.

If you didn't already, take a look at the demo slideshow to see RadReveal in action.

#How to create a RadReveal add-on

Note: I plan to write a lot more on this soon, including some skeleton example repos you can check out and use.

##Running the demo slideshow locally To run the demo slideshow locally, simply:

git clone https://github.com/joelarson4/radReveal.git
cd radReveal
npm install

Now you should be able to run demo.html in your browser.

Note that you may need to sudo npm install to get everything installed properly.

##API JsDoc for RadReveal

You may want to to skip to the API documentation for the library.

##Simple example

What does an add-on look like?

example.js - the addon script

require('rad-reveal').register({
  name: 'example',
  initialize: function(radConfig, slides) {
    for(var s = 0, len = slides.length; s < len; s++) {
      slides[s].element.className += ' ' + radConfig.addClass;
    }
  }
});

index.html modifications for initializing RadReveal and Reveal.js

<script src="node_modules/reveal.js/lib/js/head.min.js"></script>
<script src="node_modules/reveal.js/js/reveal.js"></script>
<script src="node_modules/rad-reveal/build/radReveal.min.js"></script>

Reveal.initialize({
  ...normal Reveal configuration goes here
  dependencies: [
    { 
      //include it just like a normal dependency, 
      //  but with radName and radConfig properties
      src: 'somepath/example.js', 
      radName: 'example',
      radConfig: { addClass: 'example' } 
    }
    ...other dependencies go here
  ]
});

require('rad-reveal').initialize();

So what happens when you run this?

1. Reveal.initialize loads dependencies, including rad-example.js.
2. Example add-on registers self with require('rad-require').register({ ... }).
3. After Reveal is initialized, we call require('rad-require').initialize();.
4. RadReveal's initialize calls example add-on's initialize, passing radConfig, allSlides
5. Example add-on does whatever it wants.
6. In this example, the add-on appends a class to every slide.

##Beyond initialize: attributeEventListeners Imagine you want to run some code against specific slides at certain points in the slideshow. How could you do that?

Reveal.js provides some data attributes you can attach to slides to cause certain behaviors (like data-transition and data-background). RadReveal enables your add-on to take a similar approach.

You can provide RadReveal attributeEventListeners to define attribute listener functions for your add-on.
Listener functions are only called for slides or fragments that have specific attributes, and only when specific events occur.

For example:

require('rad-reveal').register({
  name: 'example',
  attributeEventListeners: {
    'data-rad-example': {
      setup: someFunction
    }
  }
});

For any slide with the data-rad-example attribute, someFunction will be called as part of add-on setup.

The listener function is called with four arguments:

• attrVal - the value of the attribute for this slide.
• slideObj - an object representing the slide (see documentation below).
• event - the event object.
• radEventName - the name of the event.

You could use this to do something to the slide element itself. For example, we could add a class based on the value of the attribute.

function addTheClass(attrVal, slideObj, event, radEventName) {
  slideObj.element.className += ' ' + attrVal;
}

require('rad-reveal').register({
  name: 'example',
  attributeEventListeners: {
    'data-rad-example': {
      setup: addTheClass
    }
  }
});

So, this slide:

<section data-rad-example="totallyRad">

would end up having an additional class of totallyRad added to it:

<section data-rad-example="totallyRad" class="totallyRad">

which is a silly example but illustrates the point.

##Trigger something upon showing/hiding a slide

You can also register to run something on showing/arriving or hiding/leaving a slide with an attribute.

require('rad-reveal').register({
  name: 'example',
  attributeEventListeners: {
    'data-rad-example': {
      shown: anotherFunction,
      hidden: andAnotherFunction
    }
  }
});

This means that anotherFunction will run each time a slide is displayed with a data-rad-example attribute, and then when you leave that slide andAnotherFunction will run.

##All supported events

These events can be used for attributeEventListeners, called for every slide or fragment with the specified attribute:

• setup is called when the add-on is initialized.
• shown is called when the matching slide is displayed.
• hidden is called when the matching slide is hidden.
• fragmentSetup is called when the add-on is initialized.
• fragmentShown is called when the fragment is displayed.
• fragmentHidden is called when the fragment is hidden.

##The slide object Event listeners get a slide object supplied as an argument. This slide object has several public properties:

• index the index number of the slide
• element the section element for this slide
• nextSlideObj the next slide object
• prevSlideObj the previous slide object
• lastSlideObj the slide object that was shown just before this one
• data an object to which add-ons can attach additional properties.

Please do not modify the slide object or any of it's properties directly except for the data property.

##The functionRunner example add-on.

The core RadReveal repo includes functionRunner, a simple add-on that triggers a function to run for any slide with a data-rad-functionrunner-{eventName} attribute. There is also API documentation for functionRunner.

For example, here is a slide with a data-rad-functionrunner-setup attr:

<section data-rad-functionrunner-setup='{ "root" : "bar", "func" : "baz" }'>

and the page has a (global) object defined:

var bar = {
  value: 'Hello world!',
  baz: function(slideObj, event, radEventName) {
    var span = document.createElement('span');
    span.innerHTML = radEventName + ': ' + this.value;
    slideObj.element.appendChild(span);
  }
}

Together this results in setup: Hello world! text being appended to the slide one time at setup (before any slides are shown).

You can also pass arguments through a functionRunner attribute. This slide has a data-rad-functionrunner-shown attr:

<section data-rad-functionrunner-shown='{ "func" : "foo", "args": ["shown", "2"] }'>

and the page has a (global) function defined:

function foo(arg0, arg1, slideObj, event, radEventName) {
  var span = document.createElement('span');
  span.className = 'functionRunnerAdded';
  span.innerHTML =  radEventName + ': ' + arg0 + ' at ' + arg1;
  slideObj.element.appendChild(span);
}

which results in shown: shown at 2 being appending to the slide every time it is shown.

Likewise you could use the attribute name data-rad-functionrunner-hidden to run a function when leaving the slide.

You also can use the same attributes on inner/vertical slides.

#In closing Before you go, a few more things you should know.

##Browser support I need to put more effort into formalizing my policy and approach on this, as well as testing IE. Currently I am manually testing this in recent versions of Chrome (40.0) and Firefox (31.4), and running automated tests in PhantomJS (1.9.8).

I am making an assumption that devs using Reveal.js are able to keep fairly up to date with browsers. I realize this limits slide-sharing capabilities but I think that's a tradeoff worth making. I'm also very open to help figuring out a better approach. Please feel free to file an issue and tell me why I'm wrong and what I can do better!

##More addons coming

• I have a several other addons in prototype that I will clean up and release (as separate repos) soon.
• I will list these on main RadReveal README.
• And hopefully remember to update this slide!

##Please write your own add-ons!

The dream would be a tiny ecosystem of well written addons that folks can use to make rad presentations.