Docs

deck.core

The deck.core module provides all the basic functionality for creating and moving through a deck. It applies and removes classes to indicate the state of the deck and its slides, allowing CSS to take care of the visual representation of each state. It also provides methods for interacting with the deck, as well as basic key bindings for going to the next and previous slides. Separate extension modules provide more functionality using the API provided by core.

Methods

init - `$.deck(selector, options)`

selector:: string | jQuery | array, optional
options:: object, optional

Initializes the deck, using each element matched by selector as a slide. May also be passed an array of string selectors or jQuery objects, in which case each selector in the array is considered a slide. The second parameter is an optional options object which will extend the default values.

Users may also pass only an options object to init. In this case the slide selector will be options.selectors.slides which defaults to .slide.

$.deck('.slide');

$.deck([
   '#first-slide',
   '#second-slide',
   '#etc'
]);

next - `$.deck('next')`

Moves to the next slide. If the last slide is already active, the call is ignored.

prev - `$.deck('prev')`

Moves to the previous slide. If the first slide is already active, the call is ignored.

go - `$.deck('go', index)`

index:: integer | string

Moves to the slide at the specified index if index is a number. Index is 0-based, so $.deck('go', 0); will move to the first slide. If index is a string this will move to the slide with the specified id. If index is out of bounds or doesn’t match a slide id the call is ignored.

getSlide - `$.deck('getSlide', index)`

Returns: jQuery

index:: integer | string, optional

Returns a jQuery object containing the slide at index. If index is not specified, the current slide is returned.

getSlides - `$.deck('getSlides')`

Returns: array

Returns all slides as an array of jQuery objects.

getTopLevelSlides - `$.deck('getTopLevelSlides')`

Returns: array

Returns all slides that are not subslides as an array of jQuery objects.

getNestedSlides - `$.deck('getNestedSlides', index)`

Returns: array

index: integer, optional

Returns all nested slides of the current slide as an array of jQuery objects. If index is specified it returns nested slides of the slide at that index. If there are no nested slides this will return an empty array.

getContainer - `$.deck('getContainer')`

Returns: jQuery

Returns a jQuery object containing the deck container as defined by the container option.

getOptions - `$.deck('getOptions')`

Returns: object

Returns the options object for the deck, including any overrides that were defined at initialization.

extend - `$.deck('extend', name, method)`

name:: string
method:: function

Adds method to the deck namespace with the key of name. This doesn’t give access to any private member data — public methods must still be used within method — but lets extension authors piggyback on the deck namespace rather than pollute jQuery.

$.deck('extend', 'alert', function(msg) {
   alert(msg);
});

// Alerts 'boom'
$.deck('alert', 'boom');

Options

The default settings object for a deck. All extensions should extend this object to add defaults for any of their options.

$.deck.defaults = {
   classes: {
      after: 'deck-after',
      before: 'deck-before',
      childCurrent: 'deck-child-current',
      current: 'deck-current',
      loading: 'deck-loading',
      next: 'deck-next',
      onPrefix: 'on-slide-',
      previous: 'deck-previous'
   },

   selectors: {
      container: '.deck-container',
      slides: '.slide'
   },

   keys: {
      // enter, space, page down, right arrow, down arrow
      next: [13, 32, 34, 39, 40],
      // backspace, page up, left arrow, up arrow
      previous: [8, 33, 37, 38]
   },

   touch: {
      swipeDirection: 'horizontal',
      swipeTolerance: 60
   },

   initLockTimeout: 10000,
   hashPrefix: 'slide',
   preventFragmentScroll: true,
   setAriaHiddens: true
}

options.classes.after: This class is added to all slides that appear after the 'next' slide.
options.classes.before: This class is added to all slides that appear before the 'previous' slide.
options.classes.childCurrent: This class is added to all elements in the DOM tree between the 'current' slide and the deck container. For standard slides, this is mostly seen and used for nested slides.
options.classes.current: This class is added to the current slide.
options.classes.loading: This class is applied to the deck container during loading phases and is primarily used as a way to short circuit transitions between states where such transitions are distracting or unwanted. For example, this class is applied during deck initialization and then removed to prevent all the slides from appearing stacked and transitioning into place on load.
options.classes.next: This class is added to the slide immediately following the 'current' slide.
options.classes.onPrefix: This prefix, concatenated with the current slide index, is added to the deck container as you change slides.
options.classes.previous: This class is added to the slide immediately preceding the 'current' slide.
options.selectors.container: Elements matched by this CSS selector will be considered the deck container. The deck container is used to scope certain states of the deck, as with the onPrefix option, or with extensions such as deck.goto and deck.menu. For standard full screen decks, this should be the body element.
options.selectors.slides: Elements matched by this selector make up the individual deck slides. If a user chooses to pass the slide selector as teh first argument to $.deck() on initialization it does the same thing as passing an override for this option.
options.keys.next: The numeric keycode used to go to the next slide.
options.keys.previous: The numeric keycode used to go to the previous slide.
options.touch.swipeDirection: The direction swipes occur to cause slide changes. Can be 'horizontal', 'vertical', or 'both'. Any other value or a falsy value will disable swipe gestures for navigation.
options.touch.swipeTolerance: The number of pixels the user’s finger must travel to produce a swipe gesture.
options.initLockTimeout: The number of milliseconds the init event will wait for beforeInit event locks to be released before firing the init event regardless.
options.hashPrefix: Every slide that does not have an id is assigned one at initialization. Assigned ids take the form of hashPrefix + slideIndex, e.g., slide-0, slide-12, etc.
options.preventFragmentScroll: When deep linking to a hash of a nested slide, this scrolls the deck container to the top, undoing the natural browser behavior of scrolling to the document fragment on load.
options.setAriaHiddens: When set to true, deck.js will set aria-hidden attributes for slides that do not appear onscreen according to a typical hierarchical deck structure. You may want to turn this off if you are using a theme where slides besides the current slide are visiblee on the screen and should be accessible to screenreaders.

Events

All events are triggered on the document.

deck.beforeChange

This event fires when a slide change has been triggered but before the change occurs. The callback function is passed two parameters, from and to, equal to the indices of the old slide and the new slide respectively. If preventDefault is called on the event within this handler the deck.change event will not fire and the slide change does not occur. Handlers for this event should only focus on this aspect of the slide change, whether the change should occur and preventing default accordingly.

deck.change

This event fires whenever the current slide changes, whether by way of next, prev, or go. The callback function is passed two parameters, from and to, equal to the indices of the old slide and the new slide respectively.

$(document).bind('deck.change', function(event, from, to) {
   alert('Moving from slide ' + from + ' to ' + to);
});

deck.beforeInit

This event fires at the beginning of deck initialization. This event makes a good hook for preprocessing extensions looking to modify the DOM before the deck is fully initialized. It is also possible to halt the deck.init event from firing while you do things in beforeInit. This can be done by calling lockInit on the event object. The init can be released by calling releaseInit.

$(document).bind('deck.beforeInit', function(event) {
  event.lockInit(); // halts deck.init event
  window.setTimeout(function() {
    event.releaseInit(); // deck.init will now fire 2 seconds later
  }, 2000);
});

The init event will be fired regardless after options.initLockTimeout milliseconds if locks still persist.

deck.init

This event fires at the end of deck initialization. Extensions should implement any code that relies on user extensible options (key bindings, element selectors, classes) within a handler for this event. Native events associated with deck.js should be scoped under a .deckmodule event namespace, as with the example below:

var $d = $(document);
$.deck.defaults.keys.myExtensionKeycode = 70; // 'h'
$d.bind('deck.init', function() {
   $d.bind('keydown.deckmyextension', function(event) {
      if (event.which === $.deck.getOptions().keys.myExtensionKeycode) {
         // Rock out
      }
   });
});

Theming

Below is a skeleton example of a standard deck and all the theme-able components included in core. What follows is an explanation of each component and the base CSS properties that themes must extend. These bare styles can be seen on the Getting Started page and selecting "None" for both Style and Transition themes.

<body class="deck-container">
   <section class="slide deck-before">...</section>
   <section class="slide deck-before deck-child-current">
      ...
      <section class="slide deck-before">...</section>
      <section class="slide deck-previous">...</section>
      <section class="slide deck-current"></section>
      <section class="slide deck-next">...</section>
   </section>
   <section class="slide deck-after">...</section>
   <section class="slide deck-after">...</section>
</body>

.deck-container

The deck container wraps all slides. Keeping the position:relative and height:100% rules intact is recommended, as they tend to be needed for transition themes.

position: relative;
height: 100%;
width: 70%;
margin: 0 auto;
padding: 0 48px;

.slide

These are generic styles for all slides, including nested slides. These should rarely be overwritten.

width: auto;
min-height: 100%;
position: relative;

.deck-before, .deck-previous, .deck-next, .deck-after

All slides that are not the current one are accessibly hidden off the screen.

position: absolute;
left: -999em;
top: -999em;

.deck-current

The current slide is given a z-index. This does nothing on its own, but is included in core as it is commonly used in transition themes.

z-index: 2;

.slide .slide

All nested slides are reset to a static position to maintain the parent slide layout and hidden in place.

visibility: hidden;
position: static;
min-height: 0;

.deck-child-current

Parents of active nested slides are reset to a static position to keep them in place despite having a .deck-previous or .deck-before class simultaneously.

position: static;
z-index: 2;

.deck-child-current .slide

All nested slides are hidden by default.

visibility: hidden;

.deck-child-current any(.deck-previous, .deck-before, .deck-current)

The current nested slide and any previous nested slides are visible.

visibility: visible;

deck.goto

This module adds the necessary methods and key bindings to show and hide a form for jumping to any slide number/id in the deck (and processes that form accordingly). The form-showing state is indicated by the presence of a class on the deck container.

Methods

showGoTo - `$.deck('showGoTo')`

Shows the Go To Slide form by adding the class specified by the goto class option to the deck container.

hideGoTo - `$.deck('hideGoTo')`

Hides the Go To Slide form by removing the class specified by the goto class option from the deck container.

toggleGoTo - `$.deck('toggleGoTo')`

Toggles between showing and hiding the Go To Slide form.

Options

$.extend(true, $.deck.defaults, {
   classes: {
      goto: 'deck-goto'
   },

   selectors: {
      gotoForm: '.goto-form',
      gotoInput: '#goto-slide'
   },

   keys: {
      goto: 71 // 'g'
   },

   countNested: true
});

options.classes.goto: This class is added to the deck container when showing the Go To Slide form.
options.selectors.gotoDatalist: The element that matches this selector is the datalist element that will be populated with options for each of the slide ids. In browsers that support the datalist element, this provides a drop list of slide ids to aid the user in selecting a slide.
options.selectors.gotoForm: The element that matches this selector is the form that is submitted when a user hits enter after typing a slide number/id in the gotoInput element.
options.selectors.gotoInput: The element that matches this selector is the text input field for entering a slide number/id in the Go To Slide form.
options.keys.goto: The numeric keycode used to show the Go To Slide form.
options.countNested: If false, only top level slides will be counted when entering a slide number.

Theming

<form action="." method="get" class="goto-form">
   <label for="goto-slide">Go to slide:</label>
   <input type="number" name="slidenum" id="goto-slide" list="goto-datalist">
   <datalist id="goto-datalist"></datalist>
   <input type="submit" value="Go">
</form>

.goto-form

The form is centered at the bottom of the deck container by default. Defining everything in em units lets the form scale if the base font size of the deck container changes with the theme.

position: absolute;
z-index: 3;
bottom: 10px;
left: 50%;
height: 1.75em;
margin: 0 0 0 -9.125em;
line-height: 1.75em;
padding: 0.625em;
display: none;
background: #ccc;
overflow: hidden;

// .border-radius .goto-form
-webkit-border-radius: 10px;
-moz-border-radius: 10px;
border-radius: 10px;

// .deck-goto .goto-form (showing form)
display: block;

.goto-form label

font-weight: bold;
float: left;

.goto-form input

display: inline-block;
font-family: inherit;

#goto-slide

width: 8.375em;
margin: 0 0.625em;
height: 1.4375em;

deck.menu

This module adds the necessary methods and key bindings to show and hide a menu of all slides in the deck. The deck menu state is indicated by the presence of a class on the deck container.

Options

$.extend(true, $.deck.defaults, {
   classes: {
      menu: 'deck-menu'
   },

   keys: {
      menu: 77 // 'm'
   }
});

options.classes.menu: This class is added to the deck container when showing the slide menu.
options.keys.menu: The numeric keycode used to toggle between showing and hiding the slide menu.
options.touch.doubletapWindow: Two consecutive touch events within this number of milliseconds will be considered a double tap, and will toggle the menu on touch devices.

Theming

<body class="deck-container deck-menu">
   ...
</body>

.deck-menu .slide

Unhides all slides, including nested slides.

background: #eee;
position: static;
visibility: visible;

.deck-menu .deck-current

Highlights the active slide.

background: #ddf;

deck.navigation

This module adds clickable previous and next links to the deck.

Options

$.extend(true, $.deck.defaults, {
   classes: {
      navDisabled: 'deck-nav-disabled'
   },

   selectors: {
      nextLink: '.deck-next-link',
      previousLink: '.deck-prev-link'
   }
});

options.classes.navDisabled: This class is added to a navigation link when that action is disabled. It is added to the previous link when on the first slide, and to the next link when on the last slide.
options.selectors.nextLink: The elements that match this selector will move the deck to the next slide when clicked.
options.selectors.previousLink: The elements that match this selector will move to deck to the previous slide when clicked.

Theming

<a href="#" class="deck-prev-link" title="Previous">&#8592;</a>
<a href="#" class="deck-next-link" title="Next">&#8594;</a>

.deck-prev-link, .deck-next-link

display: none;
position: absolute;
z-index: 3;
top: 50%;
width: 32px;
height: 32px;
margin-top: -16px;
font-size: 26px;
line-height: 30px;
vertical-align: middle;
text-align: center;
text-decoration: none;
color: #fff;
background: #888;

// .border-radius only
-webkit-border-radius: 16px;
-moz-border-radius: 16px;
border-radius: 16px;

.deck-container:hover .deck-prev/next-link

Only shows the navigation buttons if you hover over the deck continer. Since the default deck container width is only 70%, this hides the nav when presenters move their mouse to a corner.

display: block;

.deck-prev-link

left: 0;

.deck-next-link

right: 0;

.deck-container:hover .deck-nav-disabled

Applied to the appropriate link to hide it when on the first or last slide.

display: none;

deck.scale

This module adds automatic scaling to the deck. Each slide is scaled down using CSS transforms to fit within the deck container. If the container is big enough to hold the slide without scaling, no scaling occurs. The user can disable and enable scaling with a keyboard shortcut.

Note: CSS transforms may make Flash videos render incorrectly. Presenters that need to use Flash videos may want to disable scaling to play them. HTML5 video works fine.

Methods

enableScale - `$.deck('enableScale')`

Enables scaling and adds the scale class to the deck container.

disableScale - `$.deck('disableScale')`

Disables scaling and removes the scale class from the deck container.

toggleScale - `$.deck('toggleScale')`

Toggles between enabling and disabling scaling.

Options

$.extend(true, $[deck].defaults, {
   classes: {
      scale: 'deck-scale'
   },

   keys: {
      scale: 83 // s
   },

   baseHeight: null,
   scaleDebounce: 200
});

options.classes.scale: This class is added to the deck container when scaling is enabled. It is enabled by default when the module is included.
options.keys.scale: The numeric keycode used to toggle enabling and disabling scaling.
options.baseHeight: When baseHeight is falsy, as it is by default, the deck is scaled in proportion to the height of the deck container. You may instead specify a height as a number of px, and slides will be scaled against this height regardless of the container size.
options.scaleDebounce: Scaling on the browser resize event is debounced. This number is the threshold in milliseconds. Check out John Hann’s article on debouncing to learn more about it.

deck.status

This module adds a (current)/(total) style status indicator to the deck.

Options

$.extend(true, $.deck.defaults, {
   selectors: {
      statusCurrent: '.deck-status-current',
      statusTotal: '.deck-status-total'
   },

   countNested: true
});

options.selectors.statusCurrent: The element matching this selector displays the current slide number.
options.selectors.statusTotal: The element matching this selector displays the total number of slides.
options.countNested: If false, nested slides will be ignored in the total slide count and any navigation to them will be treated as navigation to the top level slide.

Theming

<p class="deck-status">
   <span class="deck-status-current"></span>
   /
   <span class="deck-status-total"></span>
</p>

.deck-status

The status indicator is placed in the bottom right padding of the deck container by default. .deck-status-current and .deck-status-total are used by the extension’s JS, but also provide hooks for styling. They inherit from .deck-status with no custom styles of their own.

position: absolute;
bottom: 10px;
right: 0;
color: #888;
z-index: 3;
margin: 0;