With the inclusion of the Extension Library as core in Notes and Domino 9, there are eleven new @Functions provided for SSJS. They can be found in the Designer Help in IBM Domino Designer User Guide > Designing XPages Applications > Adding Controls from the XPages Extension Library > @Function (Extension Library). Note, you will not find these @Functions listed alongside the other XPages @Functions, so if you use search scopes in the Eclipse-based help, you’ll need to add this section.

And you’ll want to, because they are very useful if you use a lot of SSJS. Some of them fall into distinct groups.

The first I’ll cover are @Functions for posting to xp:message (Display Error) and xp:messages (Display Errors) controls. They are @InfoMessage, @WarningMessage and @ErrorMessage. They each add messages for the user, great for error or other message handling. For those starting out on using Java, they’re also very useful to review because you can download the Extension Library and see what is happening under the hood. As with the others, they’re in the NotesFunctionsEx class of the com.ibm.xsp.extlib.javascript package of the com.ibm.xsp.extlib.domino plugin project. They each call FacesContext.addMessage(), each adding a message with a different severity – SEVERITY_INFO, SEVERITY_WARN and SEVERITY_ERROR.

The second group of @Functions are for URL handling – @AbsoluteUrl, @EncodeUrl, @FullUrl and @IsAbsoluteUrl. @FullUrl provides the URL for the resource relative to the server, @AbsoluteUrl includes the server host name and protocol. For those getting started with XPages, @AbsoluteUrl, @EncodeUrl and @FullUrl call static methods in the NotesFunctionsEx method that can be called from Java – absoluteUrl(String), encodeUrl(String) and fullUrl(String). So you can call them from Java as well. The last one already exists in Java – com.ibm.xsp.util.FacesUtil.isAbsoluteUrl(String).

The remaining new @Functions are @NormalizeSubject, @TopParentID, @TopParentUNID and @ViewIconUrl. @NormalizeSubject is useful to return “Untitled” if the text passed in is blank or restrict it to a number of characters, by default 80. Again, there’s a Java method in the same class, normalizeSubject(String subject, int maxlength). @ViewIconUrl is useful for taking a view icon number and returning the URL for the relevant icon. That doesn’t have a specific static method, but there’s nothing stopping you using the code, if you want to use native Java.

The other point of this is to highlight the amount of code required to provide SSJS @Functions. For those 11 @Functions, the Java class is 599 lines long. We’re looking to provide the same functionality for the new methods in org.openntf.domino, and we currently have about 50 new methods. Needless to say, it takes quite a bit of work to extend them to SSJS. We’ve already added them for the DateTime class, but there are a number of others yet to do. But we want to get there.

So in the meantime enjoy the @Functions provided now out-of-the-box in Notes and Domino 9.

2 thoughts on “New Notes 9 @Functions”

Leave a Comment

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.