As part of a current XPages project we had the need to capture comments from the user when they edit certain documents. Similar functionality was developed for a Notes Client application before I joined Intec, using a dialog box in the PostOpen / QueryModeChange event to force the user to enter comments. My intention, therefore, was to reproduce the same process in XPages. Because I wanted the functionality in a number of XPages, and because it was functionality that could certainly be beneficial for other projects, I developed it deliberately to work as a standalone custom control. I also took the time to include a Design Definition explaining how to implement it, as Steve Castledine explained a couple of months ago on his blog (http://www.stevecastledine.com/sc.nsf/dx/providing-illustration-for-your-xpage-custom-controls-design-definition?opendocument).
As you can see from the screenshot the functionality triggers a dijit dialog box for comments, with validation to ensure the user doesn’t just cancel the dialog or click OK without entering comments. The comments are then stored in a viewScope variable, which can be used in querySaveDocument code to pass back into the relevant field of the document. To get the dijit dialog working I must mention two articles which were very useful, one from Julian Buss’ YouAtNotes blog (http://www.youatnotes.de/web/youatnotes/blog2.nsf/dx/xpages-display-a-panel-as-nice-dojodijit-dialog-on-page-load.htm) and the other from Mark Hughes’ blog.
If you look at the sample database, the custom control that does the audit trail is called auditTrail. This includes two resources – the dijit.Dialog dojo module and dialog.js script using the dialog_create function from Mark Hughes’ blog. One other point worthy of note is code in the custom.css to suppress the close icon from the dijit dialog:
Other styles are from the OneUI2 styles, as found in Niklas Heidloff and Steve Castledine’s XPages Framework on OpenNTF. A script block launches the dialog box on load, using XSP.addOnLoad. The audit trail inputTextarea is bound to a viewScope variable. The Close button uses client-side javascript to validate the dialog and does a partial refresh on close. For this purpose it expects a mainTable element on the form.
The custom control can be seen implemented on the frmKeyword custom control. The auditTrail custom control is only rendered if the currentDocument is not a new note and if the currentDocument is in edit mode (code throughout uses currentDocument, so you don’t need to change dominoDocument variables). Code in the querySaveDocument event of the dominoDocument then saves the viewScope back to an Audit field of the currentDocument along with the user’s name and server date/time, appending any existing audit trail comments.
Even if the custom control itself is not of use, I hope some of the incidental techniques may be of interest.
Currently the code in this sample allows the user to click the Esc key to close the dialog. To prevent that I’ve posted an update to dialog.js { Link }