We all know that XPages can do lots of funky stuff; however, sometimes we need to step beyond what it can provide ‘out of the box’. This could be anything from a jQuery plug-in to a complete client side framework such as AngularJS. We may even be using the XPage as just a container for holding externally created HTML/JavaScript, making use of XPiNC (XPages in the Notes Client) to display a beautiful Notes homepage.

All of which is possible, although you do need to be aware of certain techniques that may need to be used when implementing HTML/JavaScript not originally intended for an XPage.

Adding a class or attributes to the <html> tag

Use the this.attrs tag just underneath xp:view. Example:

<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:attr name="class" value="no-js"></xp:attr>
<xp:attr name="ng-app" value="notesHomeApp"></xp:attr>

Adding a class to the <body> tag

Append it in the xp:view with styleClass.

<xp:view xmlns:xp="http://www.ibm.com/xsp/core" styleClass="app">

Adding attributes to the <body> tag

This needs to be done by extending the ViewRootRenderer class and overriding its encodeHtmlBodyStart method. Full details on how to do this are in the Stack Overflow post here.

Specifying the ID of an element

Use the attrs tag with the name ‘id’, which will override the generated ID (make sure it’s unique though).

<xp:attr name="id" value="search-results"></xp:attr>

Adding an attribute with no value

This gets reported as an error and prevents a compile. To get round this, add as an attribute with the minimized parameter set to ‘true’.

<xp:attr name="ng-cloak" value="ng-cloak" minimized="true">

If it’s not an xp: element then turn it into one (see below).

Converting HTML elements into xp: controls

Create an xp:panel and set the tagName attribute, so:



<xp:panel tagName="ul">

Dealing with reserved XML characters (e.g. ‘&&’) used as logic in attribute values

If possible, move the logic into a function in the framework itself. So, for example, the following AngularJS attributes on this span won’t compile due to the ‘and’ operation:

<span ng-show="group.edit && $index > 0" ng-click="removeGroup($index)">

To fix this, create a new AngularJS JavaScript function:

$scope.performAnd = function(variable1, variable2)
return(variable1 && variable2);

…and call this to perform the ‘and’ operation instead:

<span ng-show="performAnd(group.edit, $index > 0)" ng-click="removeGroup($index)">

Controlling the <form> tag

You can disable the auto-generation of the <form> tag (which by default encapsulates the whole page) by setting createForm to false in the view tag:

<xp:view xmlns:xp="http://www.ibm.com/xsp/core" createForm="false">

If you want the <form> tag to contain a particular portion of the XPage, disable the main one with createForm=”false”, then add your own with <xp:form>.

Removing all theme CSS

To take control of all CSS (including any from the theme) – create a new theme, and in the source remove the following text:


Save, then apply the new theme in the application’s Xsp Properties.

Disabling Dojo

By default, Dojo client libraries are included – which may conflict with code on your page. To disable this, add the following line to Xsp Properties:


Beware however that doing so will disable much functionality of any xp: controls on your page.