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 🙂
Xomino 
Good post. Some great tips. I tend to use Safari/Element Inspector first (developing mobile apps because it supports WebKit) and sometimes the inspector reports ‘unknown token } line 67’ (or whatever line). The problem is that this is not the real line number – and is a bugger when you do have JS on the line reported that is well defined and not the real problem. If this happens, use Firefox as the JS gets extracted and the real line of code is displayed. This has caught me out before and FF/Firebug should be used even as a secondary inspector.
thanks Rich 🙂
Personally I use Chrome Debugger but horses for courses, not forgetting you can execute any javascript in the console as well as set breakpoints etc.
Probably a classic is leaving a console.log in the javascript and you have IE8 users.
You know I have been threatening to do a NotesIn9 on using the debugger in XPages applications……good point !
Mark,
One additional free tool to use is Fiddler. With Fiddler you can see the raw or format information being requested and responded from the server.
Good suggestion – I also like to use the HTTPFox plugin for firebug which gives more information that Firebug itself.
Since we use all RESTful services, Fiddler will provide you information on what is happening even if the debugger is telling you there is an error in Dojo. Automatically tells me that I either got badly constructed response Json or I did a boo boo and use Fiddler to see the req/res
That URL modification tip turned out to be quite handy yesterday 🙂
Glad to hear it 🙂
When ever anyone asks me for help my first question is still “what does firebug say” 🙂