<commit_before>= bespoke-overview
<NAME>
:idprefix:
:idseparator: -
:experimental:
:uri-raw-file-base: https://raw.githubusercontent.com/opendevise/bespoke-overview/master

The bespoke-overview plugin presents an overview of all the slides when the kbd:[o] is pressed in a http://markdalgleish.com/projects/bespoke.js[Bespoke.js] presentation.
This overview mode gives you a “big picture” view of the presentation.
It can also be used as a navigation aid to advance to an arbitrary slide.

image::demo/screenshot.png[Screenshot of bespoke-overview]

== Download

Download the {uri-raw-file-base}/dist/bespoke-overview.min.js[production mode version] or the {uri-raw-file-base}/dist/bespoke-overview.js[development mode version], or use a <<package-managers,package manager>>.

== Example

http://opendevise.github.io/bespoke-overview[View the demo] online.

This repository includes a demo folder the shows this plugin in action.
To view it locally, you first need to clone this repository:

 $ git clone https://github.com/opendevise/bespoke-overview && cd bespoke-overview

Next, install the dependencies inside the project folder using npm:

 $ npm install

Finally, visit the file [path]_demo/index.html_ in your browser to see the plugin in action.
Press the kbd:[o] key to activate overview mode.

== Usage

This plugin is shipped in a https://github.com/umdjs/umd[UMD format], meaning that it is available as a CommonJS/AMD module or as a browser global.

For example, when using CommonJS modules:

```js
var bespoke = require('bespoke'),
  classes = require('bespoke-classes'),
  keys = require('bespoke-keys'),
  overview = require('bespoke-overview');

bespoke.from('.deck', [
  classes(),
  keys(),
  overview()
]);
```

When using browser globals:

```js
bespoke.from('.deck', [
  bespoke.plugins.classes(),
  bespoke.plugins.keys(),
  bespoke.plugins.overview()
]);
```

=== Options

The following options are available to the bespoke-plugin:

columns _(type: integer, default: 3)_::
The number of columns to use for the grid.

margin _(type: number, default: 15)_::
The spacing (in pixels) between the slides in the grid.
This value is scaled by the same amount as the slides when in overview mode.

autostart _(type: boolean, default: false)_::
A flag that controls whether the presentation starts in overview mode.

numbers _(type: boolean, default: false)_::
A flag that controls whether numbers are shown on the slides when in overview mode.
When enabled, adds the `bespoke-overview-counter` class to the deck parent element.
The style of the numbers can be controlled using the `.bespoke-overview-counter .bespoke-slide::after` CSS selector.

title _(type: boolean, default: false)_::
A flag that controls whether the presentation title is shown above the slides in overview mode.
When enabled, adds a `<header>` element with the `bespoke-title` class as the first child of the deck parent element.
The title content is taken from either the `data-title` attribute on the deck parent or `document.title`.
The style of the title can be controlled using the `.bespoke-overview .bespoke-title` CSS selector.

Here's an example showing all the options enabled:

```
bespoke.from('.deck', [
  classes(),
  keys(),
  overview({ columns: 2, margin: 10, autostart: true, numbers: true, title: true })
]);
```

=== Plugin order

The overview plugin should be applied in the following order relative to other plugins:

* bespoke-classes
* bespoke-scale
* *bespoke-overview*
* bespoke-bullets
* bespoke-multimedia

The placement of other plugins doesn't result in any known problems.

== How it works

When the trigger key is pressed (i.e., kbd:[o]), all the slides in the presentation become visible and are arranged in a grid layout.
The number of columns in the grid is controlled by the `columns` option passed to the plugin (e.g., `overview({ columns: 4 })`, which defaults to 3.
The number of rows is determined by the number of slides in the presentation.
A scrollbar will appear on the right side of the screen, which can be used to bring slides that spill outside the visible area into view.

When the plugin is loaded, it prepends a collection of styles to the top of the HTML page, which are used to control the default behavior of the overview mode.
Note that these styles can be overridden or customized.

When the overview is activated, the `bespoke-overview` class is added to the deck parent element (the element that has the `bespoke-parent` class).
Thanks to the built-in styles, all the slides will become visible (pending any slide transitions) when the `bespoke-overview` class is added to the deck parent.
Next, a transform is applied to each slide to arrange the slides in a grid layout.
The transform consists of two properties:

translate::
sets the x, y coordinates of the slide

scale::
resizes the slide to fit within the grid

TIP: This plugin works either with or without the bespoke-scale plugin applied (in either mode).

After the overview is activated, the selected slide will automatically be scrolled into view.
A border will appear around the selected slide.
You can use the cursor to navigate through the slides in overview mode.
You'll see the selection border advance as you use the left and right arrows (kbd:[<-] and kbd:[->], respectively).
The selected slide will be scrolled into view automatically, if necessary.

NOTE: For browsers that honor the CSS https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior[scroll-behavior] property (e.g., Firefox), the slides will be scrolled into view smoothly.

There are two ways to leave overview mode.
When one of the trigger keys is pressed (i.e., kbd:[o] or kbd:[enter]), the presentation will exit from overview mode and show the selected slide in the normal (single slide) mode.
If, instead, one of the slides is clicked, the presentation will return to the normal (single slide) mode after advancing to the slide that received the click.

When overview mode is deactivated, the `bespoke-overview` class is removed from the deck parent, the scrollbar is hidden, the slides are temporarily repositioned to account for the deactivation of the scrollbar and, finally, the manual transform on each slide is removed.
(If there's a scroll offset when the overview mode is deactivated, it will appear as though the selected slide transitions from its position in the overview to its position in slide mode thanks to an interim translation of its position).

== Transitions

The bespoke-overview plugin gives you fine-grained control over the transition going to and from overview mode.
The `bespoke-overview-to` class is added to the deck parent when the overview is activated and remains there until all slide transitions, if any, are complete.
Conversely, the `bespoke-overview-from` class is added to the deck parent when the overview is deactivated and remains there until all slide transitions, if any, are complete.

IMPORTANT: The transform origin is assumed to be 50% 50% (i.e., the center of the slide).

NOTE: The `bespoke-overview` class is removed immediately when the overview mode is deactivated, whereas the `bespoke-overview-from` class remains on the deck parent element until all slide transitions, if any, are complete.

TIP: If you want to defer a style change until the transition into overview mode is complete, using the CSS selector `.bespoke-overview:not(.bespoke-overview-to)`.

.Understanding z-index values
****
If each slide is enclosed in a wrapper element that has a transform applied to it (e.g., when bespoke-scale is enabled and configured to use the transform strategy), the z-index setting on a slide will have no effect on the visual stacking order.
This happens because a wrapper element with a transform applied creates a new stacking context, which limits the scope of the z-index setting (i.e., the value only applies relative to other elements in the stacking context).
Under these conditions, the active slide may not appear on top when transitioning out of overview mode regardless of the z-index setting.
****

=== Default transitions

By default, overview mode will use the same transitions that are applied to the slides themselves.
If you do not use transitions on the slides in your presentation, then transitions will not be used when you toggle overview mode.

=== Disabling transitions

If you do have transitions on your slides (particularly on `transform`), you can disable transitions when going to and from overview mode using the following styles in your CSS file:

```css
.bespoke-overview-to .bespoke-slide,
.bespoke-overview-from .bespoke-slide {
  -webkit-transition: none;
  transition: none;
}
```

=== Custom transitions

Rather than disabling transitions, you can use the `bespoke-overview-to` and `bespoke-overview-from` classes to create distinct transitions when entering and leaving overview mode.

```css
.bespoke-overview-to .bespoke-slide {
  -webkit-transition: -webkit-transform 0.5s ease-out, opacity 0.5s ease-in-out 0.4s;
  transition: transform 0.5s ease-out, opacity 0.5s ease-in-out 0.4s;
}

.bespoke-overview-from .bespoke-slide {
  -webkit-transition: -webkit-transform 0.5s ease-in-out 0.05s, opacity 0.15s ease-in-out;
  transition: transform 0.5s ease-in-out 0.05s, opacity 0.15s ease-in-out;
}
```

=== Transitioning the title

If you enable the title, you can also use the `bespoke-overview-to` and `bespoke-overview-from` to control the transition on the title when entering and leaving overview mode.

```css
.bespoke-title {
  opacity: 0;
}

.bespoke-overview .bespoke-title {
  opacity: 1;
}

.bespoke-overview-to .bespoke-title {
  visibility: visible;
  -webkit-transition: opacity 0.5s ease-in-out 0.4s;
  transition: opacity 0.5s ease-in-out 0.4s;
}

.bespoke-overview-from .bespoke-title {
  visibility: visible;
  -webkit-transition: opacity 0.15s ease-in-out;
  transition: opacity 0.15s ease-in-out;
}
```

IMPORTANT: The `visibility` property is important as it overrides the built-in behavior necessary to work when transitions on the title are not used.

== Package managers

=== npm

```bash
$ npm install bespoke-overview
```

=== Bower

```bash
$ bower install bespoke-overview
```

== Credits

This plugin was built with https://github.com/markdalgleish/generator-bespokeplugin[generator-bespokeplugin].

== License

http://en.wikipedia.org/wiki/MIT_License[MIT License]
<commit_msg>clarify the HTML used for the title element<commit_after>= bespoke-overview
<NAME>
:idprefix:
:idseparator: -
:experimental:
:uri-raw-file-base: https://raw.githubusercontent.com/opendevise/bespoke-overview/master

The bespoke-overview plugin presents an overview of all the slides when the kbd:[o] is pressed in a http://markdalgleish.com/projects/bespoke.js[Bespoke.js] presentation.
This overview mode gives you a “big picture” view of the presentation.
It can also be used as a navigation aid to advance to an arbitrary slide.

image::demo/screenshot.png[Screenshot of bespoke-overview]

== Download

Download the {uri-raw-file-base}/dist/bespoke-overview.min.js[production mode version] or the {uri-raw-file-base}/dist/bespoke-overview.js[development mode version], or use a <<package-managers,package manager>>.

== Example

http://opendevise.github.io/bespoke-overview[View the demo] online.

This repository includes a demo folder the shows this plugin in action.
To view it locally, you first need to clone this repository:

 $ git clone https://github.com/opendevise/bespoke-overview && cd bespoke-overview

Next, install the dependencies inside the project folder using npm:

 $ npm install

Finally, visit the file [path]_demo/index.html_ in your browser to see the plugin in action.
Press the kbd:[o] key to activate overview mode.

== Usage

This plugin is shipped in a https://github.com/umdjs/umd[UMD format], meaning that it is available as a CommonJS/AMD module or as a browser global.

For example, when using CommonJS modules:

```js
var bespoke = require('bespoke'),
  classes = require('bespoke-classes'),
  keys = require('bespoke-keys'),
  overview = require('bespoke-overview');

bespoke.from('.deck', [
  classes(),
  keys(),
  overview()
]);
```

When using browser globals:

```js
bespoke.from('.deck', [
  bespoke.plugins.classes(),
  bespoke.plugins.keys(),
  bespoke.plugins.overview()
]);
```

=== Options

The following options are available to the bespoke-plugin:

columns _(type: integer, default: 3)_::
The number of columns to use for the grid.

margin _(type: number, default: 15)_::
The spacing (in pixels) between the slides in the grid.
This value is scaled alone with the slides in overview mode.

autostart _(type: boolean, default: false)_::
A flag that controls whether the presentation starts in overview mode.

numbers _(type: boolean, default: false)_::
A flag that controls whether numbers are shown on the slides when in overview mode.
When enabled, adds the `bespoke-overview-counter` class to the deck parent element.
The style of the numbers can be controlled using the `.bespoke-overview-counter .bespoke-slide::after` CSS selector.

title _(type: boolean, default: false)_::
A flag that controls whether the presentation title is shown above the slides in overview mode.
When enabled, adds a `<header class="bespoke-title">` element as the first child of the deck parent element containing the title wrapped in a child `<h1>` element.
The title text is taken from either the `data-title` attribute on the deck parent or `document.title`.
The style of the title can be controlled using the `.bespoke-overview .bespoke-title` CSS selector.

==== Options example

Here's an example showing all the options enabled:

```
bespoke.from('.deck', [
  classes(),
  keys(),
  overview({ columns: 2, margin: 10, autostart: true, numbers: true, title: true })
]);
```

=== Plugin order

The overview plugin should be applied in the following order relative to other plugins:

* bespoke-classes
* bespoke-scale
* *bespoke-overview*
* bespoke-bullets
* bespoke-multimedia

The placement of other plugins doesn't result in any known problems.

== How it works

When the trigger key is pressed (i.e., kbd:[o]), all the slides in the presentation become visible and are arranged in a grid layout.
The number of columns in the grid is controlled by the `columns` option passed to the plugin (e.g., `overview({ columns: 4 })`, which defaults to 3.
The number of rows is determined by the number of slides in the presentation.
A scrollbar will appear on the right side of the screen, which can be used to bring slides that spill outside the visible area into view.

When the plugin is loaded, it prepends a collection of styles to the top of the HTML page, which are used to control the default behavior of the overview mode.
Note that these styles can be overridden or customized.

When the overview is activated, the `bespoke-overview` class is added to the deck parent element (the element that has the `bespoke-parent` class).
Thanks to the built-in styles, all the slides will become visible (pending any slide transitions) when the `bespoke-overview` class is added to the deck parent.
Next, a transform is applied to each slide to arrange the slides in a grid layout.
The transform consists of two properties:

translate::
sets the x, y coordinates of the slide

scale::
resizes the slide to fit within the grid

TIP: This plugin works either with or without the bespoke-scale plugin applied (in either mode).

After the overview is activated, the selected slide will automatically be scrolled into view.
A border will appear around the selected slide.
You can use the cursor to navigate through the slides in overview mode.
You'll see the selection border advance as you use the left and right arrows (kbd:[<-] and kbd:[->], respectively).
The selected slide will be scrolled into view automatically, if necessary.

NOTE: For browsers that honor the CSS https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior[scroll-behavior] property (e.g., Firefox), the slides will be scrolled into view smoothly.

There are two ways to leave overview mode.
When one of the trigger keys is pressed (i.e., kbd:[o] or kbd:[enter]), the presentation will exit from overview mode and show the selected slide in the normal (single slide) mode.
If, instead, one of the slides is clicked, the presentation will return to the normal (single slide) mode after advancing to the slide that received the click.

When overview mode is deactivated, the `bespoke-overview` class is removed from the deck parent, the scrollbar is hidden, the slides are temporarily repositioned to account for the deactivation of the scrollbar and, finally, the manual transform on each slide is removed.
(If there's a scroll offset when the overview mode is deactivated, it will appear as though the selected slide transitions from its position in the overview to its position in slide mode thanks to an interim translation of its position).

== Transitions

The bespoke-overview plugin gives you fine-grained control over the transition going to and from overview mode.
The `bespoke-overview-to` class is added to the deck parent when the overview is activated and remains there until all slide transitions, if any, are complete.
Conversely, the `bespoke-overview-from` class is added to the deck parent when the overview is deactivated and remains there until all slide transitions, if any, are complete.

IMPORTANT: The transform origin is assumed to be 50% 50% (i.e., the center of the slide).

NOTE: The `bespoke-overview` class is removed immediately when the overview mode is deactivated, whereas the `bespoke-overview-from` class remains on the deck parent element until all slide transitions, if any, are complete.

TIP: If you want to defer a style change until the transition into overview mode is complete, using the CSS selector `.bespoke-overview:not(.bespoke-overview-to)`.

.Understanding z-index values
****
If each slide is enclosed in a wrapper element that has a transform applied to it (e.g., when bespoke-scale is enabled and configured to use the transform strategy), the z-index setting on a slide will have no effect on the visual stacking order.
This happens because a wrapper element with a transform applied creates a new stacking context, which limits the scope of the z-index setting (i.e., the value only applies relative to other elements in the stacking context).
Under these conditions, the active slide may not appear on top when transitioning out of overview mode regardless of the z-index setting.
****

=== Default transitions

By default, overview mode will use the same transitions that are applied to the slides themselves.
If you do not use transitions on the slides in your presentation, then transitions will not be used when you toggle overview mode.

=== Disabling transitions

If you do have transitions on your slides (particularly on `transform`), you can disable transitions when going to and from overview mode using the following styles in your CSS file:

```css
.bespoke-overview-to .bespoke-slide,
.bespoke-overview-from .bespoke-slide {
  -webkit-transition: none;
  transition: none;
}
```

=== Custom transitions

Rather than disabling transitions, you can use the `bespoke-overview-to` and `bespoke-overview-from` classes to create distinct transitions when entering and leaving overview mode.

```css
.bespoke-overview-to .bespoke-slide {
  -webkit-transition: -webkit-transform 0.5s ease-out, opacity 0.5s ease-in-out 0.4s;
  transition: transform 0.5s ease-out, opacity 0.5s ease-in-out 0.4s;
}

.bespoke-overview-from .bespoke-slide {
  -webkit-transition: -webkit-transform 0.5s ease-in-out 0.05s, opacity 0.15s ease-in-out;
  transition: transform 0.5s ease-in-out 0.05s, opacity 0.15s ease-in-out;
}
```

=== Transitioning the title

If you enable the title, you can also use the `bespoke-overview-to` and `bespoke-overview-from` to control the transition on the title when entering and leaving overview mode.

```css
.bespoke-title {
  opacity: 0;
}

.bespoke-overview .bespoke-title {
  opacity: 1;
}

.bespoke-overview-to .bespoke-title {
  visibility: visible;
  -webkit-transition: opacity 0.5s ease-in-out 0.4s;
  transition: opacity 0.5s ease-in-out 0.4s;
}

.bespoke-overview-from .bespoke-title {
  visibility: visible;
  -webkit-transition: opacity 0.15s ease-in-out;
  transition: opacity 0.15s ease-in-out;
}
```

IMPORTANT: The `visibility` property is important as it overrides the built-in behavior necessary to work when transitions on the title are not used.

== Package managers

=== npm

```bash
$ npm install bespoke-overview
```

=== Bower

```bash
$ bower install bespoke-overview
```

== Credits

This plugin was built with https://github.com/markdalgleish/generator-bespokeplugin[generator-bespokeplugin].

== License

http://en.wikipedia.org/wiki/MIT_License[MIT License]

{'fraction_non_alphanumeric': 0.08135576969173977, 'fraction_numerical': 0.0054173258545471975, 'mean_word_length': 4.483701366982124, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '165899', 'n_tokens_mistral': 5968, 'n_tokens_neox': 5637, 'n_words': 2777}