Controlling the order of Script Resources (e.g. Jquery) with a Custom ViewRootRenderer

When loading Client Side Javascript libraries in XPages, sometimes the order that the libraries are ‘encoded’ (or written in HTML) in the <head> tag is important.

For example jQuery and some of it’s plugins can have some issues if Dojo is encoded first.

By default in XPages you don’t have too much say in what is written out first, a nifty workaround for this has been shared by Sven Hasselbach (here and here) which utilises the lesser known <xp:headTag> tag. This workaround ensures the specified libraries will be encoded before all the normal XPages resources are encoded.

UPDATE!! It turns out that Sven made a solution like this a couple of years after those original posts! I just didn’t see it because all my googling took me to the original posts. So check out his solution as well as it allows a bit more control.

There are only 2 downsides to this method and they are not too major.

  1. You must have resource aggregation turned on
  2. You can’t use a theme to specify the resources

I wanted to come up with another solution because sometimes I like to turn resource aggregation off while developing, and also I would prefer to specify these resources in a theme instead of on individual Xpages, or alternatively adding the resources programatically with java.

Developing the solution

In the end, the actual solution is not too complicated. But, getting to that point is always the tricky part so I will explain how I went about it, and at the end you can install to your own applications and modify if you like.

The starting point is to ask, “Well how does XPages actually write out these <script> / <link> tags anyway?”. The answer is that it does so using a Renderer.

At the very Root of your XPages component tree is the UIViewRoot (corresponding to the <xp:view> tag.

Just like all your other components on your xpage (e.g. panel, inputText, viewPanel etc.) have renderers, so too does the UIViewRoot component, and it is this renderer that is responsible for generating the surrounding <html><head></head><body> tags.

We don’t want to re invent the wheel, we just want to change it’s behaviour ever so slightly, so our plan is to extend the existing view root renderer, override one of it’s methods and register our new renderer in place of the other one.

Creating our ViewRootRenderer

The default View Renderer for XPages is of the class So we are going to extend that one and see what we can do with it.

I create new Java class in the NSF

Now which method to override? Lets have at the ones we can and see which might be it.

We can use the Source => Override/Implement Methods dialog to show us some candidates.


Encode Resources List, sounds pretty good. All Stylesheets, scripts etc. are known as ‘Resources’ so this should be what we are looking for. Let’s override that method and throw in some testing code to see if we are on the right track.

Next thing to do is register our Renderer, and then tell XPages to Use it for our view root.

Register the Renderer

To do this we need to tell XPages (via faces config)

  • The Component family that our renderer is available to
  • What name do we refer to our renderer (renderer-type)
  • What is the Java Class of this renderer

The component family can be found with a little debugging, we can choose whatever name we want for renderer-type, and we know the java class because we just created it!

our faces config entry is like so:

Tell Xpages to use our renderer

Here we have 3 options!

  1. Specify on an XPage by XPage basis, some XPages use ours some don’t
  2. Use a theme to set the ViewRootRenderer for every page in the application
  3. Override the default renderer directly in faces-config

Option 1: Specify on a Page by Page basis

To do this we find the root <xp:view> tag of our xpage, and set the rendererType attribute there

Although this works, it is the least desirable option, but it is a good technique if you quickly want to change a renderer of a single control.
Since the whole point of this solution is to do it once and for all let’s move on to the next option instead.

Option 2: Use a Theme to set the ViewRootRenderer for every XPage

This is a better option, in the theme we are basically saying to xpages, whenever you find a <xp:view> set the rendererType property to our rendererType (just as we did manually above).

Below is the entry to put in the Theme, and be sure to have your theme selected for your application.

Option 3: Override the default renderer

This is another way, where you ‘hijack’ the rendererType that already exists ( This way whenever XPages tries to find the IBM renderer, it will find ours instead.

To do this we would specify IBM’s renderer type instead of the one that we created.

Which method to use is up to you but I prefer option 2 as the intention is clearest.

Check that our renderer is being used

So to check we are using our renderer we would expect to see the comments that we writing in our encodeResourceList method to appear in the generated HTML. Lets do that now by using the view-source function in our browser.


Great! So this means we are able to control what is written out at these spots.

What to do next?

So we know we can write whatever we want at these points in the <head> tag. We could go the cheap and nasty route and just write out the script tags directly from our renderer:

and this does the job, but it is not a super flexible solution as it dose not allow for customisation on a XPage by XPage basis, i.e. all XPages will have the same.


So we need some sort of test to identify:

  • which resources should be at the top
  • which should be at the bottom
  • which should be left to normal (and free to participate in resource aggregation if they like!)

Firstly I will try to make 2 resources that are specified on an XPage to appear in the ‘before’ and ‘after’ sections, and then we will do one from a theme.

Because the ScriptResource implements the FacesAttrObject interface, it can have child ‘attr’ tags that you can specify to be whatever you want. Other resources like the StyleSheetResource also can do this too.
I will utilise this and specify my own ‘encode-position’ attribute that I can use later in the renderer.

Now in the Renderer we add a bit more logic.

We make a method that will inspect a resource to determine if it should be before, after or normal, based on the encode-position attribute.

And then in our encodeResourceLists, we process the page resources into 3 lists, the ones to render before, the ones to render normally (possibly aggregated if that is set) and the ones to render after.

Ok, lets check out html and see if it worked…


Woohoo, so that’s the good news, the bad news is this won’t work from a theme, because we can’t utilise the attr’s functionality from theme. We will have to think of something else.

My solution is a bit of a hack in itself, but I am going to temporarily hijack the ‘type’ property of a script resource with some extra information, so instead of ‘type/javascript’ I will put ‘type/javascript/before’ or ‘type/javascript/after’.

Then in the renderer, I will check for this, and then fix it up (restore it back to ‘type/javascript’ so it will be correct when renderered) and attach the ‘Attr’ at that point so that any subsequent tests will use the attr instead to determine before or after.

Lets add some scripts to our theme with this new convention of added /after or /before

and check our html to see if it worked!



I hope this has shown how you can extend and modify the behaviour of XPages. In this case to solve a common problem that I’m sure many have faced.

I have put these example files in a github repository, let me know if any questions / problems!

Even if you don’t have a need this script before /after business, I hope you got something out of this anyway!

You may also like...

2 Responses

    • camerongregor says:

      Haha I had not seen that at all!
      I was thinking to myself, “I wonder why Sven didn’t bother to do this?” 🙂
      I have updated my post with a link to your solution!

      Now I wish that I had blogged about something else 😐

Leave a Reply

Your email address will not be published. Required fields are marked *