DontPanic - a blog about Lotus Notes / Domino

Custom Control for custom layout of checkboxes

2013-05-21T09:53:00.001+01:00

In a recent project, I wanted to create an interface to toggle different settings for different user types in an app. To save real estate on the page and (hopefully) make it more intuitive, I wanted to have a column per user type, and organize the checkboxes vertically.

I couldn't find any way to do this out of the box. To make it work, I made a regular checkbox group per field. Then in a repeat control, I have regular HTML checkboxes with name fetched from the real checkbox group. The checkbox group has to have the same values as the HTML checkboxes, or the values will be discarded.

The checkbox component is removed from the DOM via javascript when the page loads. If the real checkbox component isn't removed, you will only be able to select, and not deselect.

Screenshot from the demoapp (each checkbox column is bound to a multivalue field):

The custom control has four properties:

checkboxValues: Array of strings - Values for the checkboxes
fieldNames: Array of strings - Names of the fields in the form you want to connect the checkboxes to (remember to set them to multi-value in form)
headerLabels: Array of strings - Header labels for the checkbox columns
rowLabels: Array of strings - Labels for the checkbox rows

Currently, the custom control uses currentDocument to bind the fields. If the control doesn't work, you might need to use a more specific document data source.

Example usage

<xc:CheckboxTable checkboxValues="#{javascript:return ['inbox','outbox'];}"
   fieldNames="#{javascript:return ['hidden_items_administrators','hidden_items_users','hidden_items_limited_users'];}"
   headerLabels="#{javascript:return [labels.administrators, labels.users, labels.limitedUsers];}" rowLabels="#{javascript:return [labels.inbox,labels.outbox];}" />

The demoapp has been tested/works in these browsers: IE8/9 (should work in earlier browsers, but the layout is ugly), latest versions of Chrome, Firefox and Opera.

>> Download demoapp

The technique I used (real+"fake" checkboxes) should enable you to customize the layout of checkboxes however you want. I imagine the technique should also work for radio buttons.

Fix for partial refresh on Dojo Tab Container/Content Pane

2013-03-20T09:00:00.000+01:00

I wrote this a while back, but I couldn't find that I'd shared it.

You need to use the partial refresh hijacker to use the code snippet.

This code snippet initializes Dojo Tab Containers/Dojo Content Panes in the area that's refreshed:

// Fix problem with partial refresh on Dojo Tab Container/Content pane
// Source for inspiration:
// http://www.openntf.org/projects/pmt.nsf/0/D228115FAA98DDEC86257A7D0050E7FF
dojo.subscribe( 'partialrefresh-complete', this, function( method, form, refreshId ) {
 var tabContainersAndContentPanes = dojo.query( '[id=' + refreshId + '] .dijitTabContainer[widgetid], ' +
  '[id=' + refreshId + '] .dijitContentPane[widgetid]' );
 if( tabContainersAndContentPanes.length === 0 ) {
  return;
 }
 
 for( var i = 0; i < tabContainersAndContentPanes.length; i++ ) {
  var widgetId = tabContainersAndContentPanes[i].getAttribute( 'widgetid' );
  var widget = dijit.byId( widgetId );
  if( widget ) {
   widget.startup();
   widget.resize();
  }
 }
} );

Add the code snippet in a dojo.addOnLoad function or something similar.

If you have other widget types that fails to initialize, just modify the selector/startup commands to fix.

Small LS class that can be used to check if fields have changed

2013-01-18T10:05:00.000+01:00

We've had some issues with semaphore locks on one of our import databases. The import database has routines that import/update data, then replicate it to a cluster when it's done.

We're not exactly sure what triggers the locks, but the server crashed sometimes several times a day, so we decided to see if the import routines could be optimized to do as few writes as possible.

Several of the routines saved documents even if there were no field changes. I wrote a simple class to test for field value changes.

'// Used to test if certain fields have changed
Class FieldChangeChecker
 Private fieldsToCheck As Variant
 Private fieldValues List As Variant
 
 '// Run this after calculcation/etc. to see if specified fields have changed
 Function haveFieldsChanged( doc As NotesDocument ) As Boolean
  On Error GoTo bubbleError
  
  If doc.isNewNote Then
   haveFieldsChanged = True
   Exit Function
  End If
  
  Dim initialValue As Variant, currentValue As Variant
  ForAll fieldName In Me.fieldsToCheck
   initialValue = Me.fieldValues( fieldName )
   currentValue = doc.getItemValue( fieldName )(0)
   
   If initialValue <> currentValue Then
    haveFieldsChanged = True
    Exit Function
   End If
  End ForAll
  
  Exit Function
bubbleError:
  Error Err, errorMessage()
 End Function
 
 '// Comma separate field names. E.g. "forename,surname"
 Sub New( ByVal commaSeparatedFieldNames As String )
  On Error GoTo bubbleError
  
  Me.fieldsToCheck = FullTrim( Split( commaSeparatedFieldNames, "," ) )
  
  Exit Sub
bubbleError:
  Error Err, errorMessage()
 End Sub
 
 
 '// Run this before calculation/etc.
 Sub readInitialValues( doc As NotesDocument )
  On Error GoTo bubbleError
  
  ForAll fieldName In Me.fieldsToCheck
   Me.fieldValues( fieldName ) = doc.getItemValue( fieldName )(0)
  End ForAll

  Exit Sub
bubbleError:
  Error Err, errorMessage()
 End Sub 
End Class

Example of use:

..
Dim fieldChangeChecker As New FieldChangeChecker( "FirstName,LastName,Address,PostCode,City" )
Set customerDoc = customersView.getFirstDocument()
While Not customerDoc Is Nothing
 Call fieldChangeChecker.readInitialValues( customerDoc )

 '// Code that looks up the newest information and sets fields

 If fieldChangeChecker.haveFieldsChanged( customerDoc ) Then
  Call dataDoc.Save(True, False) 
 End If

 Set customerDoc = customersView.getNextDocument( customerDoc )
Wend
..

Regarding the errorMessage-function in the class. I use error bubbling in all my LS code. If something fails somewhere in a routine, I want the routine to stop executing. At the top of the stack, I use OpenLog/LogError. This gives me a nice pseudo stack of the function calls.
Code for errorMessage function:

Function errorMessage As String
 '// Simple function to generate more readable errors when dealing with error-bubbling
 Dim message As String
 message = Error
 
 If CStr( GetThreadInfo(10) ) = "INITIALIZE" Then
  errorMessage =  "Error " & Err & " on line " & Erl & " in function " & GetThreadInfo( 10 ) & ": " + Error
 Else
  errorMessage =  Chr(13) + Chr(9) + "Error " & Err & " on line " & Erl & " in function " & GetThreadInfo( 10 ) & ": " + Error$ 
 End If 
End Function

Code Snippet - Close dialog if all fields are valid

2012-10-12T07:36:00.000+01:00

Today I was working on a dialog that had fields with validation. I only want to close the dialog if all fields are valid. I'm not aware of any inbuilt XSP methods that does this. This code snippet checks for any invalid fields in the dialog. If all fields are valid, the dialog is closed.

function closeDialogIfValid( dialogId ){
 var invalidCount = dojo.query( '[id="' + dialogId + '"] [aria-invalid="true"]' ).length;
 if( invalidCount === 0 ){
  XSP.closeDialog( dialogId );
 }
}

This probably only works if you're using server side validation.

If there is something like this in the XSP API, please let me know.

Share and enjoy!

Snippet to clear session for user

2012-09-06T11:35:00.000+01:00

During testing, I sometimes log in as different user to test hide/whens/etc. I used to delete the SessionID cookie in the browser to clear session scoped beans/sessionScope variables. Today, I looked for a solution to automate this. This line will clear all objects related to a session:

facesContext.getExternalContext().getSession( false ).invalidate();

If you want to clear session when logged in user changes for the current "XPages" session, here's the snippet I use (put the code in afterPageLoad or beforePageLoad):

// Reset session when user changes
var currentUserName = sessionScope.currentUserName;
var userName = session.getEffectiveUserName();
if( currentUserName && userName !== currentUserName ){
 facesContext.getExternalContext().getSession( false ).invalidate();
}   
sessionScope.currentUserName = userName;

I would think this is better than deleting the cookie, as the server is immediately notified that it should flush the objects bound to the session. When I delete the cookie, I believe that the objects are kept in memory until a specified timeout.

Comprehensive guide to Design Definitions

2012-08-20T13:17:00.000+01:00

I found this guide in IBM's Application Development wiki while looking for information on Design Definitions:
Native and Custom Control Custom Visualization Best Practices

So far it's the most comprehensive guide to Design Definitions I've found.

XPages - Grouping data in comboboxes

2012-07-27T13:13:00.000+01:00

I wanted to have some values grouped in a ComboBox. Not sure if it's possible to do with pure SSJS (without using the Java API), but found a way using beans:
JSF Tree in a dropdown (see accepted answer).

The resulting html is select node with options grouped in optgroup nodes.

Multi value fields and Beans in XPages

2012-06-25T08:02:00.000+01:00

I had an issue with multi value fields bound to bean fields in an XPages I worked on.

I got this error message on refresh:

java.lang.IllegalArgumentException: argument type mismatch

The issue turned out to be a somewhat inconsistent underlying API. When the field is empty, or has single value, it tries to set a string. When there are multiple values, it tries to set a list.

To work around the issue, have the getter return an Object, and the setter accept an object.
E.g.


public Object getInputMulti() {
 return this.inputMulti;
}
...
@SuppressWarnings( "unchecked" )
public void setInputMulti( Object inputMulti ) {
 if( inputMulti == null ){
  this.inputMulti = null;
 }
 
 if( inputMulti instanceof String ) {
  Vector inputNameList = new Vector();
  inputNameList.add( (String) inputMulti );
  this.inputMulti = inputNameList;  
 }
 if( inputMulti instanceof List ) {
  this.inputMulti = (Vector) inputMulti;
 }
}

You can have the translation for the setter be done in a utility method. E.g.

@SuppressWarnings("unchecked")
public static Vector translateToVector( Object object ){
 if( object instanceof String ){
  Vector list = new Vector();
  list.add( object );
  return list;
 }
 
 if( object instanceof List ){
  return (Vector)object;
 }
 
 return null;
}

Then, for the setter:


@SuppressWarnings( "unchecked" )
public void setInputMulti( Object inputMulti ) {
  this.inputMulti = UtilityClass.translateToVector( inputMulti );
}

Example of multi value fields: Checkbox group, multi value fields (fields with multipleSeparator), list boxes.

Update for Enhanced Messages Control - Show "system" messages

2012-06-22T16:36:00.002+01:00

In response to this question on the XPages Forums, I've updated the source code for my Enhanced Messages Control, so that it also shows messages not bound to controls.

The "system" messages are show above the messages from components.

Update for Enhanced Messages - Now in page order

2012-06-08T22:30:00.000+01:00

I added a small snippet of code that sorts the messages in the order that the components are in the page.

I only had a simple page to test on, but in theory it should work for large pages with complex structure.

Original post with source code for custom control

Improving performance in Domino Designer when developing XPages

2012-05-31T13:17:00.002+01:00

If the XPage has a view data source/the view name is a static value, it looks like Domino Designer is constantly polling the view for column info/etc.

If you are done dragging and dropping columns from the view to the view panel/etc. Go into source mode and compute the viewName.

Before

<xp:dominoView var="view1" viewName="MyView" />

After

<xp:dominoView var="view1" viewName="${javascript:return 'MyView'}" />

When the view name is computed, Domino Designer can't determine what view it should check -> No more lag.

I haven't tested this with Document Data source, but you might get a performance boost if you compute the formName as well, as Domino Designer won't have to check the fields for drag/drop.

Optimally I would wish the Designer team implemented a refresh fields/columns button for the data pane.

Share and enjoy!

Using Java reflection and Domino form to auto populate beans

2012-05-29T19:51:00.001+01:00

>> Download DemoApp

Due to a lot of positive posts about using beans/MVC pattern for developing XPages apps, I've started writing more Java and less SSJS. I really like the performance improvements/stricter structure of code.

In one of my recent apps, I wrote a Model class for each of the forms in the app. The class has fields for all the form fields. Whilst writing the app, I thought about using Java reflection/Domino Form to auto populate the class instance. Java reflection lets you fetch methods from classes using their name (as a String). The Form class contains methods that lets you fetch all the declared field names in the form.

A couple of advantages to using auto population of fields is less code to maintain (~less bugs), and "auto discovery" of typos in either field names or getters/setters. If you call a field firs_name (typo), and write getters/setters for first_name, using the methodology I use, the code would crash, and you would instantly be aware of some error. If you use some kind of logging, you could look at the stack trace to determine what failed.

A couple of disadvantages. Using reflection/fetching field information adds a slight performance penalty. I don't notice any slowness, but it's something to be aware of if you're aiming for light speed/serving the entire Republic of China on one server. :)

In most of my apps, I use underscores to separate "words" in my field names. To make this work with reflection I convert the underscore field names to ProperCase, and prepend get/set.

E.g.
Field: first_name
ProperCased: FirstName
Getter: getFirstName
Setter: setFirstName

In the attached DemoApp, I have a helper class that deals with the most common field types. It has two methods:
setObjectFieldsFromDocument( String form, Object object, DominoDocument doc )
setDocumentFieldsFromObject( String form, Object object, DominoDocument doc ).

The first parameter is the name of the form that you want to use as "schema" for the population of the instance fields. The second parameter is the Java instance. The third parameter is a Document wrapped in a simple helper class.

The demoapp has a XPage that uses a controller bean (PersonController) to handle interaction with the model (Person). It's bound to view scope. When the XPage is loaded, it checks for a parameter (id). If id is available, the controller uses setObjectFieldsFromDocument to populate the model. When save is called, the controller uses setDocumentFieldsFromObject to update the underlying Notes Document with values from the model.

If this sounds interesting. Download the Demoapp, look at the Person XPage for the data binding, and use Package Explorer to take a look at underlying java code.

I'll just add the source code for the Person model class, in case some of you fear that everything in Java is complex

package com.dontpanic82;

import java.io.Serializable;
import java.util.Date;

public class Person implements Serializable {
 private static final long serialVersionUID = 1L;

 public static final String FORM = "Person";

 private String id;
 private String firstName;
 private String lastName;
 private String email;
 private String homepage;
 private Double age;
 private Date birthdate;

 public Person() {
 }

 public Double getAge() {
  return age;
 }

 public Date getBirthdate() {
  return birthdate;
 }

 public String getEmail() {
  return email;
 }

 public String getFirstName() {
  return firstName;
 }

 public String getHomepage() {
  return homepage;
 }

 public String getId() {
  return id;
 }

 public String getLastName() {
  return lastName;
 }

 public void setAge( Double age ) {
  this.age = age;
 }

 public void setBirthdate( Date birthdate ) {
  this.birthdate = birthdate;
 }

 public void setEmail( String email ) {
  this.email = email;
 }

 public void setFirstName( String firstName ) {
  this.firstName = firstName;
 }
 
 public void setHomepage( String homepage ) {
  this.homepage = homepage;
 }

 public void setId( String id ) {
  this.id = id;
 }

 public void setLastName( String lastName ) {
  this.lastName = lastName;
 }

}

XPages Toolbox - Really nice profiling tool

2012-04-19T07:27:00.006+01:00

If you feel that your XPage application is too slow, XPages Toolbox can help you to find the biggest bottlenecks in your code.

If you haven't tried it, I highly recommend that you give it a spin (it's free). If you like it, give it a good rating.

+1 to Philippe Riand for sharing it with the community :)

Showing horizontal notes data as vertical in view

2012-03-15T21:22:00.015+01:00

Today at work, I needed to transfer some data from a Notes application to SQL. The documents in question were horizontal.

An example of what I mean:
An order form in Notes with five order lines. For each line, there may be five fields that contains information about the order. Making it a total of 25 fields for five order lines.

Traditionally, if you want to show this data in a regular notes view, you have to have a column per field.

Thanks to the way the index is organized in a Notes view, you can show this data vertically using Show multiple values as separate entities.

A summary of the technique:

In each column, create a list of the field values that you want to show
Each column list has to have equal amount of values
Each column has to have Show multiple.. property enabled
Only the first column can be sorted (it can be categorized), or you end up with a lot of rows.
This is probably due to how the index is organized/matching of multiple values

Here's the demoapp I took the screenshots from:
>> Download

Take a look at the Vertical view to see the technique I used.

Thanks to this technique, I can simply pull the data from a view using view entries/column values/send row by row to a stored procedure in SQL. The alternative would be to write code for each field.

Share and enjoy! :)

Patch for bug in XSP.partialRefreshGet/-Post in 8.5.3

2012-03-08T13:01:00.005+01:00

Someone made a really stupid mistake in the code for XSP.partialRefreshGet/-Post in 8.5.3..

I won't go into specifics of the code as I'm uncertain if it's breaking some license. Let's just say that if they moved a line of code four or five lines upwards, there wouldn't be any bug.

I wrote a simple patch for the bug. Put it in a CSJS library, and your code will work like it did on 8.5.2 (unless I made a stupid mistake).

/**
 * Fix for bug with partialRefreshGet/-Post in 8.5.3
 */
(function(){
 var oldPartialRefreshGet = XSP.partialRefreshGet;
 XSP.partialRefreshGet = function( targetId, options ){
  // Convert to array
  var argsArray = Array.prototype.slice.apply( arguments );
  
  if( argsArray.length > 1 ){ argsArray[1] = argsArray[1] || {}; }  
  if( argsArray.length === 1 ){ argsArray.push( {} ); }
  
  oldPartialRefreshGet.apply( XSP, argsArray );
 };
 
 var oldPartialRefreshPost = XSP.partialRefreshPost;
 XSP.partialRefreshPost = function( targetId, options ){
  // Convert to array
  var argsArray = Array.prototype.slice.apply( arguments );
  
  if( argsArray.length > 1 ){ argsArray[1] = argsArray[1] || {}; }  
  if( argsArray.length === 1 ){ argsArray.push( {} ); }
  
  oldPartialRefreshPost.apply( XSP, argsArray );
 };
})();

This code should be forwards compatible with future API updates, as it doesn't assume number of arguments in function.

Runtime optimized JavaScript and CSS - workaround for multiple stylesheets

2012-01-26T09:55:00.005+01:00

Update: This workaround is only needed if you use "folders" in the image resource name.
E.g. backgrounds\home.png.

If you have multiple local stylesheets on a page, the CSS files are combined into a single file.

This changes the url to the stylesheet (adds xsp/.ibmmodres/.css after the path to the db).

If you have an image reference like url(image.png), the image can no longer be loaded, as the url is relative to the path of the stylesheet.

To work around this issue, add ../../../ to the image reference.

E.g.
url(../../../image.png)

Useful tool when working with text files (CSV, source code, etc)

2012-01-05T12:50:00.004+01:00

WinGrep is a tool that let's you search one/several folders for parts of strings. It supports searching in zip files, and lets you use Regular Expression (Perl syntax?) for searching strings.

The result pane shows all the matching lines in the file(s) you are searching.

Thing to be aware of when using "Generate unique keys.." in view

2012-01-02T12:43:00.004+01:00

I had trouble with a couple of views today. The views had the option Generate unique keys in index checked.

When the views were replicated to other servers, they weren't built. When trying to open them I got the error message Entry not found in index

I found the solution on the Domino forums, add @IsUnavailable($Conflict) to the view selection.

ClassNotFoundException with the new Java design element

2011-12-13T09:16:00.005+01:00

Last week Vince Shuurman blogged about having to recompile when opening an XPage app in Domino Designer.

I had the same issue. I was using some Java code in an XPage, and every time I opened the app in designer, I got ClassNotFoundException when opening the XPage. A build of the project fixed the issue.

My java code was in the new Java design element (new in Domino 8.5.3), so I suspected that it might have something to do with this.

I moved the code to a "custom" java source folder, and the error went away. Closing/opening the app in Designer did not result in ClassNotFoundException.

Java Debugging in Designer without hacks

2011-10-21T07:44:00.003+01:00

I found this today: How can I enable Java debugging?.

Not sure if this is new in 8.5.3, but I never heard of it. It makes it a lot easier to debug than the using the two headed beast method which seemed like too much trouble.

The full instructions are in the Designer help. Search for java debugging.

Collecting data for HTTP hang or performance issues on a Lotus Domino server

2011-09-28T11:12:00.001+01:00

We're currently having problems with one of our old Domino servers. The HTTP task randomly hangs.

In the process of looking for help to track down the reason, I found this document from IBM.

Collecting data for HTTP hang or performance issues on a Lotus Domino server

Indicator for all partial refreshes

2011-09-27T13:06:00.007+01:00

Sometimes partial updates take a while. To make users aware of updates happening, I made a small JS object that automatically shows a dojox.widget.Standby over the area being updated. Initially I thought that it would be too much, showing the mask over every refreshed area. So far, I quite like the effect.

The app isn't in production yet, so I don't know how users will react, but hopefully they will appreciate being made aware of that things are happening.

To load the object, put this in a JavaScript library (client side)

dojo.addOnLoad(function(){ new StandbyWidget(); });

The default background color is bright yellow. To override, simply put a hex string in the "constructor" call.

dojo.addOnLoad(function(){ new StandbyWidget( '#555'); }); // Dark grey

To use the code snippet below, you also need the partial event hijacker

var StandbyWidget = function( backgroundColor ){
 dojo.require( 'dojox.widget.Standby' );
 this.widget = new dojox.widget.Standby();
 this.widget.attr( 'color', backgroundColor || '#ffe' );
 
 document.body.appendChild( this.widget.domNode );
 this.widget.startup();
 
 dojo.subscribe( 'partialrefresh-init', this, function( method, form, targetId ){
  if( targetId && targetId !== '@none' ){ this.show( targetId ); }
 });
 
 dojo.subscribe( 'partialrefresh-complete', this, function( method, form, targetId ){
  if( targetId && targetId !== '@none' ){ this.hide(); }
 });
 
 dojo.subscribe( 'partialrefresh-error', this, function( method, form, targetId ){
  if( targetId && targetId !== '@none' ){ this.hide(); }
 });
}

StandbyWidget.prototype = {
 show: function( targetId ){
  this.widget.attr( 'target', targetId );
  this.widget.show();  
 },
 hide: function(){  
  this.widget.hide();
 }
}

Using themeId for maintainability

2011-09-26T18:46:00.014+01:00

In an application I'm currently working on, there are several categorized views with number-/totals columns. As the number of views/columns increased, I looked for a way to make styling of the columns more maintainable.

The solution I found was using themeId on the columns and calling a SSJS function in the theme, that generates the style classes.

I chose numberColumn as the name for the themeId.

In theme

<control>
 <name>numberColumn</name>
 <property>
  <name>styleClass</name>
  <value>#{javascript:return StyleHelper.getNumberColumnStyleClass( this );}</value>
 </property>
</control>

this refers to the column object.

SSJS code

var StyleHelper = {
 // Used to calculate styleClass for a number column
 getNumberColumnStyleClass: function( column ){
  try {
   var entry = column.getViewRowData();
   var styleClass = 'numberCell';
   if( entry.isCategory() ){ styleClass += ' categoryCell'; }
   if( entry.isTotal() ){ styleClass += ' totalsCell'; }
   return styleClass;
  } catch( e ){ /* Exception handling */ }
 }
}

Regular column cells will get class="numberCell".
Totals column cells will get class="numberCell totalsCell".
Category column cells will get class="numberCell categoryCell".

All I have to do to add dynamic styling to future columns is to set themeId on the column to numberCell.

XPages: Passing event handler code to custom control

2011-08-26T11:55:00.007+01:00

Update: After a little test, it looks like the onchange event of the combo fires for every refresh. I'll move the code to beforeRenderResponse or something like that instead.

In an application I'm currently working on, I have a combobox that's used in several pages. The values the combobox contains persist over every page, but what happens when the user changes value varies from page to page.

I saw that the combobox has several properties for events under all properties. I tried adding
#{compositeData.onchange} to the onchange event, and it works. One caveat is that it seems to fire three times, but I can live with that.

To implement:
Add custom properties to the custom control for the events you want to have custom event handlers for. In the source code of the field, add attributes for the events you want code to run. E.g. onchange="#{compositeData.onchange}"

In the XPage under custom properties for the custom control, write the SSJS you want to run for your events.

That's about it.

I have only tested this with ComboBoxes, but I'm not surprised if it works for most fields that have event properties.

Tested on server running Domino 8.5.2 FP2