janishutz-legacy/impress.js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

restructure, move to TS

Browse Source
This commit is contained in:
Janis Hutz
2024-01-08 20:37:18 +01:00
parent 125ab80766
commit 90653fa34e
9 changed files with 344 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
docs/DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,411 @@
# Reference API
## HTML
### Root Element
impress.js requires a Root Element. All the content of the presentation will be created inside that element. It is not recommended to manipulate any of the styles, attributes or classes that are created by impress.js inside the Root Element after initialization.
To change the duration of the transition between slides use `data-transition-duration="2000"` giving it
a number of ms. It defaults to 1000 (1s).
When authoring impress.js presentations, you should target some screen size, which you can define here.
The default is 1024 x 768. You should write your CSS as if this is the screen size used for the
presentation. When you present your presentation on a screen (or browser window) of different size,
impress.js will automatically scale the presentation to fit the screen. The minimum and maximum limits
to this scaling can also be defined here.
All impress.js steps are wrapped inside a div element of 0 size! This means that in your CSS you
can't use relative values for width and height (example: `width: 100%`) to define the size of step elements.
You need to use pixel values. The pixel values used here correspond to the `data-width` and `data-height`
given to the `#impress` root element. When the presentation is viewed on a larger or smaller screen, impress.js
will automatically scale the steps to fit the screen.
**NOTE:** The default width and height have been changed to target HD screens in v1.2.0. If you
don't set target width and height explicitly, layout and dimensions of your presentations are likely
to be affected. In order to get back the old target resolution, use:
<div id="impress" data-width="1024" data-height="768" data-max-scale="1" data-min-scale="0"
You can also control the perspective with `data-perspective="500"` giving it a number of pixels.
It defaults to 1000. You can set it to 0 if you don't want any 3D effects.
If you are willing to change this value make sure you understand how CSS perspective works:
https://developer.mozilla.org/en/CSS/perspective
See also [the plugin README](src/plugins/README.md) for documentation on `data-autoplay`.
**Attributes**
Attribute | Default | Explanation
-------------------------|-----------|------------
data-transition-duration | 1000 (ms) | Speed of transition between steps.
data-width | 1920 (px) | Width of target screen size. When presentation is viewed on a larger or smaller screen, impress.js will scale all content automatically.
data-height | 1080 (px) | Height of target screen size.
data-max-scale | 3 | Maximum scale factor. (Note that the default 1 will not increase content size on larger screens!)
data-min-scale | 0 | Minimum scale factor.
data-perspective | 1000 | Perspective for 3D rendering. See https://developer.mozilla.org/en/CSS/perspective
**Example:**
```html
<div id="impress"
data-transition-duration="1000"
data-width="1024"
data-height="768"
data-max-scale="3"
data-min-scale="0"
data-perspective="1000"
data-autoplay="7">
```
### Step Element
A Step Element is an element that contains metadata that defines how it is going to be presented in the screen.
A Step Element should contain a `.step` class and an optional `id` attribute.
The content represents an html fragment that will be positioned at the center of the camera.
In the Step Element, you can define a specific set of default attributes and positioning, that are documented below.
**Example:**
```html
<div id="bored" class="step" data-x="-1000">
<q>Aren’t you just <b>bored</b> with all those slides-based presentations?</q>
</div>
```
#### 2D Coordinates Positioning (data-x, data-y)
Define the pixel based position in which the **center** of the [Step Element](#step-element) will be positioned inside the infinite canvas.
**Attributes**
Attribute | Default | Explanation
-------------------------|-----------|------------
data-x | 0 | X coordinate for step position
data-y | 0 | Y coordinate for step position
**Example:**
```html
<div id="bored" class="step" data-x="-1000" data-y="-1500">
<q>Aren’t you just <b>bored</b> with all those slides-based presentations?</q>
</div>
```
#### 2D Scaling (data-scale)
Defines the scaling multiplier of the [Step Element](#step-element) relative to other Step Elements. For example, `data-scale="4"` means that the element will appear to be 4 times larger than the others. From the presentation and transitions point of view, it means that it will have to be scaled down (4 times) to make it back to its correct size.
**Example:**
```html
<div id="title" class="step" data-x="0" data-y="0" data-scale="4">
<span class="try">then you should try</span>
<h1>impress.js<sup>*</sup></h1>
<span class="footnote"><sup>*</sup> no rhyme intended</span>
</div>
```
#### 2D Rotation (data-rotate)
Represents the amount of clockwise rotation of the element relative to 360 degrees.
**Example:**
```html
<div id="its" class="step" data-x="850" data-y="3000" data-rotate="90" data-scale="5">
<p>
It’s a <strong>presentation tool</strong> <br>
inspired by the idea behind <a href="http://prezi.com">prezi.com</a> <br>
and based on the <strong>power of CSS3 transforms and transitions</strong> in modern browsers.
</p>
</div>
```
#### 3D Coordinates Positioning (data-z)
Define the pixel based position in which the **center** of the [Step Element](#step-element) will be positioned inside the infinite canvas on the third dimension (Z) axis. For example, if we use `data-z="-3000"`, it means that the [Step Element](#step-element) will be positioned far away from the camera (by 3000px).
**Example:**
```html
<div id="tiny" class="step" data-x="2825" data-y="2325" data-z="-3000" data-rotate="300" data-scale="1">
<p>and <b>tiny</b> ideas</p>
</div>
```
**Note:** The introduction of the [rel](src/plugins/rel/README.md) plugin includes a slight backward incompatible change.
Previously the default value for `data-x`, `data-y` and `data-z` was zero. The `rel` plugin changes the default to inherit
the value of the previous slide. This means, you need to explicitly set these values to zero, if they ever were non-zero.
#### 3D Rotation (data-rotate-x, data-rotate-y, data-rotate-z)
You can not only position a [Step Element](#step-element) in 3D, but also rotate it around any axis.
**Example:**
The example below will get rotated by -40 degrees (40 degrees anticlockwise) around X axis and 10 degrees (clockwise) around Y axis.
You can of course rotate it around Z axis with `data-rotate-z` - it has exactly the same effect as `data-rotate` (these two are basically aliases).
```HTML
<div id="its-in-3d" class="step" data-x="6200" data-y="4300" data-z="-100" data-rotate-x="-40" data-rotate-y="10" data-scale="2">
<p>
<span class="have">have</span>
<span class="you">you</span>
<span class="noticed">noticed</span>
<span class="its">it’s</span>
<span class="in">in</span>
<b>3D<sup>*</sup></b>?
</p>
<span class="footnote">* beat that, prezi ;)</span>
</div>
```
#### 3D Rotation Order (data-rotate-order)
The order in which the CSS `rotateX(), rotateY(), rotateZ()` transforms are applied matters. This is because each rotation is relative to the then current position of the element.
By default the rotation order is `data-rotate-order="xyz"`. For some advanced uses you may need to change it. The demo presentation [3D rotations](examples/3D-rotations/index.html) sets this attribute to rotate some steps into positions that are impossible to reach with the default order.
## CSS
### 4D States (.past, .present and .future classes)
The `.future` class is added to all [Step Elements](#step-element) that haven't been visited yet.
**Example:**
```CSS
.future {
display: none;
}
```
The `.present` class is added to the [Step Element](#step-element) that is currently at the center of the camera. This is useful to create animations inside the step once the camera navigates to it.
**Example:**
```CSS
.present .rotating {
transform: rotate(-10deg);
transition-delay: 0.25s;
}
```
The `.past` class is added to all [Step Elements](#step-element) that have been visited at least once.
**Example:**
```CSS
.past {
display: none;
}
```
### Current Active Step (.active class)
The `.active` class is added to the [Step Element](#step-element) that is currently visible at the center of the camera.
**Example:**
```CSS
.step {
opacity: 0.3;
transition: opacity 1s;
}
.step.active {
opacity: 1
}
```
At the same time, the `impress-on-*` class is added to the body element, the class name represents the active [Step Element](#step-element) id. This allows for custom global styling, since you can't match a CSS class backwards from the active [Step Element](#step-element) to the `body`.
**Example:**
```CSS
.impress-on-overview .step {
opacity: 1;
cursor: pointer;
}
.impress-on-step-1,
.impress-on-step-2,
.impress-on-step-3 {
background: LightBlue;
}
```
### Progressive Enhancement (.impress-not-supported class)
The `.impress-not-supported` class is added to the `body` element if the browser doesn't support the features required by impress.js to work, it is useful to apply some fallback styles in the CSS.
It's not necessary to add it manually on the `body` element. If the script detects that the browser lacks important features it will add this class.
It is recommended to add the class manually to the `body` element though, because that means that users without JavaScript will also get fallback styles. When impress.js script detects that the browser supports all required features, the `.impress-not-support` class will be removed from the `body` element.
**Example:**
```CSS
.impress-not-supported .step {
display: inline-block;
}
```
## Plugins
Many new features are implemented as plugins. The [Plugins documentation](src/plugins/README.md) is the starting place to learn about those, as well as the README.md of [each plugin](src/plugins/).
## JavaScript
### impress( [ id ] )
A factory function that creates the [ImpressAPI](#impressapi).
Accepts a [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) that represents the id of the root element in the page. If omitted, impress.js will lookup for the element with the id "impress" by default.
**Example:**
```JavaScript
var impressAPI = impress( "root" );
```
### ImpressAPI
The main impress.js API that handles common operations of impress.js, listed below.
#### .init()
Initializes impress.js globally in the page. Only one instance of impress.js is supported per document.
**Example:**
```JavaScript
impress().init();
```
Triggers the `impress:init` event in the [Root Element](#root-element) after the presentation is initialized.
**Example:**
```JavaScript
var rootElement = document.getElementById( "impress" );
rootElement.addEventListener( "impress:init", function() {
console.log( "Impress init" );
});
impress().init();
```
#### .tear()
Resets the DOM to its original state, as it was before `init()` was called.
This can be used to "unload" impress.js. A particular use case for this is, if you want to do
dynamic changes to the presentation, you can do a teardown, apply changes, then call `init()`
again. (In most cases, this will not cause flickering or other visible effects to the user,
beyond the intended dynamic changes.)
**Example:**
```JavaScript
impress().tear();
```
#### .next()
Navigates to the next step of the presentation using the [`goto()` function](#impressgotostepindexstepelementidstepelement-duration).
**Example:**
```JavaScript
var api = impress();
api.init();
api.next();
```
#### .prev()
Navigates to the previous step of the presentation using the [`goto()` function](#impressgotostepindexstepelementidstepelement-duration).
**Example:**
```JavaScript
var api = impress();
api.init();
api.prev();
```
#### .goto( stepIndex | stepElementId | stepElement, [ duration ] )
Accepts a [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) that represents the step index.
Navigates to the step given the provided step index.
**Example:**
```JavaScript
var api = impress();
api.init();
api.goto(7);
```
Accepts a [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) that represents the [Step Element](#step-element) id.
Navigates to the step given the provided [Step Element](#step-element) id.
**Example:**
```JavaScript
var api = impress();
api.init();
api.goto( "overview" );
```
Accepts an [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) that represents the [Step Element](#step-element).
Navigates to the step given the provided [Step Element](#step-element).
**Example:**
```JavaScript
var overview = document.getElementById( "overview" );
var api = impress();
api.init();
api.goto( overview );
```
Accepts an optional [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) in the last argument that represents the duration of the transition in milliseconds. If not provided, the default transition duration for the presentation will be used.
Triggers the `impress:stepenter` event in the [Root Element](#root-element) when the presentation navigates to the target [Step Element](#step-element).
**Example:**
```JavaScript
var rootElement = document.getElementById( "impress" );
rootElement.addEventListener( "impress:stepenter", function(event) {
var currentStep = event.target;
console.log( "Entered the Step Element '" + currentStep.id + "'" );
});
```
Triggers the `impress:stepleave` event in the [Root Element](#root-element) when the presentation navigates away from the current [Step Element](#step-element).
**Example:**
```JavaScript
var rootElement = document.getElementById( "impress" );
rootElement.addEventListener( "impress:stepleave", function(event) {
var currentStep = event.target;
var nextStep = event.detail.next;
console.log( "Left the Step Element '" + currentStep.id + "' and about to enter '" + nextStep.id );
});
```
# Improve The Docs
Did you find something that can be improved? Then [create an issue](https://github.com/impress/impress.js/issues/new) so that we can discuss it!

167
docs/GettingStarted.md Normal file
View File

@@ -0,0 +1,167 @@
# Introduction
Welcome to impress.js! This presentation framework allows you to create stunning presentations with the power of CSS3 transformations.
**NOTE:** This Guide is not made for you, if you have never written HTML and/or CSS before. Knowing your way around in JavaScript certainly helps, but is not a necessity. You may still continue this tutorial and try to understand what we do as you go.
For more advanced and complete documentation, you might prefer the [DOCUMENTATION](DOCUMENTATION.md).
# Getting started with impress.js
## Installation / acquiring the framework
First of all, you need to know, if you are going to have WiFi connection when you hold your presentation. If you are not sure, please use the method where you download the file instead of the cdn.
### Including from cdn
Loading the script from the cdn is quite straight forward. If you copy the below example code, you need to do nothing else, impress will be loaded automatically.
**Direct links to different versions of the impress.js file**
- V2.0.0: https://cdn.jsdelivr.net/gh/impress/impress.js@2.0.0/js/impress.js
- V1.1.0: https://cdn.jsdelivr.net/gh/impress/impress.js@1.1.0/js/impress.js
- Source: https://cdn.jsdelivr.net/gh/impress/impress.js/js/impress.js
### Download the file to your PC
Head to the releases tab and download the source code as zip or as a tarball. Go ahead and unzip / untar it. You need to copy the folder */js/* into the folder you are working in. Optionally, if you want to make your life a bit easier, you can copy also copy the folder */css/* in there.
## Setting up the project
Open up your favorite text-editor / IDE, for example Visual Studio Code, Atom, Notepad ++, ...
Now, create a new file called *index.html* and create the basic HTML structure:
```
<!DOCTYPE html>
<html>
<head>
<title>My first presentation</title>
<link rel="stylesheet" href="./css/impress-common.css"><!--Leave out, if you don't use impress-common.css-->
</head>
<body class="impress-not-supported">
<div class="fallback-message">
<p>Your browser <b>doesn't support the features required</b> by impress.js, so you are presented with a simplified version of this presentation.</p>
<p>For the best experience please use the latest <b>Chrome</b>, <b>Safari</b> or <b>Firefox</b> browser.</p>
</div>
<div id="impress">
<div id="myFirstSlide" class="step">
<h1>My first Slide</h1>
</div>
</div>
<script src="js/impress.js"></script>
<script>window.impress || document.write('<script src="https://cdn.jsdelivr.net/gh/impress/impress.js@2.0.0/js/impress.js">\x3C/script>');</script>
<script>impress().init()</script>
</body>
</html>
```
Now, head into a file-manager, navigate to the file you just created (*index.html*) and open it. You should end up in a browser where you should see "My first Slide" displayed. As this is not really exciting, we are not gonna change anything about that and are gonna look at what you just typed. What do these lines mean?
Well, first things first, you should probably give your presentation a title. You may do this in normal HTML fashion by changing the *title* HTML tag.
So now, we reached the HTML body. You can see that it already belongs to a class. This class just tells impress.js that this is the body where the "fallback-message" should be displayed when it detects, that your browser does not support CSS3 and therefore impress.js won't work. You can easily omit that class though, including the "fallback-message" div with its content, if you only intend to use the presentation for yourself and you know about the fact that some browsers might not work.
Now, probably the most important part of all is the *div* that belongs to the ```impress``` class. This *div* should contain all the HTML code you write, as everything outside that class will not be animated by impress.js.
Finally, we load the ```impress.js``` script from your local copy (if you have one) or from the cdn, if you do not have a local copy and execute
```
impress().init()
```
to initialize impress.js. Now, let's continue on to explore more and more features of this amazing tool!
## Creating slides
Creating slides is fairly easy. You create a *div* that belongs to the class ```step``` and you are off to the races! Let me give you an example:
```
<div class="step">
Hello World
</div>
```
Now, if you reload the presentation, you start to see a \*slight\* problem. All your text is stacked... How do we work around that?
Obviously, impress.js has an answer to it. You can add the following additional attributes to your div, to make it work:
Attribute | Explanation
----------------|------------
data-x | Position the element along the x-axis (from left to right)
data-y | Position the element along the y-axis (from top to bottom)
data-z | Position the element along the z-axis (3D-Effect, move the element behind another one)
data-rotate | Rotate the element (if not using data-z!)
data-rotate-x | Rotate the element along the x-axis
data-rotate-y | Rotate the element along the y-axis
data-rotate-z | Rotate the element along the z-axis
data-scale | Scale the element.
These are the basic positioning options in impress.js. All of the attributes take Strings as arguments, so be aware of the fact, that you need to put quotation marks around the numbers! The *data-rotate* attributes take an angle in form of a String as argument.
Now, that you have created the slides, you might want to style them. This is where CSS comes into play. Add another file to your project called, e.g., ```style.css```.
**NOTE:** Whatever you do, do not mess with positioning and rotation of the div that belongs to the class *step*, but add a div inside of it, if you really have to mess with these properties. See the example below. Always position *steps* with the *data-* attribute!
```
<div class="step yourClassNameHere" data-x="1000" data-y="1000" data-z="-1000" data-scale="2" data-rotate-z="90">
<div class="yourSubClassNameHere">
<h1>Powerful, yet still simple</h1>
</div>
</div>
```
**NOTE:** You may also use negative numbers for all these properties!
## More advanced features
You might want to change some default settings, like the transition speed, the width & height of the target screen, etc. This table is from the [DOCUMENTATION](DOCUMENTATION.md) and was slightly adapted.
Attribute | Default | Explanation
-------------------------|-----------|------------
data-transition-duration | 1000 (ms) | Speed of transition between steps.
data-width | 1920 (px) | Width of target screen size. When presentation is viewed on a larger or smaller screen, impress.js will scale all content automatically.
data-height | 1080 (px) | Height of target screen size.
data-max-scale | 3 | Maximum scale factor. (Note that the default 1 will not increase content size on larger screens!)
data-min-scale | 0 | Minimum scale factor.
data-perspective | 1000 | Perspective for 3D rendering. See https://developer.mozilla.org/en/CSS/perspective
### **Renaming Steps**
You can give each step an ID. The name of the ID will be displayed in the browsers navigation bar instead of the default *step-x* whereas x is replaced by the current step number. This can be especially helpful, when trying to jump between steps and go back to a previous one. If you want to know how to move to a specific slide, you should take a look at the [README](./src/plugins/goto/README.md) of the "Goto" plugin.
# Using PLUGINS
Impress.js is limited to everything that we have discussed so far and some other details, we won't go over here. Check the [DOCUMENTATION](DOCUMENTATION.md) for that.
impress.js has accumulated a lot of very useful plugins. You may find all of them [here](./src/plugins/)!
Each Plugin has a README.md file which you may read to get an idea on how to use them. Some of the plugins run unnoticed in the background, like the *resize* plugin, which automatically resizes the presentation whenever the browser window changed in size. Here, I will give you an overview of some of the plugins that impress.js includes by default.
**NOTE:** As previously mentioned, if you'd like to get more info about how it works, take a look at the [DOCUMENTATION](DOCUMENTATION.md) or the README.md files of the plugins.
## [impressConsole](/src/plugins/impressConsole/README.md)
This plugin opens up and additional browser tab which contains a speaker console. There you can see the current slide, the past slide and your notes. You add notes to your presentation by adding a *div* that belongs to the class "notes" to your *div* that belongs to the class "step".
### **adding notes to your presentation**
You may add notes to your presentation by adding a div of class *notes* into the div of class *step*, like so:
```
<div class="step">
Some text that is being displayed on your slides
<div class="notes">
this won't be displayed in your presentation
</div>
</div>
```
Now that you have added the notes to your HTML, it is time to hide them. You need to add the following code to your CSS file (or in the style tag in the header):
```
.notes {
display: none;
}
```
To enter it, press P.
## [Goto](/src/plugins/goto/README.md)
This plugin allows you to directly go to a certain step, by either passing in a number or the id of the step you'd like to go to.
## [Progress](/src/plugins/progress/README.md)
This plugin, as its name implies, displays the progress in your presentation.
## [Blackout](/src/plugins/blackout/blackout.js)
This plugin hides the screen, if you press B, which is handy in a lot of situations.
## Other plugins
You may find the other plugins [here](/src/plugins/). It certainly helps if you familiarise yourself with the plugins.
# Thank you for reading this
If you want to know more, you can always ready the [DOCUMENTATION](DOCUMENTATION.md) or, even better, read the Source Code and try to understand how it works!

44
docs/npm-readme.md Normal file
View File

@@ -0,0 +1,44 @@
# impress.js
**What is impress.js?**
impress.js is a javascript framework that uses the power of CSS 3 transforms and transitions in today's browsers and is inspired by the idea behind [prezi.com](https://prezi.com).
**WARNING**
impress.js may not help you if you have nothing interesting to say ;)
# How to use it
Run `npm i impress.js` to get the framework or head to our GitHub page and follow the instructions in the [README](/README.md) there. You may also use one of the links provided down below to include the script directly from a cdn. *Note:* This might not always work, so if it doesn't, just download the file and put it into a folder on your hard drive.
## Direct links to only impress.js file
- V2.0.0: https://cdn.jsdelivr.net/gh/impress/impress.js@2.0.0/js/impress.js
- V1.1.0: https://cdn.jsdelivr.net/gh/impress/impress.js@1.1.0/js/impress.js
- Source: https://cdn.jsdelivr.net/gh/impress/impress.js/js/impress.js
For older versions, please just replace the version number behind the @!
## Getting Started guide
Alternative download instructions that are more exhaustive are also included in our new [Getting Started](/GettingStarted.md) file where you can also get an introduction to impress.js.
## Demos
You can see a demo of the framework in action [here](https://impress.js.org). Additional examples may be found [here](https://impress.js.org/examples).
# Browser Support
The design goal for impress.js has been to showcase awesome CSS3 features as found in modern browser versions. We also use some new DOM functionality, and specifically do not use jQuery or any other JavaScript libraries, nor our own functions, to support older browsers. In general, recent versions of Firefox and Chrome are known to work well. Reportedly IE now works too.
The typical use case for impress.js is to create presentations that you present from your own laptop, with a browser version you know works well. Some people also use impress.js successfully to embed animations or presentations in a web page, however, be aware that in this some of your visitors may not see the presentation correctly, or at all.
In particular, impress.js makes use of the following JS and CSS features:
- [DataSet API](http://caniuse.com/#search=dataset)
- [ClassList API](http://caniuse.com/#search=classlist)
- [CSS 3D Transforms](http://caniuse.com/#search=css%203d)
- [CSS Transitions](http://caniuse.com/#search=css%20transition)
# COPYRIGHT AND LICENSE
Copyright 2011-2016 Bartek Szopka
Copyright 2015-present Henrik Ingo
Released under the MIT [License](https://github.com/impress/impress.js/blob/HEAD/LICENSE)