Add a framework for libraries, and a first library gc

- Libraries are under src/lib/
- Added to build.js as usual, before plugins.
- See src/lib/README.md for details

gc library implements a "garbage collector" library, which allows
both the core and plugins to store elements and listeners to a list,
and when impress().lib.gc.teardown() is called, to have all of them
removed from the DOM. It also allows plugins to register their own
callback functions, which are called at teardown.

Commentary:

This work is based on copying the src/lib/gc.js from impressionist. While it was
useful, it turns out on the impress.js side there was much more a need to reset
attributes rather than delete elements. For now, this means lots of plugins do this
via their own lib.gc.addCallback() functions. Probably it would be nicer to add
some generic lib.gc.resetAttributes() functionality for this particular case.
I'll return to this in a future patch.

extras/ are not supported for impress().tear(). What can I say, they're extras.
Maybe in the future I'll support them, for now I can live without.
This commit is contained in:
Henrik Ingo
2017-10-05 14:57:59 +03:00
parent 9198ca854b
commit 9b958f0e00
7 changed files with 693 additions and 26 deletions

105
src/lib/README.md Normal file
View File

@@ -0,0 +1,105 @@
Impress.js Libraries
====================
The `src/lib/*.js` files contain library functions. The main difference to plugins is that:
1. Libraries are closer to the impress.js core than plugins (arguably a subjective metric)
2. Libraries are common utility functions used by many plugins
3. Libraries are called synchronously, which is why the event based paradigm that plugins use to
communicate isn't useful.
Plugins can access libraries via the API:
var api;
document.addEventListener( "impress:init", function(event){
api = event.detail.api;
api().lib.<libraryName>.<libaryFunction>();
});
...which is equivalent to:
impress().lib.<libraryName>.<libraryFunction>();
Implementing a library
----------------------
1. Create a file under `src/lib/`.
2. Start with the standard boilerplate documentation, and the (function(document, window){})();
wrapper.
3. The library should implement a factory function, and make its existence known to impress.js core:
window.impress.addLibraryFactory( { libName : libraryFactory} );
4. The library function should return a similar API object as core `impress()` function does:
var libraryFactory = function(rootId) {
/* implement library functions ... */
var lib = {
libFunction1: libFunction1,
libFunction2: libFunction2
}
return lib;
};
5. While rarely used, impress.js actually supports multiple presentation root div elements on a
single html page. Each of these have their own API object, identified by the root element id
attribute:
impress("other-root-id").init();
(The default rootId obviously is `"impress"`.)
Libraries MUST implement this support for multiple root elements as well.
- impress.js core will call the factory once for each separate root element being initialized via
`impress.init(rootId)`.
- Any state that a library might hold, MUST be stored *per `rootId`*.
- Note that as we now support also `impress(rootId).tear()`, the same root element might be
initialized more than once, and each of these MUST be treated as a new valid initialization.
Putting all of the above together, a skeleton library file will look like:
/**
* Example library libName
*
* Henrik Ingo (c) 2016
* MIT License
*/
(function ( document, window ) {
'use strict';
// Singleton library variables
var roots = [];
var singletonVar = {};
var libraryFactory = function(rootId) {
if (roots["impress-root-" + rootId]) {
return roots["impress-root-" + rootId];
}
// Per root global variables (instance variables?)
var instanceVar = {};
// LIBRARY FUNCTIONS
var libararyFunction1 = function () {
/* ... */
};
var libararyFunction2 = function () {
/* ... */
};
var lib = {
libFunction1: libFunction1,
libFunction2: libFunction2
}
roots["impress-root-" + rootId] = lib;
return lib;
};
// Let impress core know about the existence of this library
window.impress.addLibraryFactory( { libName : libraryFactory } );
})(document, window);