From 9889fd4d383a69d88c2b6381be0c5f1504057ddc Mon Sep 17 00:00:00 2001 From: janis Date: Tue, 29 Nov 2022 19:20:19 +0100 Subject: [PATCH 01/70] Added a Getting Started guide --- GettingStarted.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 GettingStarted.md diff --git a/GettingStarted.md b/GettingStarted.md new file mode 100644 index 000000000..7ad4cc75b --- /dev/null +++ b/GettingStarted.md @@ -0,0 +1,132 @@ +# Introduction +Welcome to impress.js! This presentation framework allows you to create stunning presentations with the power of CSS3 transformations. It is inspired by the idea behind [prezi.com](https://prezi.com). +**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, as we won't go over how you may use JavaScript in conjunction with this framework here. You may still continue this tutorial and try to understand what we do as you go. + +Also, if you are an experienced (or sorta experienced user, anyway), you might prefer the [DOCUMENTATION] (DOCUMENTATION.md). + +# Getting started with impress.js +## Installation / acquiring the framework +You first need to decide if you want to use the bleeding edge (most up to date, but higher risk of experiencing problems) or the stable release. + +### **Stable release:** +Head to the releases tab and download the source code as zip or as a tarball. Go ahead and unzip / untar it. You may find the framework under ```/js/impress.js.``` + +### **Bleeding Edge:** +In the github repository, click the "Code"-Button, then click "Download ZIP". Go ahead and unzip / untar it. You may find the framework under ```/js/impress.js.``` + +## Setting up the project +Open up your favorite text-editor / IDE, for example Visual Studio Code, Atom, Notepad ++, ... +Now, copy the *impress.js* file into the folder you are working in and create a new file called *index.html* and create the basic HTML layout: + +``` + + + + + + +
+

Your browser doesn't support the features required by impress.js, so you are presented with a simplified version of this presentation.

+

For the best experience please use the latest Chrome, Safari or Firefox browser.

+
+ +
+
+

My first Slide

+
+
+ + - - - -``` - -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 not, 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 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: -``` -
-Hello World -
-``` - -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:** It is not intended that you modify the CSS properties of the built-in class *step*. Instead add another class to that element and style that class. See the example below. - -``` -
-

Powerful, yet still simple

-
-``` -**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 [DOCUMENTATION](DOCUMENTATION.md). This functionality is part 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. - -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 -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". - -To enter it, press P. - -## Goto -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 -This plugin, as its name implies, displays the progress in your presentation. - -## Blackout -This plugin hides the screen, if you press B, which is handy in a lot of situations. - - -# 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! \ No newline at end of file From 7f6b1ab8fd049e4a2de09e4171f62030e6375f60 Mon Sep 17 00:00:00 2001 From: janis Date: Mon, 12 Dec 2022 18:04:52 +0100 Subject: [PATCH 14/70] remove code from other pr --- js/impress.js | 6 ------ src/plugins/impressConsole/impressConsole.js | 6 ------ 2 files changed, 12 deletions(-) diff --git a/js/impress.js b/js/impress.js index 3eec7cf4b..6a865c82b 100644 --- a/js/impress.js +++ b/js/impress.js @@ -2565,12 +2565,6 @@ ( function( document, window ) { 'use strict'; - var notes = window.document.getElementsByClassName( 'notes' ); - - for ( let items in Object.entries( notes ).values ) { - items.style.display = 'none'; - } - // TODO: Move this to src/lib/util.js var triggerEvent = function( el, eventName, detail ) { var event = document.createEvent( 'CustomEvent' ); diff --git a/src/plugins/impressConsole/impressConsole.js b/src/plugins/impressConsole/impressConsole.js index 6a1eb21ac..c00ee6732 100644 --- a/src/plugins/impressConsole/impressConsole.js +++ b/src/plugins/impressConsole/impressConsole.js @@ -16,12 +16,6 @@ ( function( document, window ) { 'use strict'; - var notes = window.document.getElementsByClassName( 'notes' ); - - for ( let items in Object.entries( notes ).values ) { - items.style.display = 'none'; - } - // TODO: Move this to src/lib/util.js var triggerEvent = function( el, eventName, detail ) { var event = document.createEvent( 'CustomEvent' ); From 0e72ee634d8cf7d46bab6e056539e0e5989c54e4 Mon Sep 17 00:00:00 2001 From: janis Date: Mon, 12 Dec 2022 19:46:02 +0100 Subject: [PATCH 15/70] added plugins getting started guide --- src/plugins/GettingStarted.md | 608 ++++++++++++++++++++++++++++++++++ 1 file changed, 608 insertions(+) create mode 100644 src/plugins/GettingStarted.md diff --git a/src/plugins/GettingStarted.md b/src/plugins/GettingStarted.md new file mode 100644 index 000000000..64c91a8c2 --- /dev/null +++ b/src/plugins/GettingStarted.md @@ -0,0 +1,608 @@ +# Plugins +impress.js has a plugin system that allows you to expand its functionality. It ships with some default plugins which are activated by default, but there are more plugins which you can find [here](/extras/). You may learn how to activate those plugins by reading [this](#extra-plugins). Here you can see all the collected plugin READMEs and Documentation from the js files. I have added a note, where I have added my own documentation and where I have changed something. + +## CONTENTS + +* [Autoplay](#autoplay) +* [Blackout](#blackout) +* [Form](#form) +* [Fullscreen](#fullscreen) +* [Goto](#fullscreen) + + + +# Main plugins +## Autoplay +*This documentation here was not authored by the creator of the plugin* + +The [autoplay](/src/plugins/autoplay/autoplay.js) plugin automatically advances the presentation after a certain timeout expired. + +**USAGE** + +You first have to enable the plugin by setting a global ```data-autoplay``` value on the impress-div. Then you can change individual ```data-autoplay``` values on each *step* by adding ```data-autoplay``` to it. If this value is set to ```0```, there will be no more auto-advancing on this *step*. The value you enter is time in seconds to switch to the next slide. + +**EXAMPLE** + +Note: This only shows part of the HTML. If you want to know how to set up a presentation, I highly recommend you read our [Getting Started Guide](/GettingStarted.md) +``` +
+
+ This slide will not auto-advance +
+
+ This slide will auto-advance at the globally defined rate. +
+
+ This slide will auto-advance after 10 seconds +
+
+``` + + +## Blackout +*This documentation here was not authored by the creator of the plugin* + +This plugin is automatically enabled and runs whenever you start your presentation. You can press *B* or *.* on your keyboard to blank / unblank the screen. + + +## Form +Form support! Functionality to better support use of input, textarea, button... elements in a presentation. + +This plugin does two things: + +Set stopPropagation on any element that might take text input. This allows users to type, for example, the letter 'P' into a form field, without causing the presenter console to spring up. + +On impress:stepleave, de-focus any potentially active element. This is to prevent the focus from being left in a form element that is no longer visible in the window, and user therefore typing garbage into the form. + +***THIS PLUGIN REQUIRES FURTHER DEVELOPMENT*** + + TODO: Currently it is not possible to use TAB to navigate between form elements. Impress.js, and + in particular the navigation plugin, unfortunately must fully take control of the tab key, + otherwise a user could cause the browser to scroll to a link or button that's not on the current + step. However, it could be possible to allow tab navigation between form elements, as long as + they are on the active step. This is a topic for further study. + +## Fullscreen +*This documentation here was not authored by the creator of the plugin* +This plugin puts your presentation into fullscreen by pressing *F5*. You can leave fullscreen again by pressing *Esc*. + +*Note:* impress.js works just fine with the normal fullscreen offered by your browser where you would (usually) press *F11* to enter it. There are certain circumstances where you might want to use this plugin instead, as it should work with the impressConsole plugin as well. + + + +## Goto +The goto plugin is a pre-stepleave plugin. It is executed before +`impress:stepleave` event, and will alter the destination where to transition next. + +Example: + + +
+ + +
+ + +
+ +See https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values for a table +of what strings to use for each key. + +***Author:*** + +Copyright 2016 Henrik Ingo (@henrikingo) + + +## Help +Shows a help popup when a presentation is loaded, as well as when 'H' is pressed. + +To enable the help popup, add following div to your presentation: + +
+ +Example CSS: + + .impress-enabled #impress-help { + background: none repeat scroll 0 0 rgba(0, 0, 0, 0.5); + color: #EEEEEE; + font-size: 80%; + position: fixed; + left: 2em; + bottom: 2em; + width: 24em; + border-radius: 1em; + padding: 1em; + text-align: center; + z-index: 100; + font-family: Verdana, Arial, Sans; + } + .impress-enabled #impress-help td { + padding-left: 1em; + padding-right: 1em; + } + + + +***Author:*** + +Copyright Henrik Ingo (@henrikingo), 2016 + + +## impressConsole +Press 'P' to show a speaker console window. + +* View of current slide +* Preview of next slide +* Speaker notes (contents of a
element on current slide) +* Navigation + +For speaker notes, add the following anywhere inside a step + +
Speaker notes text...
+ +Example CSS: + + /* Hide notes from the actual presentation. This will not affect the visibility of notes in the impress console window. */ + + .notes { + display: none; + } + + + +***Authors:*** +* Henrik Ingo, henrik.ingo@avoinelama.fi, impress.js (plugin) integration +* Heiko Richler, Aico.Richler@gmx.net, major changes in rev. 1.3 +* Lennart Regebro, regebro@gmail.com, main author of impressConsole +* David Souther, davidsouther@gmail.com, author of the original notes.js + + +## Media +This plugin will do the following things: + - Add a special class when playing (body.impress-media-video-playing and body.impress-media-video-playing) and pausing media (body.impress-media-video-paused and body.impress-media-audio-paused) (removing them when ending). This can be useful for example for darkening the background or fading out other elements while a video is playing. Only media at the current step are taken into account. All classes are removed when leaving a step. +- Introduce the following new data attributes: + - data-media-autoplay="true": Autostart media when entering its step. + - data-media-autostop="true": Stop media (= pause and reset to start), when leaving its step. + - data-media-autopause="true": Pause media but keep current time when leaving its step. + +When these attributes are added to a step they are inherited by all media on this step. Of course this setting can be overwritten by adding different attributes to inidvidual media. + +The same rule applies when this attributes is added to the root element. Settings can be overwritten for individual steps and media. +Examples: +- data-media-autoplay="true" data-media-autostop="true": start media on enter, stop on leave, restart from beginning when re-entering the step. +- data-media-autoplay="true" data-media-autopause="true": start media on enter, pause on leave, resume on re-enter +- data-media-autoplay="true" data-media-autostop="true" data-media-autopause="true": start media on enter, stop on leave (stop overwrites pause). +- data-media-autoplay="true" data-media-autopause="false": let media start automatically when entering a step and let it play when leaving the step. +- ```
...
``` + All media is startet automatically on all steps except the one that has the data-media-autoplay="false" attribute. +- Pro tip: Use ```