[Hi Everybody...Chris here. I'm very happy to be able to present to you the first guest post on Interface Matters. I thought this was a cool technique and since it was demonstrated to me using the Kwik-E-Mart database, how could I refuse! ;-) So, please welcome Keil Wilson with a great post on using an embedded view as a picklist. Take it away, Keil...]The problem…I’ve built dozens of applications that included Picklists (either @Picklist or NotesUIWorkspace.Picklist) to allow the users to select one or more documents from a list of documents. Generally, this Picklist is called from a button on a form that tests if the user pressed ‘OK’ or ‘Cancel’ and then performs some action using the selected document(s). The Picklist function in Notes is very cool for a number of reasons, but one of the biggest is that it just uses a Notes View to display a list of documents from which the user can pick. This gives you all of the formatting controls available to Notes Views and can help provide a consistent user experience so that the list of documents displayed in the Picklist looks just like the lists of documents displayed in your Notes Views. You can include the view icons or graphics, categories, and you can filter that list of documents displayed using view categories.
What if your users want to select documents from one of two or three different categories, though? What if, for instance, the users want the Picklist to show all accounts sometimes, current accounts sometimes, and past accounts sometimes? You have three different buttons on your form, right? If the user presses the wrong button, then they have to push Cancel to close that Picklist and then click the correct button. What if you could just have one Picklist that can display all three categories depending on which radio button or combo box selection the user chooses? We all work with similar dialogs on a regular basis, like the “Choose address book” combo box on the Select Addresses dialog in the mail file or the “Server” selection combo box in the open database dialog.
This was my challenge recently, and while the solution I developed wasn’t without compromise, I think it gets pretty close to a Picklist with multiple options for the documents displayed in the list.
About this example…This review will use Chris’
Kwik-E-Mart Squishee Order System as an example (
get the database now). The challenge here was to add an action on to the “Kwik-E-Mart Squishee Order Form” form that would allow the user to copy an existing Squishee order item. To do this, the user would select the existing item from a Picklist like control that could be filtered to show only those Squishee order items on the current order form, or show all Squishee order items in the whole system.
Check out the video demo of this in action...The above dialog box is triggered from a simple action hotspot on the “Kwik-E-Mart Squishee Order Form.” There are six design elements involved in the technique I used here. There are two embedded views (Current Customers & All Customers), two shared actions (OK & Cancel), the “Copy an Order” dialog box (on which the two views are embedded in a programmable table), and the modified “Kwik-E-Mart Squishee Order Form” originally created by Chris (the only change was the addition of the “Copy Order” action hotspot). The key concepts here are: 1) a dialog box with a two row programmable table that displays each embedded view based on a radio button selection, 2) the use of the action button bar on the embedded views to create/display the “OK” and “Cancel” buttons, and 3) storing of the selected document’s NoteID in the Notes.ini file for later use after the dialog box has gone out of scope. All of these are simple concepts (often discussed before by Chris and other developers), but they come together to make a flexible and functional solution.
So let’s start with the views…In the Kwik-E-Mart Squishee Order System, there was an existing view that did almost exactly what I wanted. So I did what any good coder does…I copied it, modified it slightly, and am now taking credit for its form and function. In fact, I did that twice. So the embedded view on Chris’ “Kwik-E-Mart Squishee Order From” has been adapted to work in the “Copy an Order” dialog box. It is important to note here, that because I’m working with essentially the same view that Chris had already taken the time to create, test, and format beautifully, not only did that lighten my work load, but it also provides a pretty consistent look and feel on my new dialog when compared to the existing system. Once I had modified the views’ selection formulas and columns to meet my needs, I cleared all of the action buttons from the view. Now all I needed were my two new action buttons.
Actions are the key…The view action buttons are the key to this whole solution, as well as the weakest point. In order to determine which document(s) were selected in the embedded view, I needed a way to trigger some event within the embedded view. I tried several different things, like Queryclose (which doesn’t fire in an embedded view), but nothing worked. Finally, after some research on the developerWorks forums (and reading posts like
this one from Jamie Grant), I decided to try replacing the dialog box form’s “OK” and “Cancel” buttons with view action buttons. Notes gives developers a lot of control of the look of view action buttons, but their placement above the view is pretty much locked down. It is this unorthodox placement for the “OK” and “Cancel” buttons that gave me the biggest pause about this approach.
Because both embedded views display the same type of documents and I wanted to do the same thing with the selected document regardless of which view was displayed, I was able to create two shared actions (one for “OK” and one for “Cancel”) that would go on both views. I had to do a lot of tweaking on the format of the view action bar for each view. If you’ve never tweaked the action bar properties (accessing these properties is less than intuitive), you can right-click in the Action Pane in Domino Designer and select “Action Bar Properties…”, or you can click anywhere in the Action Pane and select “Action Bar” in the properties box list. Use the Notes help and take some time exploring all the action bar properties options and what they do. I’ll explain what the buttons do, but you can download the sample database to see the code.
The code behind these action buttons is very simple. The OK button does four things:
1. Get a handle to the parent form/document currently open in the UI (our dialog box).
2. Get a handle to the document that is currently selected in the embedded view.
3. Copy the NoteID of the selected document to an environment variable in the Notes.ini.
4. Close the dialog box using the UI handle we got earlier.
The “Cancel” button does three things:
1. Get a handle to the parent form/document currently open in the UI (our dialog box).
2. Clear any value in the Notes.ini variable (this indicates the user pressed “Cancel”).
3. Close the dialog box using the UI handle we got earlier.
Using the environment…Back on the “Kwik-E-Mart Squishee Order From” our “Copy An Order” button has called our dialog box and is waiting for the user to select their Squishee order item to copy. Then the user presses “OK” (or “Cancel”), the dialog box closes and control comes back to the “Copy An Order” code. This code does the following three things (again, download the database to see actual code):
1. Test the return from the dialog box to see if the user selected something. This is done by checking if the environment variable we set earlier has a valid NoteID in it. If there’s nothing but an empty string (“”), then the user pressed “Cancel.” If there’s anything but an empty string or a valid NoteID in that variable, then we’ve got an error.
2. Assuming the user has pressed “OK”, we then create a new copy of the selected document and associate it with the current “Kwik-E-Mart Squishee Order Form.”
3. Finally, we refresh the embedded view and the current UI document. This causes the new document to be displayed in the embedded view.
And Then?!So how could I have done this better? I was a bit uncomfortable about writing/reading stuff in the Notes.ini file (maybe that’s just a hold over from my R4 past), but everything seems to be pretty stable. The other major concern I had was about the location of the “OK” and “Cancel” buttons. Does anyone find the non-standard layout of the buttons unappealing or problematic? I tested this with the users and no one commented on it at all. Is it possible that button location is a bigger deal to me than it is to my users? I’m interested to hear how others could (or already have) improved on this approach. Thanks for reading.
About The Author: I've been a Notes/Domino developer and consultant in Nebraska for about 10 years. I've spent the last several years working on a Notes Client focused development project for a government agency in Nebraska. The scope of this project requires innovative solutions to typical Notes Client limitations (one of the reasons I love Interface Matters). In my past lives I spent time at several small companies managing networks, manning help desks, implementing Crystal Reports/Crystal Enterprise solutions, developing and administering training, and writing code in Notes, VB6, SQL, Java, and C#.
