spectacle-dragula
v2.3.14
Published
RctJS Powered Presentation Framework
Downloads
3
Readme
Spectacle
ReactJS based Presentation Library
Contents
- Getting Started
- One Page
- Development
- Build & Deployment
- Presenting
- Controls
- Fullscreen
- PDF Export
- Basic Concepts
- Tag API
- Third Party Extensions
Getting Started
The new best way to get started is by running create-react-app my-presentation --scripts-version spectacle-scripts
. This will use create-react-app
to create almost everything you need. This however, doesn't include publish scripts, and ejecting is required for fancy stuff.
The second best way to get started is by using the Spectacle Boilerplate.
Alternatively, you can npm install spectacle
and write your own build configurations. We also provide full UMD builds (with a Spectacle
global variable) of the library at dist/spectacle.js
and dist/spectacle.min.js
for more general use cases. You could, for example, include the library via a script tag with: https://unpkg.com/spectacle@VERSION/dist/spectacle.min.js
.
Note that we have webpack externals for react
, react-dom
, and prop-types
, so you will need to provide them in your upstream build or something like linking in via script
tags in your HTML page for all three libraries. This comports with our project dependencies which place these three libraries in peerDependencies
.
But really, it is SO much easier to just use the boilerplate. Trust me.
One Page
To aid with speedy development / kicking the tires on spectacle, we support using a simple boilerplate HTML page with a bespoke script tag that contains your entire presentation. The rest of the setup will take care of transpiling your React/ESnext code, providing Spectacle, React, and ReactDOM libraries, and being raring to go with a minimum of effort.
We can start with this project's sample at one-page.html
. It's essentially, the same presentation as the fully-built-from-source version, with a few notable exceptions:
There are no
import
s orrequire
s. Everything must come from the global namespace. This includesSpectacle
,React
,ReactDOM
and all the Spectacle exports from./src/index.js
--Deck
,Slide
,themes
, etc.The presentation must include exactly one script tag with the type
text/spectacle
that is a function. Presently, that function is directly inserted inline into a wrapper code boilerplate as a React Componentrender
function. The wrapper is transpiled. There should not be any extraneous content around it like outer variables or comments.Good examples:
<script type="text/spectacle"> () => ( <Deck>{/* SLIDES */}</Deck> ) </script>
<script type="text/spectacle"> () => { // Code-y code stuff in JS... return ( <Deck>{/* SLIDES */}</Deck> ); } </script>
Bad examples of what not to do:
<script type="text/spectacle"> // Outer comment (BAD) const outerVariable = "BAD"; () => ( <Deck>{/* SLIDES */}</Deck> ) </script>
... with those guidelines in mind, here's the boilerplate that you can literally copy-and-paste into an HTML file and start a Spectacle presentation that works from the get go!
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width initial-scale=1 user-scalable=no" />
<title>Spectacle</title>
<link href="https://fonts.googleapis.com/css?family=Lobster+Two:400,700" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300,700" rel="stylesheet" type="text/css">
<link href="https://unpkg.com/prismjs@1/themes/prism-tomorrow.css" rel="stylesheet" type="text/css">
<link href="https://unpkg.com/normalize.css@7/normalize.css" rel="stylesheet" type="text/css">
<link href="https://unpkg.com/spectacle/lib/themes/default/index.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="root"></div>
<script src="https://unpkg.com/prismjs@1/prism.js"></script>
<script src="https://unpkg.com/prismjs@1/components/prism-jsx.min.js"></script>
<script src="https://unpkg.com/prop-types@15/prop-types.js"></script>
<script src="https://unpkg.com/react@15/dist/react.js"></script>
<script src="https://unpkg.com/react-dom@15/dist/react-dom.js"></script>
<script src="https://unpkg.com/babel-standalone@6/babel.js"></script>
<script src="https://unpkg.com/spectacle/dist/spectacle.js"></script>
<script src="https://unpkg.com/spectacle/lib/one-page.js"></script>
<script type="text/spectacle">
() => {
// Your JS Code goes here
return (
<Deck>
{/* Throw in some slides here! */}
</Deck>
);
}
</script>
</body>
</html>
Development
After downloading the boilerplate, your first order of business is to open terminal and run npm install
Next run rm -R .git
to remove the existing version control.
Then, to start up the local server, run npm start
Open a browser and hit http://localhost:3000, and we are ready to roll
Build & Deployment
Building the dist version of the slides is as easy as running npm run build:dist
If you want to deploy the slideshow to surge, run npm run deploy
⚠️ If you are deploying the dist version to GitHub Pages, note that the built bundle uses an absolute path to the /dist/
directory while GitHub Pages requires the relative ./dist/
to find any embedded assets and/or images. A very hacky way to fix this is to edit one place in the produced bundle, as shown in this GitHub issue.
Presenting
Spectacle comes with a built in presenter mode. It shows you a slide lookahead, current time and your current slide:
Otherwise, it can also show you a stopwatch to count the elapsed time:
To present:
- Run
npm start
- Open two browser windows on two different screens
- On your screen visit http://localhost:3000/. You will be redirected to a URL containing the slide id.
- Add
presenter&
orpresenter&timer
immediately after the questionmark, e.g.: http://localhost:3000/#/0?presenter or http://localhost:3000/#/0?presenter&timer - On the presentation screen visit http://localhost:3000/
- Give an amazingly stylish presentation
Note: Any windows/tabs in the same browser that are running Spectacle will sync to one another, even if you don't want to use presentation mode
Check it out:
You can toggle the presenter or overview mode by pressing respectively alt+p
and alt+o
.
Controls
|Key Combination|Function| |---|---| |Right Arrow|Next Slide| |Left Arrow|Previous Slide| |Space|Next Slide| |Shift+Space|Previous Slide| |Alt/Option + O|Toggle Overview Mode| |Alt/Option + P|Toggle Presenter Mode| |Alt/Option + T|Toggle Timer in Presenter Mode| |Alt/Option + A|Start autoplay (if enabled)|
Fullscreen
Fullscreen can be toggled via browser options, or by hovering over the bottom right corner of your window until the fullscreen icon appears and clicking it.
PDF Export
Exporting a totally sweet looking PDF from your totally sweet looking Spectacle presentation is absurdly easy.
- Run
npm start
- Open http://localhost:3000/
- Add
export&
after the?
on the URL of page you are redirected to, e.g.: http://localhost:3000/#/?export&_k=wbyhif - Bring up the print dialog
(ctrl or cmd + p)
- Check "Background Graphics" to on if you are about that life
- Change destination to "Save as PDF", as shown below:
If you want to print your slides, and want a printer friendly version, simply repeat the above process but instead print from http://localhost:3000/?export&print
Basic Concepts
Main file
Your presentation files & assets will live in the presentation
folder.
The main .js
file you write your deck in is /presentation/index.js
Check it out here in the boilerplate.
// index.js
import React, { Component } from 'react';
import {
Appear, BlockQuote, Cite, CodePane, Code, Deck, Fill, Fit,
Heading, Image, Layout, ListItem, List, Quote, Slide, Text
} from 'spectacle';
export default class extends Component {
render() {
return (
<Deck>
<Slide>
<Text>Hello</Text>
</Slide>
</Deck>
);
}
}
Here is where you can use the library's tags to compose your presentation. While you can use any JSX syntax here, building your presentation with the supplied tags allows for theming to work properly.
The bare minimum you need to start is aDeck
element and a Slide
element. Each Slide
element represents a slide inside of your slideshow.
Themes
In Spectacle, themes are functions that return style objects for screen
& print
.
You can import the default theme from:
import createTheme from "spectacle/lib/themes/default";
Or create your own based upon the source.
index.js
is what you would edit in order to create a custom theme of your own, using ReactJS style inline style objects.
You will want to edit index.html
to include any web fonts or additional CSS that your theme requires.
createTheme(colors, fonts)
Spectacle's functional theme system allows you to pass in color and font variables that you can use on your elements. The fonts configuration object can take a string for a system font or an object that specifies it‘s a Google Font. If you use a Google Font you can provide a styles array for loading different weights and variations. Google Font tags will be automatically created. See the example below:
const theme = createTheme({
primary: "red",
secondary: "blue"
}, {
primary: "Helvetica",
secondary: { name: "Droid Serif", googleFont: true, styles: [ "400", "700i" ] }
});
The returned theme object can then be passed to the Deck
tag via the theme
prop, and will override the default styles.
Tag API
In Spectacle, presentations are composed of a set of base tags. We can separate these into three categories: Main tags, Layout tags & Element tags.
Main Tags
Deck
The Deck tag is the root level tag for your presentation. It supports the following props:
|Name|PropType|Description|
|---|---|---|
|controls| PropTypes.bool| Show control arrows when not in fullscreen
|contentHeight| PropTypes.numbers| Baseline content area height (default: 700)
|contentWidth| PropTypes.numbers| Baseline content area width (default: 1000)
|history|PropTypes.object|Accepts custom configuration for history
|progress| PropTypes.string|Accepts pacman
, bar
, number
or none
. To override the color, change the 'quarternary' color in the theme.
|theme|PropTypes.object|Accepts a theme object for styling your presentation|
|transition|PropTypes.array|Accepts slide
, zoom
, fade
or spin
, and can be combined. Sets global slide transitions. Note: If you use the 'scale' transition, fitted text won't work in Safari.|
|transitionDuration| PropTypes.number| Accepts integer value in milliseconds for global transition duration.
|autoplay|PropTypes.bool| Automatically advance slides.
|autoplayDuration|PropTypes.number| Accepts integer value in milliseconds for global autoplay duration, defaults to 7000.
Slide (Base)
The slide tag represents each slide in the presentation. Giving a slide tag an id
attribute will replace its number based navigation hash with the id
provided. It supports the following props, in addition to any of the props outlined in the Base class props listing:
|Name|PropType|Description|
|---|---|---|
|align| PropTypes.string | Accepts a space delimited value for positioning interior content. The first value can be flex-start
(left), center
(middle), or flex-end
(right). The second value can be flex-start
(top) , center
(middle), or flex-end
(bottom). You would provide this prop like align="center center"
, which is its default.
|id| PropTypes.string | Used to create a string based hash.
|maxHeight| PropTypes.number | Used to set max dimensions of the Slide.
|maxWidth| PropTypes.number | Used to set max dimensions of the Slide.
|notes| PropTypes.string| Text which will appear in the presenter mode. Can be HTML.
|transition|PropTypes.array|Accepts slide
, zoom
, fade
or spin
, and can be combined. Sets the slide transition. Note: If you use the 'scale' transition, fitted text won't work in Safari.|
|transitionDuration| PropTypes.number| Accepts integer value in milliseconds for slide transition duration.
Notes
The notes tag allows to use any tree of react elements as the notes of a slide. It is used as a child node of a slide tag and its children override any value given as the notes
attribute of its parent slide.
<Slide ...>
<Notes>
<h4>Slide notes</h4>
<ol>
<li>First note</li>
<li>Second note</li>
</ol>
</Notes>
{/* Slide content */}
</Slide>
MarkdownSlides
The MarkdownSlides function lets you create a single or multiple slides using Markdown. It can be used as a tagged template literal or a function. Three dashes (---
) are used as a delimiter between slides.
Tagged Template Literal Usage
<Deck ...>
{MarkdownSlides`
## Slide One Title
Slide Content
---
## Slide Two Title
Slide Content
`}
</Deck>
Function Usage
import slidesMarkdown from "raw!markdown.md";
<Deck ...>
{MarkdownSlides(slidesMarkdown)}
</Deck>
Layout Tags
Layout tags are used for layout using Flexbox within your slide. They are Layout
, Fit
& Fill
.
Layout
The layout tag is used to wrap Fit
and Fill
tags to provide a row.
Fit
The fit tag only takes up as much space as its bounds provide.
Fill
The fill tag takes up all the space available to it. For example, if you have a Fill
tag next to a Fit
tag, the Fill
tag will take up the rest of the space. Adjacent Fill
tags split the difference and form an equidistant grid.
Markdown Tag
Markdown
The Markdown tag is used to add inline markdown to your slide. You can provide markdown source via the source
prop, or as children. You can also provide a custom mdast configuration via the mdastConfig
prop.
Markdown generated tags aren't prop configurable, and instead render with your theme defaults.
|Name|PropType|Description| |---|---|---| |source|PropTypes.string| Markdown source |
Element Tags
The element tags are the bread and butter of your slide content. Most of these tags derive their props from the Base class, but the ones that have special options will have them listed:
Appear
This tag does not extend from Base. It's special. Wrapping elements in the appear tag makes them appear/disappear in order in response to navigation.
BlockQuote, Quote and Cite (Base)
These tags create a styled blockquote. Use them as follows:
<BlockQuote>
<Quote>Ken Wheeler is amazing</Quote>
<Cite>Everyone</Cite>
</BlockQuote>
CodePane (Base)
This tag displays a styled, highlighted code preview. I prefer putting my code samples in external .example
files and requiring them using raw-loader
as shown in the demo. Here are the props:
|Name|PropType|Description| |---|---|---| |lang|PropTypes.string| Prism compatible language name. i.e: 'javascript' | |source| PropTypes.string| String of code to be shown |
You can change your syntax highlighting theme by swapping the prism.js CSS file in index.html
Code (Base)
A simple tag for wrapping inline text that you want lightly styled in a monospace font.
Component Playground
This tag displays a two-pane view with a ES6 source code editor on the right and a preview pane on the left for showing off custom React components. React
and render
from ReactDOM
are supplied as variables. To render a component use the domContainer mountNode
. Any console
output will be forwarded to the main console in the browser.
|Name|PropType|Description|
|---|---|---|
|code|PropTypes.string|The code block you want to initially supply to the component playground. If none is supplied a demo component will be displayed.|
|previewBackgroundColor|PropTypes.string|The background color you want for the preview pane. Defaults to #fff
.|
|theme|PropTypes.string|Accepts light
or dark
for the source editor's syntax highlighting. Defaults to light
.|
|scope|PropTypes.object|Defines any outside modules or components to expose to the playground. React, Component, and render are supplied for you.|
Example code blocks:
const Button = ({ title }) => (<button type="button">{ title }</button>);
render(<Button title="My Button" />, mountNode);
class View extends React.Component {
componentDidMount() {
console.log("Hello");
}
render() {
return (<div>My View</div>);
}
}
render(<View />, mountNode);
Heading (Base)
Heading tags are special in that, when you specify a size
prop, they generate the appropriate heading tag, and extend themselves with a style that is defined in the theme file for that heading. Line height can be adjusted via a numeric lineHeight
prop.
|Name|PropType|Description| |---|---|---| |fit|PropTypes.boolean| When set to true, fits text to the slide's width. Note: If you use the 'scale' transition, this won't work in Safari. | |lineHeight|PropTypes.number| Sets the line height of your text.|
Image (Base)
|Name|PropType|Description| |---|---|---| |display|PropTypes.string| Set the display style property of the image | |height|PropTypes.string or PropTypes.number| Supply a height to the image | |src|PropTypes.string| Image src | |width|PropTypes.string or PropTypes.number| Supply a width to the image |
Link (Base)
The link tag is used to render <a>
tags. It accepts an href
prop:
|Name|PropType|Description|
|---|---|---|
|href|PropTypes.string| String of url for href
attribute |
|target|PropTypes.string| Set the target
attribute |
List & ListItem (Base)
|Name|PropType|Description|
|---|---|---|
|ordered|PropTypes.bool| Render as <ol>
-tag|
|reversed|PropTypes.bool| Set the reversed
attribute |
|start|PropTypes.bool| Set the start
attribute, Default: 1 |
|type|PropTypes.bool| Set the type
attribute. Default: "1" |
These tags create lists. Use them as follows:
Ordered lists:
<List ordered start={2} type="A">
<ListItem>Item 1</ListItem>
<ListItem>Item 2</ListItem>
<ListItem>Item 3</ListItem>
<ListItem>Item 4</ListItem>
</List>
Unordered lists:
<List>
<ListItem>Item 1</ListItem>
<ListItem>Item 2</ListItem>
<ListItem>Item 3</ListItem>
<ListItem>Item 4</ListItem>
</List>
S (Base)
The S
tag is used to add inline styling to a piece of text, such as underline or strikethrough.
|Name|PropType|Description|
|---|---|---|
|type|PropTypes.string| Accepts strikethrough
, underline
, bold
or italic
|
Table, TableRow, TableHeaderItem and TableItem (Base)
The Table
tag is used to add table to your slide. It is used with TableHeader
, TableBody
, TableRow
, TableHeaderItem
and TableItem
. Use them as follows:
<Table>
<TableHeader>
<TableRow>
<TableHeaderItem></TableHeaderItem>
<TableHeaderItem>2011</TableHeaderItem>
</TableRow>
</TableHeader>
<TableBody>
<TableRow>
<TableItem>None</TableItem>
<TableItem>61.8%</TableItem>
</TableRow>
<TableRow>
<TableItem>jQuery</TableItem>
<TableItem>28.3%</TableItem>
</TableRow>
</TableBody>
</Table>
Text (Base)
The Text
tag is used to add text to your slide. Line height can be adjusted via a numeric lineHeight
prop.
|Name|PropType|Description| |---|---|---| |fit|PropTypes.boolean| When set to true, fits text to the slide's width. Note: If you use the 'scale' transition, this won't work in Safari. | |lineHeight|PropTypes.number| Sets the line height of your text.|
Base Props
Every component above that has (Base)
after it has been extended from a common class that includes the following props:
| Name | PropType | Description |
| ---- | -------- | ----------- |
| italic | PropTypes.boolean | Set fontStyle
to italic
|
| bold | PropTypes.boolean | Set fontWeight
to bold
|
| caps | PropTypes.boolean | Set textTransform
to uppercase
|
| margin | PropTypes.number or string | Set margin
value|
| padding | PropTypes.number or string | Set padding
value|
| textColor | PropTypes.string | Set color
value|
| textSize | PropTypes.string | Set fontSize
value|
| textAlign | PropTypes.string | Set textAlign
value|
| textFont | PropTypes.string | Set textFont
value|
| bgColor | PropTypes.string | Set backgroundColor
value|
| bgImage | PropTypes.string | Set backgroundImage
value|
| bgDarken | PropTypes.number | Float value from 0.0 to 1.0 specifying how much to darken the bgImage image|
Typeface
The Typeface
tag is used to apply a specific font to text content. It can either use a font that exists on the system or load a font from the Google Fonts library. Typeface
requires either font
or googleFont
to be defined.
| Name | PropType | Description |
| ---- | -------- | ----------- |
| font | PropTypes.string | Use a font from the local system |
| googleFont | PropTypes.string | Use a font from the Google Fonts library |
| weight | PropTypes.number | Numeric weight value for the font. Default: 400
. |
| italic | PropTypes.boolean | Use an italics variant of the font if it exists. Default: false
. |
<Typeface googleFont="Roboto Slab" weight={600}>
<Text>This text is using bold Roboto Slab from Google Fonts.</Text>
</Typeface>
<Typeface font="SF Text" weight={400} italic={true}>
<Text>This text is using the San Francisco Text font from the system.</Text>
</Typeface>
Third Party Extensions
- Spectacle Code Slide - Step through lines of code using this awesome slide extension by @thejameskyle
- Spectacle Terminal Slide - Terminal component that can be used in a spectacle slide deck by @elijahmanor
- Spectacle Image Slide - Show a slide with a big image and a title on top