9b958f0e00
- 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.
106 lines
3.3 KiB
Markdown
106 lines
3.3 KiB
Markdown
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);
|