Genii Weblog
Creating an effective sample
Wed 4 Feb 2004, 10:30 PM
Tweetby Ben Langhinrichs
10:30pm - First impressions
Customers who use Midas often tell me that they decided to buy the product the first day they used it, based on either a standard sample database such as Send It! or a custom sample such as those I produce frequently for customers. For that reason, the sample database is incredibly important, and I thought it might be useful to describe the process I use to create an effective sample.
Rather than waxing poetic or theorizing, I decided the best way to describe the process was to record it as it happens. I plan to take you with me through the process of creating a sample for a developer. He has been working with Midas for a while for one customer, but had a requirement at a different customer and found a post of mine on the Gold forum describing a possible solution using Midas.
Nighttime is usually the best time for writing samples, because there is less chance of being interrupted, and an effective sample requires some degree of focus. (I have two teenagers, and customers in all sorts of time zones, so any degree of focus is relative) Thus, I am starting at about 10:30pm when my youngest is in bed and my older two are at least out of my wife's hair. I have also added the music currently playing to give you a feel for the mood.
10:34pm - Information gathering ("Pablo Picasso" - The Modern Lovers)
The first goal is to collect what information I have and make sure I know what the sample needs to demonstrate.
<<For another customer I am writing a Notes app that stores personnel info and requires some quite complex searching. I've done all of this in LotusScript building up a string for FTSearch. This works fine, but when I put the results into a folder it does not highlight the search terms, which is proving to be quite an issue. I noticed that in Notes.Net you responded to a similar question and said that the Midas LSX can do the trick. I've also seen the example on the web. Would this example work in the Notes client? If so I presume it requires the client licenses for all of the users? If this really can do the highlighting that Notes cannot, then this might be another sale. >>
The "example on the web" is from our Midas Demos page, and it is called Highlight Search Term (go ahead and try it - it won't bite). The description of the demo says, in part, "allows you to highlight search terms with much more control than the &Highlight syntax gives you" and "You can set the font, text attributes and color of the highlighted term, and not modify the document at all." I am not sure what post is referred to, so I can't look at that, but I do know that Midas can handle highlighting in the Notes client without modifying the document. The trickiest thing is going to be finding out what the "string for FTSearch" is, but in that I am out of luck, since I can't contact the developer now, and he needs a sample by tomorrow morning for a meeting with the customer. I'll have to guess and give some alternatives.
The customer uses 5.0.10, so I'll write this in R5 (5.0.11) and test in ND6 (6.0.2) and an earlier R5 (5.0.6).
10:48pm - Creating the sample ("Hanging on the Telephone" - Blondie)
The first step is to figure out whether to start with my standard Midas Sample template, which has some basic boiler plate views and forms and agent stubs, or whether to copy an existing sample with some similar requirements. Since this sample sounds a bit like the Medical Cross Reference sample I have shown at Lotusphere a couple of times, with the need to modify the rich text without modifying the document, and the need for some documents with random text in them, I will start by copying the MedXRef.nsf database to a new database called HighlightSearchTerms.nsf.
I copied just the design, and will then paste in the medical articles, since I don't need all the specific glossary terms and such. I get rid of the extraneous views, image resources and forms, since anything left over will confuse the developer and potential customer. I have learned to leave all the agents for now - I can cull later.
11:01pm - Setting up the sample scenario ("Peaches" - The Stranglers)
To be effective, it is important that it be readily obvious what views do what and which options are available. On the web, it was easy to add a URL parameter to highlight the appropriate terms, but the developer stated the problem quite clearly "when I put the results into a folder it does not highlight the search terms". Therefore, I need to set up a folder, and make sure that when a document is opened from the folder, the search terms are highlighted. I also have to create a way to specify the search terms, since the developer describes "building up a string for FTSearch".
11:05pm - Keep it simple
Since we don't know how the search string is produced or what it contains, let's stick with complete simplicity. Let's put a view action in the Articles view where we specify the search terms. To start with, it will just be a list of terms, any of which will generate a match.
11:08pm - Priority interrupt
The reality of working at home. Moved a load of laundry, loaded and started the dishwasher. Checked on my youngest son, who was tossing a lot.
11:51pm - Back ("Falling for the First Time" - Bare Naked Ladies)
Switched the original formula language Select search terms view action to LotusScript so it would be easier to populate the folder. I always find myself writing and re-writing when creating samples, trying to get the right combination of incredibly simple and functional. The formula language version was:
ENVIRONMENT HighlightSearchTerms := @Implode(@Prompt([OKCANCELLISTMULT]; "List of search terms"; "Select the search terms you want to use:"; "anthrax"; "anthrax":"diseases":"sex":"smallpox":"vaccines"); ",");
""
which is fairly simple and elegant, but I don't know any easy way to also populate the folder without getting really complicated and calling an agent and such. Better to use the LotusScript version, which is longer, but solves both problems in one view action. Unfortunately, I still have to finish the LotusScript version later.
11:51pm - Back ("One Week" - Bare Naked Ladies)
Added the Search Results Folder. Checked to make sure there were no view events which could help.
12:14am - Adding the QueryOpen event ("Blitzkrieg Bop" - Ramones)
When you want to change the rich text contents without actually saving the document, you generally use the QueryOpen event, because you then have access to the NotesDocument.Handle (which is the NOTEHANDLE, for you C API types), which you can use in the ConnectBackend method. This lets you change the document after it is opened on the backend but before it is opened on the front end. Just remember to skip out of the subroutine if it is in edit mode or a new document.
This code is actually very easy to write. Here is my first version:
(Options)
Option Declare
Uselsx "*lsxrtc"
Sub Queryopen(Source As Notesuidocument, Mode As Integer, Isnewdoc As Variant, Continue As Variant)
' *** Domino backend class objects
Dim doc As NotesDocument
' *** Midas Rich Text LSX backend class objects
Dim rtitem As GeniiRTItem
Dim rtchunk As GeniiRTChunk
' *** Miscellaneous processing variables
Dim searchTerms As Variant
' *** Skip unless we are in read mode and not a new document
If mode Or IsNewDoc Then Exit Sub
' *** Connect to the Body field of the current document
Set doc = Source.Document
Set rtitem = New GeniiRTItem
Call rtitem.ConnectBackend(doc.Handle, "Body")
If Not rtitem.IsConnected Then Exit Sub
rtitem.HighlightFont = "+Italic Blue"
Set rtchunk = rtitem.DefineChunk("Everything")
' *** Highlight search terms
searchTerms = Evaluate(|@Explode(@Environment("HighlightSearchTerms"); ",")|)
Forall term In searchTerms
If term <> "" Then Call rtchunk.HighlightText(term)
End Forall
End Sub
12:42am - Blogging is slowing this down ("Prologue" - The Wiz)
While this is an interesting experiment, the constant recording is slowing down the process considerably.
12:47am - Finishing up the view action ("Tornado" - The Wiz)
Went back to the view action and added calls to NotesCollection.RemoveAllFromFolder and NotesCollection.PutAllInFolder to clear and re-populate the folder. A whole lot of re-arranging to make what is happening clear. The search terms are built into a string with " or " between them, and into an environment variable with "," between them.
01:21am - Changing the highlight ("No Bad News" - The Wiz)
Everything seems to be working, but the highlight font I chose, "+Italic Blue", looks odd in some cases. It also has the possibility of not showing results properly if anything is either blue or in italics to start with. I switch this to "+HighlightYellow", which looks much better, as it uses the text highlighting feature (see Text - Highlighter - Use Yellow Highlighter), which seems somehow appropriate. I add a comment in the code that this could use some other font string instead. It is important to comment samples so that the developer can tell what is happening, but remember that the comments need to be very focused on taking this logic somewhere else, not just using it in place.
01:27am - Testing the sample ("Hong Kong Garden" - Siouxsie & The Banshees)
Added in a few tests for situations such as not picking any search term (aborts and lets you know why).
01:33am - Moved view action to agent and added to folder ("Top of the Pops" - The Rezillos)
Made the view actions for both the Search Results Folder and Articles view into simple actions which run the agent. Tested everything one more time to be sure that it was clear what was happening, that it was hard to break, and that the search results were terms people would see in the documents.
01:46am - Moved view action to agent and added to folder ("Suspect Device" - Stiff Little Fingers)
Well, that is pretty much it. Wrote a note to the developer, and sent out the sample. It took a good deal longer because I was recording everything, and I am up later than I would have liked, but I learned something about how I actually do this. When I find out how the developer and customer react, I'll let you know. Also, the sample is good enough that I'll try to make it into a publishable sample, which requires a whole new set of steps. Perhaps I should blog about that as well.
01:48am - Goodnight!
Thanks for sticking with me on this experiment for so long. Let me know what you think about a) the process, and b) the blogging about the process.
Copyright © 2004 Genii Software Ltd.
What has been said:
109.1. Duffbert (02/05/2004 05:29 AM)
Interesting insights into both your process and into the mindset of a developer. Thanks for sharing that.
109.2. Tony Lee (02/05/2004 09:54 AM)
I see we share the same taste in music. I find when I concentrate the music is background, but if I start to lose my concentration, the punchier beat gets me back into it.
109.3. chris king (02/06/2004 03:54 PM)
how'd you get your formula language into your blog with the colors intact?
109.4. Ben Langhinrichs (02/06/2004 06:43 PM)
It is a little trick I have with our Midas Rich Text LSX when it generates HTML. I could write a sample to show you how, but it is a Friday night, so maybe Monday. <grin>
109.5. Abhijeet (05/08/2005 08:21 PM)
Hi Ben;
I am using version 6.5.40.5095 of nlsxbe.DLL( The Domino object type library).
I am using VS.NET to Interop with the type lib.
For some reason I am not able to access the Handle property of the NotesDocument object.
The property does not show up in intellisense and I get a compilation error if if I have something like "mDoc.Handle" in my code.
I'd appreciate any insight you can provide in this matter.
Thanks
Abhijeet