diff --git a/README.md b/README.md
index 314622c..40b97df 100644
--- a/README.md
+++ b/README.md
@@ -33,18 +33,18 @@ We are switching to TS as the main impress development language, but you can sti
Welcome to impress.js, the impressive JavaScript framework, that allows you to build presentations for web browsers.
## Browser support
-Since impress.js is designed to show of the power of modern CSS, we cannot guarantee that it will run in older browser. Whilst we try not to intentionally not support browsers, some features might not work well on all browsers, especially with V3.x. For example, Internet Explorer is known to not work with V3.x, so if you really NEED to use that browser, please use V2.x. impress.js works best with the latest versions of Chrome, Firefox and most likely also with the latest versions of Safari.
+Since impress.js is designed to show off the power of modern CSS, we cannot guarantee that it will run in older browser. Whilst we try not to intentionally break support for certain browsers, some features might not work well on all browsers, especially with V3.x. For example, Internet Explorer is known to not work with V3.x, so if you really NEED to use that browser, please use V2.x. impress.js works best with the latest versions of Chrome, Firefox and most likely also with the latest versions of Safari.
## Quick Start
You can visit our website at [https://impress.js.org](https://impress.js.org) to learn more about the project, where you can also find helpful resources for getting started, like the [Getting Started Guide](/docs/GettingStarted.md) and [Documentation](/docs/DOCUMENTATION.md), but rendered as HTML instead of MarkDown, as it is here on GitHub.
-## A very quick quick start
+## A very quick "quick start"
Copy one of the code snippets below to the header of your impress.js presentation's HTML file.
- V3.0.0:
```
-
```
- V2.0.0:
```
@@ -57,7 +57,7 @@ Copy one of the code snippets below to the header of your impress.js presentatio
- Upstream:
```
-
```
We do not recommend using the Upstream version, as there might be breaking changes coming or features might be temporarily broken due to only partially finished feature updates. Whilst this shouldn't happen normally, please be aware of that risk when using Upstream.
@@ -70,17 +70,17 @@ You can download impress.js from the releases tab. Some older versions might not
You can find the entire documentation of impress.js on our [website](https://impress.js.org/docs) or in the [DOCUMENTATION.md](/docs/DOCUMENTATION.md) file
-The [HTML source code](index.html) of the official [impress.js demo](http://impress.js.org/) serves as a good example usage and contains comments explaining various features of impress.js. For more information about styling you can look into [CSS code](css/impress-demo.css) which shows how classes provided by impress.js can be used. Last but not least [JavaScript code of impress.js](js/impress.js) has some useful comments if you are interested in how everything works. Feel free to explore!
+The [HTML source code](index.html) of the official [impress.js demo](https://impress.js.org/) serves as a good example usage and contains comments explaining various features of impress.js. For more information about styling you can look into [CSS code](css/impress-demo.css) which shows how classes provided by impress.js can be used. Last but not least [JavaScript code of impress.js](js/impress.js) has some useful comments if you are interested in how everything works. Feel free to explore!
# Official demo
-[impress.js demo](http://impress.js.org/) by [@bartaz](http://twitter.com/bartaz)
+[impress.js demo](https://impress.js.org/) by [@bartaz](https://twitter.com/bartaz)
## Examples and demos
-The [Classic Slides](http://impress.js.org/examples/classic-slides/) demo is targeted towards beginners, or can be used as a template for presentations that look like the traditional PowerPoint slide deck. Over time, it also grew into the example presentation that uses most of the features and addons available.
+The [Classic Slides](https://impress.js.org/examples/classic-slides/) demo is targeted towards beginners, or can be used as a template for presentations that look like the traditional PowerPoint slide deck. Over time, it also grew into the example presentation that uses most of the features and addons available.
-More examples and demos can be found on [Examples and demos wiki page](http://github.com/impress/impress.js/wiki/Examples-and-demos).
+More examples and demos can be found on [Examples and demos wiki page](https://github.com/impress/impress.js/wiki/Examples-and-demos).
Feel free to add your own example presentations (or websites) there.
@@ -89,7 +89,7 @@ Feel free to add your own example presentations (or websites) there.
If you want to learn even more there is a [list of tutorials and other learning resources](https://github.com/impress/impress.js/wiki/impress.js-tutorials-and-other-learning-resources)
on the wiki, too.
-There is also a book available about [Building impressive presentations with impress.js](http://www.packtpub.com/building-impressive-presentations-with-impressjs/book) by Rakhitha Nimesh Ratnayake.
+There is also a book available about [Building impressive presentations with impress.js](https://www.packtpub.com/building-impressive-presentations-with-impressjs/book) by Rakhitha Nimesh Ratnayake.
You may want to check out the sibling project [Impressionist](https://github.com/henrikingo/impressionist): a 3D GUI editor that can help you in creating impress.js presentations.
@@ -137,25 +137,32 @@ TODO: Check that these requirements are still ok
* [build.js](build.js): Simple build file that creates `js/impress.js`. It also creates a minified version `impress.min.js`, but that one is not included in the github repository.
* [package.json](build.js): An NPM package specification. This was mainly added so you can easily install [buildify](https://www.npmjs.com/package/buildify) and run `node build.js`. Other than the build process, which is really just doing roughly `cat src/impress.js src/plugins/*/*.js > js/impress.js`, and testing, `impress.js` itself doesn't depend on Node or any NPM modules.
+TODO: Update repo structure once updating is complete
+
# About impress.js
## ABOUT THE NAME
-impress.js name is [courtesy of @skuzniak](http://twitter.com/skuzniak/status/143627215165333504).
+impress.js name is [courtesy of @skuzniak](https://twitter.com/skuzniak/status/143627215165333504).
It's an (un)fortunate coincidence that an Open/LibreOffice presentation tool is called Impress ;)
## Reference API
-See the [Reference API](DOCUMENTATION.md)
+See the [Reference API](/docs/DOCUMENTATION.md)
+
+TODO: Will be updated once full release of V3 is ready
## Browser support (again, but for devs)
impress.js uses the following CSS and JavaScript 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)
+TODO: Update list below
+
+* [DataSet API](https://caniuse.com/#search=dataset)
+* [ClassList API](https://caniuse.com/#search=classlist)
+* [CSS 3D Transforms](https://caniuse.com/#search=css%203d)
+* [CSS Transitions](https://caniuse.com/#search=css%20transition)
+
# Copyright and License
diff --git a/docs/core/addElements.md b/docs/core/addElements.md
new file mode 100644
index 0000000..b725d63
--- /dev/null
+++ b/docs/core/addElements.md
@@ -0,0 +1,2 @@
+# Adding Elements to impress
+You can add elements to impress by calling the `impress.addElement` function.
\ No newline at end of file
diff --git a/src/impress.js b/src/impress.js
index 3c43b44..bb347c3 100644
--- a/src/impress.js
+++ b/src/impress.js
@@ -22,12 +22,14 @@
// You are one of those who would like to know how impress.js works?
// Let us show you!
// Please note that compared to previous versions of impress, this code is documented in a more technical fashion.
+// A lot has changed compared to V2, so re-reading the code or documentation is highly recommended before you start
+// developing and updating plugins. There is a guide on how to migrate plugins from API V2 to API V3.
// Important note on the file structure of impress.js, as it has changed with V3:
// -------------------------------------------------------------------------------
// This file contains all the interface definitions and uses various components from the ./lib directory,
// as well as loading impress plugins from the ./plugins directory. A fully built impress.js version
-// has all of these files combined into a single file, as to enable a simple include.
+// has all of these files combined into a single file, to allow for simple includes in simple webpages
// All internal functions are (to be) prefixed with an underscore
@@ -40,8 +42,12 @@ class ImpressConfig {
}
}
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-window.impress = () => {
+/**
+ * This is the main impress.js function and is used to prepare the DOM for the usage of impress.
+ * @param {ImpressConfig?} impressConfig Optional argument to specify config. Can be changed later on with the impress().updateConfig() function.
+ * @returns {object} Returns all public impress functions
+ */
+window.impress = ( impressConfig ) => {
// Somehow eslint didn't like the variable being reassigned inside of a function...
// So I had it shut up
// eslint-disable-next-line prefer-const
@@ -121,7 +127,7 @@ window.impress = () => {
* @param {number} rotation.x The rotation in degrees around the x-axis
* @param {number} rotation.y The rotation in degrees around the y-axis
* @param {number} rotation.z The rotation in degrees around the z-axis
- * @returns {boolean} Returns true if successful at positioning this element, false, if failed
+ * @returns {boolean} Returns true if successful at positioning this element, false, if failed. Will also emit the "impress:addedElement" event to tell plugins that an element was added
*/
const addElement = ( DOMElementID, coordinates, rotation ) => {
if ( DOMElementID === '' || !DOMElementID ) {
@@ -138,7 +144,7 @@ window.impress = () => {
rotation: rotation,
id: DOMElementID
};
- positionElements();
+ _positionElements();
// Dispatch event that an element was added
document.dispatchEvent( new Event( 'impress:addedElement' ) );
@@ -158,7 +164,7 @@ window.impress = () => {
} catch ( err ) {
return false;
}
- positionElements();
+ _positionElements();
// Dispatch event that an element was removed
document.dispatchEvent( new Event( 'impress:removedElement' ) );
@@ -169,7 +175,7 @@ window.impress = () => {
* Internal function that positions elements on the canvas. Called every time a element is added / removed
* @returns {undefined}
*/
- const positionElements = () => {
+ const _positionElements = () => {
// Gets current position and calls moveTo function
moveTo( getCurrentPos().coordinates, getCurrentPos().rotation );
};
@@ -184,13 +190,15 @@ window.impress = () => {
* @param {number} rotation.x The rotation in degrees around the x-axis
* @param {number} rotation.y The rotation in degrees around the y-axis
* @param {number} rotation.z The rotation in degrees around the z-axis
- * @returns {promise} This promise resolves as a boolean, indicating success or failure
+ * @returns {promise} The returned promise resolves as a boolean, indicating success or failure
*/
const moveTo = ( coordinates, rotation ) => new Promise( ( resolve, reject ) => {
// Dispatch event telling all plugins that we're moving
document.dispatchEvent( new Event( 'impress:moving' ) );
console.log( coordinates, rotation );
if ( typeof ( coordinates ) === 'object' ) {
+ // Dispatch event telling all plugins that we've stopped moving
+ document.dispatchEvent( new Event( 'impress:movingComplete' ) );
resolve( true );
} else {
reject( new Error( 'moveTo takes a coordinate and rotation object as arguments' ) );
@@ -204,20 +212,39 @@ window.impress = () => {
const getElements = () => initializedElements;
/**
- * Returns the current position as an object of form { coordinates: Object, rotation: Object }
+ * Get the current position of the camera
* @returns {object} Returns an object that contains an object of the coordinates and rotation:
* { coordinates: { x: number, y: number, z: number }, rotation: { x: number, y: number, z: number }
*/
const getCurrentPos = () => ( { coordinates: { x: 0, y: 0, z: 0 }, rotation: { x: 0, y: 0, z: 0 } } );
- // Return all functions that are exposed by impress
+ /**
+ * Use this function to get the current impress config
+ * @returns {ImpressConfig} Returns the current impress config
+ */
+ const getCurrentConfig = () => {
+ return impressConfig;
+ }
+
+ /**
+ * Update the impress config.
+ * @param {ImpressConfig} impressConfig The new impress config
+ * @returns {undefined} Returns nothing
+ */
+ const updateConfig = ( impressConfig ) => {
+ impressConfig = impressConfig;
+ }
+
+ // Return all functions that are exposed by impress. This is superior to using classes as we can control what functions we expose.
return {
init,
getElements,
moveTo,
removeElement,
addElement,
- getCurrentPos
+ getCurrentPos,
+ getCurrentConfig,
+ updateConfig
};
};