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.
Also, take a look at the currently available add-ons you can use.
So 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.
Currently available add-ons
I've published three add-ons so far, and more are on the way:
- functionRunner helps you run arbitrary functions when slides are shown, hidden, etc.
- rad-randomizer attaches seeded Psuedo Random Number Generators to your slides.
- rad-colorizer automatically adds foreground and background colors to your slides.
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 will 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 add-on script:
{ var RadReveal = ; { forvar s = 0 len = slideslength; s < len; s++ slidessclassName += ' ' + radConfigaddClass; } RadReveal;};
index.html
modifications for initializing RadReveal and Reveal.js:
Reveal; var RadReveal = ;RadReveal;
So what happens when you run this?
Reveal.initialize
loads dependencies, includingrad-example.js
.- Example add-on registers self with
RadReveal.register(nameString, initFunction)
. - After Reveal is initialized, we call
RadReveal.initialize();
. - RadReveal's
initialize
calls example add-on's initialize function, passingradConfig, allSlides
- Example add-on does whatever it wants.
- In this example, the add-on appends a class to every slide.
Beyond initialize: attribute event listeners
Imagine you want to run some code against specific slides or fragments 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 makes it so your add-on can take a similar approach.
You can provide RadReveal attribute event listeners 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.
You register them using RadReveal.on(attribute, eventName, function)
.
For example:
RadReveal;
For any slide or fragment with the data-rad-example
attribute, someFunction
will be called when the add-on is loaded (meaning, immediately).
The listener function is called with four arguments:
attrVal
- the value of the attribute for this slide or fragment.slideObj
- an object representing the slide or fragment (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.
{ var RadReveal = ; { slideObjelementclassName += ' ' + attrVal; } RadReveal;};
So, this slide:
would end up having an additional class of totallyRad
added to it:
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 or hiding a slide or fragment that has the attribute.
RadReveal;RadReveal;
This means that anotherFunction
will run each time a slide or fragment is displayed with a data-rad-example
attribute, and then when you leave that slide andAnotherFunction
will run.
Registering for multiple attributes, events, and/or handlers
Each of the three arguments to RadReveal.on
can be supplied as arrays:
RadReveal;
This will cause those two handler functions to be run on both load
and shown
events for any slide or fragment elements with data-rad-example
or data-rad-another
attributes.
You can also supply the attribute name with an asterisk at the end to select all matching attributes that start with whatever comes before the asterisk.
RadReveal;
That would match on elements with data-rad-example
or data-rad-example-whatever
.
Finally, multiple attribute names or event names can be supplied as a single string that are seperated by commas:
RadReveal
All supported events
These events can be used for attributeEventListeners
, fired for every slide or fragment with the specified attribute:
load
is fired when the add-on is loaded.shown
is fired when the matching slide or fragment is displayed.hidden
is fired when the matching slide or fragment is hidden.
The slide or fragment object
Event listeners get a slide or fragment object supplied as an argument. For slides, the object has several public properties:
index
the index number of the slideelement
thesection
element for this slidenextSlideObj
the next slide objectprevSlideObj
the previous slide objectlastSlideObj
the slide object that was shown just before this onedata
an object to which add-ons can attach additional properties.
For fragments, these are the properties:
index
the index number of the fragment (within the slide)element
the.fragment
element for this fragmentslideObj
the slide object to which the fragment belongsnextFragObj
the next fragment objectprevFragObj
the previous fragment objectdata
an object to which add-ons can attach additional properties.
Please do not modify the slide or fragment 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-load
attr:
and the page has a (global) object defined:
var bar = value: 'Hello world!' { var span = document; spaninnerHTML = radEventName + ': ' + thisvalue; slideObjelement; }
Together this results in load: Hello world!
text being appended to the slide one time at load (before any slides are shown).
You can also pass arguments through a functionRunner attribute. This slide has a data-rad-functionrunner-shown
attr:
and the page has a (global) function defined:
{ var span = document; spanclassName = 'functionRunnerAdded'; spaninnerHTML = radEventName + ' with ' + arg0; slideObjelement;}
which results in shown with 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 add-ons coming
- I have a several other add-ons 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 add-ons that folks can use to make rad presentations.