When To Use Executeordelayuntilscriptloaded To Run Javascript In Sharepoint

The Problem with Running JavaScript in SharePoint

One of the most common issues developers face when writing JavaScript code for SharePoint pages is scripts running before the page has fully loaded. Since SharePoint pages have complex markup and loading behaviors, scripts often try to manipulate page elements before they are available in the DOM, resulting in errors.

For example, if you have a script that hides a certain div on page load, that div may not exist yet when the script runs, causing a JavaScript error. Or if you try to retrieve an element by ID before it has loaded, you’ll get null references. These premature executions happen because scripts loaded in script tags get parsed and executed immediately as the page loads above them.

To avoid this, developers need a way to delay JavaScript execution until appropriate points in the page lifecycle, such as when dependent frameworks like jQuery finish loading or SharePoint framework scripts initialize. The ExecuteOrDelayUntilScriptLoaded method provides a robust way to handle this in the SharePoint context.

Table of Contents

How ExecuteOrDelayUntilScriptLoaded Works

The ExecuteOrDelayUntilScriptLoaded method is a globally accessible function in SharePoint pages that allows delaying a script’s execution until after the wpq2 bootstrap script loads. This script contains core functionality to initialize the SharePoint framework on client-side pages. By waiting for it to load, you ensure all dependent libraries like jQuery and SharePoint namespaces have initialized before attempting to run additional scripts.

The basic usage is simple. You pass a function into ExecuteOrDelayUntilScriptLoaded containing the code you want to run on delay. This function will not get invoked until the wpq2 script finishes loading. For example:

ExecuteOrDelayUntilScriptLoaded(function(){
  //Safe to execute code here
});

This means any code inside the function will wait to run until the SharePoint framework has fully loaded on the page. The key advantage over alternatives like jQuery.ready() is SharePoint specific scripts may need to wait for additional components beyond just the DOM.

Basic Usage

Using ExecuteOrDelayUntilScriptLoaded consists of a single function call, passing in the function you want to execute on delay. For example:

ExecuteOrDelayUntilScriptLoaded(myFunction);

function myFunction(){
  //This code will wait to run  
}

Notice you pass the function name without parentheses, just a reference. Otherwise, it would get invoked immediately. Behind the scenes, SharePoint will call this function when ready instead of executing it in place.

Code passed in can do anything a standard JavaScript function would do – manipulate DOM elements, send AJAX requests, initialize objects, etc. It will queue up and execute at the appropriate time.

You can even pass anonymous functions instead of named ones:

ExecuteOrDelayUntilScriptLoaded(function(){
  alert("Loaded!"); 
});

The key is SharePoint takes care of waiting – your responsibility is to pass a function with the logic you want executed later on page load.

Delaying Page Component Initialization

A common use case for ExecuteOrDelayUntilScriptLoaded involves initializing SharePoint UI components on page load. Components like scripts editors, document libraries, and web parts often need to run setup logic when they render.

For example, you may want to attach some behavior when a Discussion Board renders. Doing this in a normal script tag may fail because the Discussion Board doesn’t exist early on. Instead, wrap it in a delayed execution:

ExecuteOrDelayUntilScriptLoaded(function(){
  //Safe to init component
  var board = document.getElementById("discussionBoard"); 
  board.addEventListener("commentAdded", function(e) {
    alert("New comment!");
  });
});

This guarantees the Discussion Board has rendered before we try accessing it. The same approach applies to any component – wrap it in a delayed function to ensure SharePoint finishes loading it on the page before initialization.

Why Not Just Use jQuery Ready?

jQuery’s ready() method is a common approach to delay code until the DOM finishes loading. However, in SharePoint ExecuteOrDelayUntilScriptLoaded is more robust since it waits for SharePoint libraries to initialize, not just the DOM.

The wpq2 script ExecuteOrDelayUntilScriptLoaded waits for handles additional bootstrapping and loading of SharePoint namespaces. The DOM may be ready before all SharePoint components initialize. So jQuery ready risks the same premature execution issues.

You want to be absolutely sure SharePoint Framework scripts finish, which ExecuteOrDelayUntilScriptLoaded guarantees before invoking passed functions. No other generic ready events account for SharePoint’s full loading sequence.

Summary

When writing JavaScript for SharePoint pages, using proper delaying and execution order is critical to avoid errors. The ExecuteOrDelayUntilScriptLoaded method provides an easy way to ensure your code runs at the right time in SharePoint’s loading sequence.

Simply pass your logic in a function to ExecuteOrDelayUntilScriptLoaded. This will queue up execution until after wpq2 bootstraps the SharePoint framework on client-side, signaling components are ready to access or manipulate safely.

Following this practice avoids premature script issues, makes component initialization reliable, and leads to robust client-side code in SharePoint. Understanding proper loading order goes a long way towards taming JavaScript in complex environments like SharePoint.