A handy undocumented Lotusscript NotesUIDocument method

Like many corporations we have a standard
signature that we encourage all our staff to use in their email. In versions
prior to release 8.5 there were two methods for signatures, a ‘Plain Text’
block of text or you could reference an external file like an image or
a bit of HTML. Although most email admins around the world would prefer
the plain text signature because it provides the most fedility when emailed
externally the folks in the marketing department designed the standard
signature making use of the corporate colors and styles so we created our
signature as a html file on the users machine by using the Signature
Wizard code provided by Rocky
and tying it into our corporate addressbook to lookup the information so
the end use didn’t have to enter in anything.

Now that Lotus Notes 8.5 is out the
way it handles signatures has changed. It is now a richtext field in the
users mailfile preferences we we decided to sit down and rethink the way
we get peoples signatures setup. We already have a couple of minor customizations
to the standard mail template so we decided on adding a button into the
users mail preferences that they could click and it would build the standard
signature and put it into the richtext field. The advantage of this solution
is that it would work across all platforms as Rocky’s original code only
seemed to work on Windows.

So what’s all this got to do with an
undocumented LotusScript call you ask? Well during the course of rewriting
the code I had hit into the bane of the Notes UI developer’s life, updating
a richtext field while working with a UIDocument that was on the screen.
if you have ever done any UIDoc work you will know that updating a richtext
field normally involves saving and closing the document and then reopening
it to get it to display the updated field. There are a couple of workarounds
but nothing that will give the end user that perfect UI experience like
reopening the mailfile preferences to the correct tab in the tabbed table.

While working on my solution I noticed
a method popping up on the autocomplete for the NotesUIDocument called
ImportItem. A quick look in the documentation revealed nothing, it is not
a documented method. I then scanned the mail template using one of my favorite
TeamStudio tools and found that IBM were using this method in the ‘ImportSignature’
agent in the mailfile. This agent is used to append the signature from
the mail preferences to whereever the cursor is in the body of an email.
What’s interesting is that it is a NotesUIDocument method that is updating
a richtext field ( the email body ) without having to do the whole save,
close and reopen.

A little experimenting and I had my
new signature code up and running. I created a temporary document in memory
with a single richtext field in it and then used the NotesRichText classes
to build the signature while looking up the information form the corporate
phonebook. Once the signature was built I used the NotesUIDocument methods
to get to the Signature_Rich field in the mailfile preferences, cleared
out everything that was already in that field and then called uidoc.importitem(tmpDoc,tmpRTField)
and bingo, the richtext that I had build in my temporary document appeared
in the richtext field in the users mailfile preferences. The end use can
now make any manual chances they want and then save their mailfile preferences.

Hopefully this undocumented method will
be of use to others, anywhere you need to update a richtext field on a
UIDocument you can build the richtext in a temporary place then use the
UIDocument to set the insertion field and point and call this method to
pop the richtext directly into the field without having to go through the
save, close and reopen workaround.