Common Pitfalls When Using _Spbodyonloadfunctionnames In Sharepoint
Executing Custom JavaScript Code on Page Load
The _spBodyOnLoadFunctionNames array in SharePoint allows developers to execute custom JavaScript code on page load. This array contains function names as strings that are called sequentially when the body of the page finishes loading. Understanding how to properly use this array is key to implementing customizations in SharePoint.
Common pitfalls when using _spBodyOnLoadFunctionNames include forgotten function references, duplicate references, incorrect ordering, and timing issues. Debugging problems can be difficult without a strong grasp of how _spBodyOnLoadFunctionNames works under the hood.
Defining Custom Functions
To use _spBodyOnLoadFunctionNames, developers first need to define any custom functions that should execute on page load. These functions must be defined globally so they are available to be called by _spBodyOnLoadFunctionNames.
<script type="text/javascript">
function myCustomFunction() {
// Function code here
}
</script>
The key is that myCustomFunction must be defined outside of DOM ready events for _spBodyOnLoadFunctionNames to have access to it. Understanding this requirement avoids tricky issues down the road.
Pushing Function Names
With custom functions defined, the next step is pushing their names onto the _spBodyOnLoadFunctionNames array. This tells SharePoint to execute these functions when the page finishes loading.
_spBodyOnLoadFunctionNames.push("myCustomFunction");
The push method allows dynamically adding any functions that should run at page load. However, problems can arise if function names are pushed incorrectly.
Understanding the _spBodyOnLoadFunctionNames Array
Under the hood, _spBodyOnLoadFunctionNames works by iterating through all names pushed onto its array and executing those functions globally. Knowing how this array functions helps troubleshoot issues.
Sequential Execution
The order that function names are pushed onto _spBodyOnLoadFunctionNames matters. SharePoint will execute them sequentially based on their index within the array.
_spBodyOnLoadFunctionNames.push("func1");
_spBodyOnLoadFunctionNames.push("func2");
Here func1 will run first, followed by func2 on page load. Understanding this order of operations is crucial when debugging functionality issues.
Global Lookup
For each name in its array, SharePoint will look up and execute the function globally. The function must be defined somewhere SharePoint can access it, or an error will occur. Troubleshooting functionality means confirming definitions.
function myFunction() {
// Code here
};
_spBodyOnLoadFunctionNames.push("myFunction");
If myFunction was not defined globally, SharePoint would fail looking it up and executing its code, often silently failing.
Forgotten Function References Causing Errors
One pitfall developers run into is pushing function names that do not match defined functions. For example:
function myFunction { // Logic here }
_spBodyOnLoadFunctionNames.push("MyFunction")
Here “MyFunction” will not match the defined “myFunction” name. SharePoint will fail finding this function to execute,often without any errors surfacing. Always double check for typos in function names.
Non-Existent Functions
Similarly, pushing names for functions that do not exist globally will cause issues:
_spBodyOnLoadFunctionNames.push("randomFunction");
With no global randomFunction function defined, SharePoint will throw an error when trying to execute it. Only push names matching existing functions.
Debugging Reference Issues
Use console logging in functions pushed to _spBodyOnLoadFunctionNames to diagnose reference issues:
function myFunction() {
console.log("Executed");
}
If logging shows myFunction never runs from _spBodyOnLoadFunctionNames, double check spelling issues or non-existent function names.
Duplicate Function References Causing Errors
Another pitfall is pushing duplicate function names to _spBodyOnLoadFunctionNames:
function myFunction() {
// Logic here
}
_spBodyOnLoadFunctionNames.push("myFunction");
_spBodyOnLoadFunctionNames.push("myFunction");
This will execute myFunction twice, often leading to unexpected behavior like duplicated DOM elements or variables overriding each other.
Checking Duplicates
Scan all calls pushing names to _spBodyOnLoadFunctionNames. If the same name appears multiple times, unintended duplicate execution may occur. Eliminate any duplicates calls.
var uniqueNames = [];
uniqueNames.push("myFunction");
if (uniqueNames.indexOf("myFunction") === -1) {
_spBodyOnLoadFunctionNames.push("myFunction");
}
Here the unique names array tracks whether myFunction has already been pushed before allowing another push. This pattern avoids duplicates.
Isolating Logic
When duplicate calls can’t be avoided, isolate logic into helper functions to be called internally to avoid repetition:
function myHelperFunction() {
// Reusable logic here
}
function myFunction() {
myHelperFunction();
}
_spBodyOnLoadFunctionNames.push("myFunction");
_spBodyOnLoadFunctionNames.push("myFunction");
This keeps business logic in a single place to be executed multiple times if needed.
Function Ordering and Timing Issues
Understanding order of execution with _spBodyOnLoadFunctionNames helps avoid tricky bugs. Functions pushed first execute first on page load:
function firstFunc() {
console.log("First");
}
function secondFunc() {
console.log("Second");
}
_spBodyOnLoadFunctionNames.push("firstFunc");
_spBodyOnLoadFunctionNames.push("secondFunc");
Here firstFunc outputs before secondFunc. Flipping the order of push statements would change execution order.
Dependent Ordering
Problems can arise if one function depends on another already having run:
function initializer() {
var myVar = "";
}
function badFunc() {
console.log(myVar); // Throws error
}
_spBodyOnLoadFunctionNames.push("badFunc");
_spBodyOnLoadFunctionNames.push("initializer");
Here badFunc assumes myVar was already defined, but initializer hasn’t run yet since it was pushed second. Order matters with dependencies.
Timing Issues
Likewise, DOM availability issues come up if functions execute before elements are ready:
function clickButton {
document.getElementById("myButton").click();
}
_spBodyOnLoadFunctionNames.push("clickButton");
If myButton doesn’t exist in the DOM yet, .click() will error. Double check timing dependencies to avoid race conditions at load.
Debugging with the Browser Console
Debugging _spBodyOnLoadFunctionNames issues relies heavily on browser developer tools like the console. Console logs output execution order and surface errors.
Tracing Execution
Insert console.logs within pushed functions for tracing:
function firstFunc() {
console.log("Inside firstFunc");
// Logic
}
_spBodyOnLoadFunctionNames.push("firstFunc");
The console will confirm firstFunc executes and its place in order. Modern browsers also show file and line numbers for logging calls.
Catching Errors
Console surfaces errors thrown within _spBodyOnLoadFunctionNames that may otherwise get swallowed in execution:
function errorFunc() {
throw new Error("Something failed!");
}
_spBodyOnLoadFunctionNames.push("errorFunc");
The console would output the Something failed! error and stack trace. This technique is invaluable for noticing and debugging issues.
Best Practices for Using _spBodyOnLoadFunctionNames
Following best practices when working with _spBodyOnLoadFunctionNames avoids headaches down the line:
- Double check for typos on pushed function names
- Define functions before push calls
- Only push names once to prevent duplicates
- Mind order dependencies with execution sequence
- Console log early and often while debugging
With attention to detail on these areas, leveraging _spBodyOnLoadFunctionNames becomes easy for custom SharePoint solutions. Allowing scripts to boot up at the right time unlocks powerful capabilities.
