Coincidentally on three separate occasion, with three different customers/developers using three different libraries I encountered the same issue last week. I am going illustrate the process I go through when troubleshooting JavaScript libraries and use this one issue as the example.
The same question from each of them: Why is my JavaScript library not working in my XPage?
What does Firebug say?
If you ever ask me for help this will always be my first question – and a significant number of issues can be solved by just looking at the browser console and taking action based on knowing what the failure is.
Typical errors
Here are some typical errors/messages and what can be done about them
- $ is not defined
- Problem: This means you have tried to use jQuery (most likely) before the jQuery library is loaded. jQuery plugins are dependent on the jQuery library being loaded before them in the browser.
- Solution: check that you are adding jQuery, the path is correct and it is being loaded before any other library dependent on it.
- 404 file not found
- Problem: Looking through the Net tab in firebug you will be able to check and see if all your files loaded correctly
- Solution: Right click on the failing URL and open in new tab then you can see the whole URL.
- Check to make sure the file is in fact where you think it should be
- Check your spelling
- Check to make sure that your new design element is built. XPages will report 404 file does not exist if you have not built the new element. Even though it is in your database does not mean it is available.
- 400 Bad request
- Check and make sure that the library has not appended anything to the end of the file name making it illegible to the Domino server (see Caching below)
- General JavaScript errors
- Problem: a lot harder to troubleshoot. You will get a message saying that the dojo.js or jQuery.min.js has reported an error and it looks like the library has a bug. Chances are though that it is a coding error or a configuration error on your part which is bubbling up as an error in the library using the code you have created.
- Solution: work back to the example and see where your code is different.
Caching
Many JavaScript libraries append random values to the end of files with the positive intention of avoiding browser cache issues. Ext JS is one example of this – when you ask for the required files within the grid “random crap” gets added to the end of the file name:
Ext.require([
'Ext.data.*',
'Ext.grid.*',
'Ext.ux.grid.FiltersFeature'
]);
When the page loads you see nothing and this issue in Firebug
So when we right click and open the file in a new tab we see the following URL in full
The answer is really very simple – IBM Domino is a web server waiting for requests, and if you (or the library you are trying to use) asks the server for something it does not understand it will reject you with a 400 bad request error. In this case it is trying to interpret the _dc= command on the FiltersFeature.js file and failing.
There are two possible solutions and depending on the library configuration you should be able to work around it
- Turn off caching if you believe it will not cause issues
- Modify the URL of the incoming file by adding ?open& on it
In the case of Ext JS we add the following code to turn off caching
Ext.Loader.setConfig({
enabled : true,
disableCaching : false //This turns off caching - nice double negative I know (v4 and above)
});
Ext.require([
'Ext.data.*',
'Ext.grid.*',
'Ext.ux.grid.FiltersFeature'
]);
But it *must* come in your code *before* the require code otherwise it won’t work.
Require.js usage in XPages R9
As has been detailed by Sven Hasslebach, along with his solution, Dojo 1.8 (used in R9) does not play at all with other AMD libraries. If your JavaScript library used require.js or an equivalent loader library you must make sure it is loaded in the header before dojo. Check out Sven’s post for the solution/workaround.
Conclusion
Troubleshooting is always easier when you have a checklist of possible issue to go through. The more you do them the more they will become muscle memory. If anyone has any other good tips please feel free to add in the comments 
