Usage
nebula.loadJS(url, handle)
Parameters
url
(Required) (String) The URL of the JS resource to load
Default: None
handle
(Optional) (String) The name to identify this resource
Default: None
Callback
(Optional) (Function) A function to run after the JS resource has loaded
Default: None
Parameter Notes
This function returns a Promise which are also available in the object nebula.site.resources.lazy.promises.
Examples
Simply lazy load a JS resource
nebula.loadJS('https://example.com/file.js', 'example-file');
Call a function after the resource is loaded (using the promise)
nebula.loadJS('https://example.com/file.js', 'example-file').then(function(){
console.log('file.js is now available');
});
Run a function after the JS has loaded (using the callback)
nebula.loadJS('https://example.com/file.js', 'example-file', function(){
console.log('file.js is now available');
});
Listen for a specific Promise
//In this example, this line happens somewhere else:
nebula.loadJS('https://example.com/file.js', 'example-file');
//Use this to listen for that Promise to resolve
nebula.site.resources.lazy.promises['example-file'].then(function(){
console.log('file.js is now available');
});
Listen for Bootstrap JS to be available using a promise
//Use this to listen for that Promise to resolve
nebula.site.resources.lazy.promises['bootstrap.bundle.min.js'].then(function(){
console.log('Bootstrap JS is now available');
});
Listen for Bootstrap JS using a standard event listener
//Note that if this event listener is called *after* the resource is loaded, it will never trigger! So wrap it in a condition to check if it is already available!
if ( typeof bootstrap === 'object' ){ //If bootstrap is not already loaded
console.log('Bootstrap JS is already available'); //Call your function here
} else {
jQuery(document).on('nebula_loadjs', function(handle){
if ( handle == 'bootstrap.bundle.min.js' ){
console.log('Bootstrap JS is now available'); //Call your function here
}
});
// ----or----
//Use the specific trigger without needing the handle conditional.
jQuery(document).on('nebula_loadjs_bootstrapbundleminjs', function(){
console.log('Bootstrap JS is now available'); //Call your function here
});
}
Additional Notes
Unlike jQuery getScript(), this function caches the JavaScript resource.
Source File
Located in /assets/js/modules/optimization.js on line 670.
No Hooks
This function does not have any filters or actions available. Request one?nebula.loadJS = async function(url, handle, callback=false){
//await nebula.yield();
nebula.site.resources.lazy.promises = nebula.site.resources.lazy.promises || {}; //Ensure this exists
//Listen for requestIdleCallback when Safari supports it
if ( typeof url === 'string' ){
if ( !handle ){
handle = url.split('\\').pop().split('/').pop().split('?')[0]; //Get the filename from the URL and remove query strings
}
//Look into import() here instead of generating a <script> element to append. The import() function does work with third-party endpoints.
//Store the promise so it can be listened for elsewhere if necessary
nebula.site.resources.lazy.promises[handle] = new Promise(function(resolve, reject){
var lazyScriptElement = document.createElement('script');
lazyScriptElement.src = url;
lazyScriptElement.onload = resolve;
lazyScriptElement.onerror = reject;
document.body.appendChild(lazyScriptElement);
}).then(function(){
//Trigger an event if that is an option to listen for as well
nebula.dom.document.trigger('nebula_loadjs_' + handle.replaceAll(/[^a-zA-Z]/gi, '')); //This one is specific to the handle being loaded. Ex: 'nebula_loadjs_bootstrapbundleminjs'
nebula.dom.document.trigger('nebula_loadjs', handle); //This one is a generic one that passes the handle name
if ( callback ){ //Callback just in case it is preferred instead of the returned promise.
return callback(); //Should this have a return on it? That would break the promise, but if a callback is specified it would be expected...
}
});
return nebula.site.resources.lazy.promises[handle];
}
nebula.help('nebula.loadJS() requires a valid URL. The requested URL is invalid: ' + url, '/functions/loadjs/');
};
Override
To override or disable this JavaScript function, simply redeclare it with the exact same function name. Remember: Some functionality is conditionally loaded via dynamic imports, so if your function is not overriding properly, try listening for a DOM event (described below).
For non-module import functions:
nebula.loadJS = function(url, handle, Callback){
//Write your own code here, leave it blank, or return false.
}
For dynamically imported module function overrides:
jQuery(window).on('load', function(){
nebula.loadJS = function(url, handle, Callback){
//Write your own code here, leave it blank, or return false.
}
});
Custom Nebula DOM events do also exist, so you could also try the following if the Window Load listener does not work:
jQuery(document).on('nebula_module_loaded', function(module){
//Note that the module variable is also available to know which module specifically was imported
if ( typeof nebula.loadJS === 'function' ){
nebula.loadJS = function(url, handle, Callback){
//Write your own code here, leave it blank, or return false.
}
}
});