Thursday, April 27, 2006

SnTT: Good Looking and Useable Form Validation

Ah...Form validation. A subject that could probably fill several tomes and has been source of debate since the web browser was first introduced. There are probably as many ways to implement validation on your web forms as there are opinions about the best way to do it. Even though there is a ton of information out there about the hows and whys of form validation, I still see many sub-par implementations of the concept in Domino-based web sites. This certainly has nothing to do with the technology itself. I think most of us know by now that you can do just about anything in Domino...even if it calls for righteous hacks. :-) So...what's the reason for poor validation techniques in Domino. Typically I've found that it's just that developers aren't aware of some simple, yet powerful ways to use web technologies in their apps. The purpose of this entry is to introduce you to a really easy technique that you can implement right away to have nice clean, useable validation in your Domino forms.

For our purposes today, I'm going to use client-side validation. That is, we'll use JavaScript to check the fields before the form is ever submitted to the server. This is fast and efficient, since we let the client do the work. Unfortunately, this can be handled very poorly. The most common implementation of client-side form validation I see is the use of the JavaScript alert function, which pops up a message to the user telling them that they forgot to fill in a certain field. This might be OK for only one or two fields, but beyond that it is bad news from a usability perspective. What typically happens is that the user fills out the field referenced in the alert box and then clicks the submit button again. If there is another field that fails validation, then an error message for that field pops up. Yuck...do this several times and bye bye user.

Aside: Always remember you can't just rely on client-side validation to do your work. Your user might have JavaScript disabled or a tricky hacker might find an easy way to exploit a hole in your app. Client-side validation is great for quick, immediate feedback to the user without requiring a trip to the server, but you have to do your true validation on the server-side.


A slightly better way is to provide a list of all fields that failed in a single alert call. At least this time the user knows everything that went wrong. The problem is the limited memory retention that we have. Once the user clicks the OK button to dismiss the dialog box, that's it...the validation message is gone. If there are several fields listed, the user either has to remember all the fields that need to be fixed or they have to jot them down. Again, not the best solution when you are striving for a useable app.

You can get really fancy with server-side validation, since you can write in lots of error information when you present the form back to the user. But in our case, how can we provide useful error information that doesn't interfere with the rest of the interface and still be quick and lightweight? Here's a picture of what I'm striving for. This example is from Amazon. Although their validation is done server-side, I want to mimic this kind of idea for my Domino forms.

amazon1


Here's the cool trick and secret to doing this...I create a hidden div which is used to display my validation messages. If validation fails, this div is revealed to the user. If you place this at the top of your form, the user sees the feedback immediately and can continue filling in the form while still referring back to the error messages. Of course, since this is all just HTML and CSS, your div can be positioned anywhere it makes sense in the context of your form. This is really flexible and easy!

The code to handle all of this is quite easy. First, check out the sample to see how this works...then come back.

OK...that's pretty cool, eh? Here's the code for the div that holds the error messages.




This div is empty and has a class I called "hideMe". For simplicity, my CSS definition for the classes that will show or hide this information looks like:



In practice, these classes might have more to them, but it's not necessary right now.

The "ErrorMsg" div resides at the top of the form. When the user tries to submit the form, the validation code is called. You can use whatever validation code you currently have (Jake has done some great stuff with this). In order to get this to work with your current validation routine, you'll just have to do a couple of extra things:

1. Construct your error message using HTML.
2. Write this message to the "ErrorMsg" div.
3. Show the "ErrorMsg" div by changing it's class to "showMe".

For this example, I took a very streamlined part of Jake's code to demonstrate. Here's the whole scenario step by step.

1. User opens the page and clicks the 'Continue' button. This invokes a call to the 'canYouDigIt' function.

2. 'canYouDigIt' builds an array to hold the required fields and the text that you want displayed in the error message.




3. It then calls the 'validateRequiredFields' function and submits the form if all is OK. If validation fails, it builds the HTML code that will be displayed to the user and then places that code in the "ErrorMsg" div using the innerHTML property. When that is done, it calls 'showIt' function to change the "ErrorMsg" div class to "showMe".



Note: empty_fields is a global variable that is declared in the JS Header.

In the event that validation fails, the HTML that you construct can be as simple or complex as you want. In this case, I built a fieldset and placed a table within that fieldset.

That's all there is to it. The cool thing about this solution is that it is pretty easy to plug in anywhere and requires a fairly small amount of code. Of course, there's a lot that can be done to improve it. Let's look at one other usability enhancement. I find that users really like it when they not only get a message of what needs to be fixed, but when they get a visual indicator on the fields themselves. This can be accomplished with the addition of just a couple more lines of code. In your validation code, when you find a field that fails validation, set the class of that field to "formerror". Then, in your CSS, define the properties you want for the "formerror" class.

Here's what I used:



With this little enhancement, the background color and border color of the field is changed and a small image appears. If this doesn't get their attention, then all is lost! ;-)

You can see how all this fits together by viewing the source of my sample page, but for completeness, here is the remainder of the code that does all the work. The code that is important for this example is the line where the class of the field is set to nothing (to reset possible past errors) and when it is set to "formerror" in the event that the field is blank.




If you got this far, congratulations...boy can I ramble on! :-) Anyway, I hope you find this a useful and user-friendly form validation technique. If you'd be interested in having this in a sample database, please leave a comment or ping me and I'll put one together. Cheers!

Technorati tags:

Sunday, April 16, 2006

Be A Lotus Evangelist...Start A Lotus Notes Power Hour!

Hi again...Happy Easter! Hope everyone got lots of chocolate goodies! :-)

Today, I wanted to briefly introduce an idea that is starting to really take off at my company, at least at the location that I work in. Even though my company is international in scope and has a quite large and mature Notes infrastructure, many of our locations only provide a minimum of training around Notes. In fact, I think training only really happens when we do a major upgrade and we're probably lucky if we get that. Miss a session? Well then...you'll probably have to read the little pamphlet that someone puts together. New employees who have never used Notes are probably the most unfortunate. They're just thrown into the pool and left to sink or swim.

You've probably figured by now that I'm really big on helping users. Now, don't get me wrong...as a developer, users drive me crazy too. :-) BUT...I try to remember that what seems so obvious to us can be really challenging for the lay person. I mentioned in a previous post that I found almost all of our users were unaware of how to create a basic table. We routinely see people composing an e-mail in Word and then attaching it to a new memo since they are so unfamiliar with the Notes UI that they cannot do simple rich text editing. After seeing this time and again, I decided to do something about it. I talked to our director of IT and the manager of our training department and in a short time announced the commencement of the "Lotus Notes Power Hour".

The Lotus Notes Power Hour is our now monthly 'lunch and learn' session that focuses on one particular aspect of the Notes client. It's completely voluntary and takes place at lunchtime to make it convenient for most people. Users can attend either physically in our training room or remotely using (I'm sorry to say) LiveMeeting.

So here's the thing...instead of being run by the training department, I do all of the Power Hour sessions. This is, I think, a big bonus. Since I am a passionate user of Notes, I can convey my passion and excitement to the users. I try to not make it like a normal training session. Instead, I have fun with it. I come up with funny scenarios, but situations that are real world. If I use any slides or supplemental material, I use images and text from pop culture (like Jack Bauer turning off mail notification...cause no one tells Jack Bauer when to do mail!). Think training along the lines of the 'Head First' series of books. Playing and having fun with it makes the material go down so much easier. Our first session focused on tables and was a great hit. Recently we did advanced mail functionality and I received many good comments from that session too.

I've been very pleasantly surprised with the turnout of the Lotus Notes Power Hour. People really do want to learn how to effectively use the software they spend so much of their day in and attendance has been growing for each session. I'm trying to convince some of my colleagues overseas to consider doing something similar. Since we are all Lotus Evangelists, we're in a unique position to spread the word. Maybe you can consider starting a Lotus Notes Power Hour at your company. Besides the excellent exposure for your career, you'll get great practice at being in front of an audience. Best of all, you'll be helping your users be more productive and maybe they'll start to enjoy using Lotus products as much as we do. It may be a small step, but it's certainly a step in the right direction. Give it a try...your users will thank you for it!

Wednesday, April 12, 2006

Rethink Your Interface

Like most of you, I've seen hundreds (maybe thousands) of Notes applications over the years. Probably 90% of them were constructed in the same way...some kind of navigation, either a page with an embedded outline or a navigator (how old school :-), on the left side of the screen, with a default view in the main part of the screen. This is just the way it is supposed to be, right? It's a simple paradigm which we've come to expect when working in Notes client applications. Domino is exciting for many of us, since we essentially can control all aspects of the interface (my company's website is entirely based on Domino...doesn't really look like it does it?). But what if you are using the Notes client? Does this mean that all your apps have to have that same old layout? What if you are using an application in which you only have access to a handful of documents? Does this setup make sense? Sure it works, but from a usability perspective it may not be the most efficient way for your user to interact with his or her documents. Usability folks often talk about "getting the interface out of the way". I've found this is sometimes a great approach in Notes.

When you start to practice an interface-first design approach, you'll start to discover all kinds of interesting things. Especially if you are working with clients that have not been big users of Notes before, you will find that your interface on paper may not look like a "typical" Notes application. This is a good thing because you want to design your interface to be useable, not necessarily to conform to standards.

Aside: If you have design standards at your work that specify that all databases must look the same, challenge the status quo. Standards for design are great if they are used as a guideline, but if they prevent you from creating the best interface for your users then you need to rethink your policies.


While I am working through the design process, I spend a lot of time thinking about the user's flow. What will they see when they enter the database? Will they have to search around through views to find the information they need or can I present it to them right up front? Heck...do they even need views? Depending on your scenario, you might be able to eliminate some of the interface stuff that's become a legacy in most Notes databases.

Here's an example that I think illustrates this point well. I was involved in the re-design of an existing Notes application that was used for tracking employes goals and competencies for HR. Its interface was a typical Notes database like I described above. The first thing I did during the design phase was to play with the existing application to see how everything was laid out. The next step was to perform some user interviews in order to get an idea of the different scenarios in which the database is used. Basically, I found that this application had three different user types: The end user, a team manager and an HR representative. Security was obviously an important aspect of this application, so all documents were secured with reader and author fields. As it turned out, the end user will only ever see three documents while working with this application. They would first create their "Person Profile" to capture metadata about them (location, education, training and certification, etc.). After this, they would create two other documents, their "Goals" for the year and their "Development Plan". Since these were the only documents they would ever even see in the database, I immediately starting thinking along the lines of a dashboard metaphor...a single screen that would give them an overall view of their documents without having to deal with different views. We worked out some prototypes on paper and ended up with the following UI:

goals1


When the user first enters the database, they see the three documents that they have to work with represented under the 'My Documents' section. The dots are used as an indicator to denote whether or not they have completed that particular document. In this example, the end user has created the "Person Profile" but has yet to add the "Goals" and "Development Plan". This layout worked well for two reasons...the users had a much easier way to get to their documents and they had a visual reminder of what they needed to do at a single glance. Since we were able to dispense with the views, we were also able to make good use of the extra screen real estate to include important news items and links to databases and websites of note.

This interface worked very well for the end users, but what about the their managers? As we learned from user interviews, one of the trouble points in the old application was that a manager did not know where employees stood in terms of completing their information. What they needed was a simple way to get an overall picture of their group and what still needed to be done. Since each manager had a handful of employees, a slight variation of the end user dashboard did the trick.

manager1


Here an embedded view provides an "at-a-glance" look into the state of each employee's documents. The documents in this embedded view just serve as a container to hold the UNIDs of the actual documents. In this way, we were able to provide the nice graphical feature in a very lightweight manner. If the manager wants to go to a certain document for an employee, they just click the employee's link in the embedded view and are prompted for the document to open.

In the end, this dashboard was found to serve its purpose in all scenarios. The HR representatives, having access to all documents, would use the manager dashboard, with the ability to select users by business division, country or manager.

hr


In the event that a manager or HR representative (or even an end user) wanted to use a standard view, those options were presented as well, since this was simple to do. A section at the bottom of the dashboard can be opened and the user can pick from the list of available views. The selected view is then displayed within this area of the dashboard as an embedded view.

goals2


There were a lot of other aspects of this application that we touched while performing this overhaul, but rethinking the whole "navigation and view in a frame" concept was the biggest change. Not surprisingly, this was also the piece that the users found most appealing. The lesson learned from this application redesign was that by removing a lot of the UI stuff that wasn't providing value (such as the views), users were happier and acceptance of the application was much higher than the old database.

So...care to share unique interfaces that you have built?

Friday, April 07, 2006

A Skinnable Lightweight Notes Client? Yes, Please!

John Vaughan recently wrote about how cool it would be if Hannover was skinnable. You never know...since it's based on Eclipse it might just be possible to do. Something I'm sure we'll all have fun looking into.

John's main point was that the Notes client offers so much incredible power and functionality, but that its interface gets in the way. Boy is he right. This reminded me of something I have wished for from Lotus for a long time...a lightweight Notes client. Think something along the lines of the free "reader" programs that many software companies offer for interacting with files created in their "big brother" versions. A sleek and streamlined Notes client, with a lot of the bloat and unnecessary functionality stripped out...this would be ideal.

Before you rush to post a comment along the line of "Hey dummy...it's Domino...just use a web browser", let me say that there are many situations we encounter in our corporate setting in which the web browser is impractical or not possible. When we deploy the Notes client however, I often see the same thing as John, the look of despair on the user's face when they see it...even 6.5 has waaaaay too much stuff that just takes up space but doesn't provide value. I recently started a lunchtime seminar session to introduce users to different functionality in Notes that they might find useful. Over 90% of them didn't know how to create a basic table! With the exception of our power users, most of the client functionality that is exposed via menus and toolbars could be stripped out completely and we would be fine. If we could box up all the good stuff...robust security, replication, rich text, etc., in a clean and SIMPLE interface, I think we'd have a lot more passionate Notes users. Hopefully Hannover and the future incarnations of Notes start to take us down that path. In the meantime, there's a lot you can do as a developer to help your interface "stay out of the way". I'll explore this more in my next post.

Thursday, April 06, 2006

Microsoft Attacked!

So...like my banner? I wasn't going to put it on here, but I thought some of my Notes pals might get a kick out of it. I was on the phone with a friend late one night and doodling on my tablet pc when the image of the 'Mars Attacks' aliens marching on the Microsoft campus popped into my head (I've learned not to ask...my brain seems to have a mind of its own). So, I fired up the trusty 'ol graphics editor and played around a bit. That's the result at the top of the page. I'll only keep it around for a little while. Too bad it's only make believe! ;-)

Tuesday, April 04, 2006

Design For the User...Not Your Inner Geek

What kind of developer are you? I don't mean what language you use or technology you prefer. Rather, I wonder if you are the kind of developer that is sitting in a requirements gathering session thinking of all the cool code you will be able to write to build this new application you are discussing? Are you being technology agnostic, or have you already determined, without really LISTENING to the users, that you are going to use [insert hot technology here] to build this program? In the end, are you more interested in how your program works than how it looks? There's nothing inherently wrong with doing these things...it's the nature of most developers. We tend to focus on the really interesting stuff, which (let's face it), is usually the code we write. But it's possible, and often desirable, to break this mold and look at the design of our applications in a brand new way...in a way that focuses on what our users actually do.

As developers, we sometimes forget that to our users, the interface IS the application. We love to geek out on the latest techno-wizbang technology that we added to our code library but we often neglect to examine how easy it is to actually USE our app. As a usability advocate, I try to encourage developers to employ an interface-first method of design. Of course, the underlying code has to be elegant and do what is expected, but jumping into the deep end technical problems as you start a project tends to place the value of the application on the technology, not the people that should be benefiting from it.

Employing an interface-first approach takes a little getting used to in the beginning, but pays huge dividends in the end. How many times have you gathered specifications from a user, built the functionality and delivered it, only to have the user tell you that it's not really what they wanted? Be honest...it's probably more times than you'd like to admit. Have you ever thought up a cool design feature that you were sure they would LOVE, only to find out that they don't use it, or worse, don't LIKE it? I'm sure this has happened to the best of us. By using an interface-first design method, you can avoid many of these problems. It's not fool-proof, but it gets you a lot closer to the desired end result a lot faster than traditional methods.

So what does using an interface-first approach actually mean? By using this method, you actually build the interface for your application BEFORE you write a lick of code. This can take many different forms, but essentially involves drawing out what all of the screens will look like as a first step. I use low-fidelity prototyping for all of my projects. This is just a fancy name for sketching out the interface on paper...using pencil, pen, crayons...whatever you have handy. Some people prefer to use HTML or a graphics program to design screen layouts. This is fine too, but takes more work (see aside below). After I have gathered enough requirements so that I feel I have a good grasp of what the user is looking for, I grab a stack of fresh blank paper and jump into the design process. I draw out the fields, sections, graphics...everything that I expect will be a part of the application interface. This doesn't have to look good. In fact, I encourage you to not spend a lot of time drawing these screens. They're very likely to change and you might have to do this several times.

Hint: If you are designing an application in which you will have several static elements that will always be visible (such as a page header or footer), draw these elements out first and then make a stack of them with your photocopier. This saves tons of time since you don't have to draw a placeholder for each element on all of your prototype pages.


Here's a couple of examples of the paper prototype I developed for my machine forecasting application. I ended up using an embedded editor for this functionality, but I didn't have this in mind when I drew this...I just mapped out what I thought was the most logical interface based on what the users described to me. The first shot is my initial sketch and the second is after a meeting with users...they wanted to add a new field and also thought of an additional requirement they hadn't relayed to me before.





After your paper prototype is complete, schedule another meeting with your customer. Ask them to look at the screens and give you feedback. This can be formal (conducting a full-fledged usability testing session) or very informal...whatever you are more comfortable with. Take time to explore different scenarios. If your database is for entering customer complaints, ask the user to take the role of a customer service representative and have them walk through what they would do while looking at your paper prototype. Ask them to talk out loud as they do this, explaining each action. You'll be amazed at the insight this gives you into the mind of the user. When you find something that doesn't belong on the form, cross it out with a marker. Need to add some new fields? Just draw them in with a new color. See why it's good not to spend a lot of time tweaking your prototype? You'll end up changing them a lot.

When you come back from your initial paper prototype session you may be surprised at how much has changed. If you nailed it the first time, good for you! More often than not, however, you've got some changes to make. Quite literally, you should go back to the drawing board and build the next iteration. For a typical application, I will build about two or three paper prototypes. This may seem like a lot of work, but in reality doesn't take too long.

Aside: There are a few reasons low-fidelity prototypes are best sketched out fast and work even better than mock-ups built in Photoshop or HTML. First, from your point of view, you don't feel nearly so invested in the design when it's a bunch of scribbles on blank paper. Since you haven't written any code yet, changes are no biggie. The flip side of this is good from the user's point of view. When presented with a polished looking mock-up or prototype, the user may not reveal their true feelings. They may think you've already put a lot of effort in and have decided that this is how the application will work, even if it is less than desirable. They don't have any problems, however, criticizing a paper prototype...trust me! :-) In fact, they often enjoy grabbing the pen and being an active part of designing the application they will use. This is probably a secondary benefit, but many users have mentioned to me how much they enjoyed the interface design phase.


So...you've built your paper prototypes, gone through some iterations with your users and have a pretty good feel for what the interface will look like and how the application will function. Now what? Now, go about your business...doing what you do best. Start slinging your code, basing it not only on the business requirements, but also on the interface requirements that you've collaboratively developed along with the user. By designing the interface first, you are already halfway to user acceptance and in my experience, have also made the users more passionate about the application. They feel invested in it much more than in traditional programming methods, where you may have only met with them once or twice. When you finally deliver that application, I guarantee it will be almost exactly what the customer asked for...and that, my friends, is exactly why we do this!


Saturday, April 01, 2006

Embedded Editors That Work

In talking about certain aspects of Notes development, my friends and I often use a football analogy to describe functionality which is almost great, but not quite. Many times, Lotus drives it to the five yard line, in some cases making spectacular moves along the way, only to fumble the ball and lose the game. One such example is the Embedded Editor. I decided to do a write up on this, as I was surprised how many of my colleagues did not know about this functionality. When tweaked, it can be a powerful UI construct.

The purpose of the Embedded Editor is to allow you to include multiple forms in a single container form or to allow you to edit documents in an embedded view without having to open those documents directly. Sounds pretty cool and usually works well, but there are several places where the implementation is just not quite right. For one thing, creating a new document using a combination of an embedded editor and an embedded view doesn't work (correctly) out of the box. Also, the context in which certain events or properties of the various elements are known or unknown can be limiting. You can find several examples on LDD of people trying to transfer data between the main form and the embedded form, most with limited success. It seems that for vanilla functionality these embedded elements work fine, but try to get that fancy chocolate and you start to make a mess.

The situation I recently found myself in was creating a database to store forecasting information for machines that need to be built. Each machine is defined in a Project document and one aspect of the Project document is the Bill of Materials (BOM). The BOM is made up of Notes documents, each representing a particular part of the machine. There are only a few fields on the Part document and these documents are directly related to the Project. From a usability perspective, allowing the user to add or change the content of the BOM directly from the Project form would be best, so this was an ideal place for the embedded editor. Through trial and error (and multiple crashes of the Notes client), I came up with a method that allows users to do this in a fairly elegant way. Let's explore it...

I created a sample database that you can download if you want to play along with the home game. (Disclaimer: No...my interfaces don't normally look like this. I just wanted to have a little fun with it). [Link has been moved from box.net due to problems...new link should work fine]

Talking about manufacturing stuff is pretty boring, so for purposes of this example, let pretend we have a database that allows users to order Squishees from Apu's Kwik-E-Mart. The main Order document includes the "metadata" we need for purposes of views and such, like the customer's name, address, etc. Related to this will be the 'OrderList' document (our embedded editor form), containing the detail of the Squishees the user wants to order (think shopping cart). Here's what something like that looks like when implemented:

kwik-e-main


Here we see that there is an embedded editor along with an embedded view. The embedded view is showing the 'OrderList' documents. When one of these documents is selected in the embedded view, the document is available for editing via the embedded editor. This is actually a pretty slick UI technique, since the user is not interrupted by another document opening up just to edit a few fields. Notice on the right that there are links where a user can update the information on the document or delete an item from the order entirely.

Creating a new document in an embedded editor

One of the things that I know some people have found tricky is creating new documents in the embedded editor and having them appear right away in the embedded view. This should be easy, right? Well...5 yard line again. It's a bit tricky, so let's examine that part first. For purposes of this demo, I've included the code to create a new 'OrderList' doc in two places, one in a link on the main form and one in an action button in the embedded view. Choose whichever will work best for your situation and UI. The code is similar for both, and you can take a look at this in the sample database. I'll just walk you through the logic here.


Aside: I stripped out as much unnecessary code as I could in this sample database. Of course, you'll want to add error checking, logging, etc. as needed for your application. I did try to add comments to help make certain parts more clear, but feel free to e-mail me if you have any questions.

I choose not to have the embedded editor available if there were no 'OrderList' documents created yet. The behavior in this situation is less than desirable. You can see this for yourself by creating 'Generic Embedded Editor Example' document in the sample database. Since I am relating the OrderList documents to the main Order document, I created a key value that links these together. For this reason, I make sure the main Order document is saved before Squishees can be added. Once you fill out the Customer Information tab, you can save the document and then you will see on the Shopping Cart tab that you have the embedded view but no embedded editor available. I implemented this by using a computed subform. There is a field called "txt_OrderAvailable" on the main form which does a lookup to the embedded editor view. If it finds any docs, this flag is set to "1", otherwise it's "0". The computed subform then uses this value to determine which subform to show.

When you click the link to 'Add A Squishee', the code first checks to see if there are any OrderList documents for this Order. If none are found, we know that we are going to have to reopen the main Order document so that we get the correct subform to display. Before doing that, we create the new OrderList document in the back end, set some of the important fields (such as the key value) and then save it. At this point, we determine what to do with the ui document in order to see the newly created Squishee in the list. If this is the first OrderList document, we get the main Order document in the back end and save it so that the "txt_OrderAvailable" flag gets updated. We then close the ui document (which is the front end representation of the Order document) and re-open it, which will force the computed subform formula to be re-evaluated and show the subform that contains the embedded editor, along with our new Squishee item. If we already have items in the list, then we need to just reload the main document to see the update.

If you compare the code for the 'Add A Squishee' action button in the embedded view to that in the action hotspot on the main form, you'll find there are some slight differences but the main ideas are the same.

Deleting documents from an embedded editor

Another area people often have problems with when using an embedded editor is deleting documents. Depending on the way a doc is deleted when you have an embedded view/embedded editor combo, some wierd things (i.e. not good) can happen. To make this work seamlessly for the users, I created an action hotspot on the OrderList (embedded editor) form. The first thing that happens when the user clicks the link is that the embedded form is put into read mode (setting SaveOptions to "0" so the user isn't prompted to save) and then an agent is called which deletes the document. The embedded view is then refreshed and the main Order document is closed. If this was the last OrderList document for this order, we get the Order document in the back end and update the "txt_OrderAvailable" flag (setting this to "0"). Finally, the Order document is re-opened in the UI. This process of opening and closing the main document occurs so quickly that it is imperceptible to the users.

Additional ideas to add

In the production database where I implemented this technique, there are several other bits of functionality that I used that you could consider adding as well. These include:

  • Allowing the main document to be deleted only from an action on that form. This will make sure you are not left with "orphaned" documents when you get rid of a main document.
  • Preventing a user from opening the documents based on the embedded editor form. We show these documents in views throughout the database but we did not want a user to open these directly. Code in the QueryOpenDocument event in each view prevents this from happening. Taking it one step further, the actual "parent" document is opened instead, navigating the user directly to the tab which shows the embedded view/embedded editor. Nice, eh? You can see an example of this if you open the 'Other Stuff" view in the sample database.


Aside: Another trick I found many developers don't know is to navigate to a particular part of your document when you open that document via script. There's a handy trick to be found here. When you call the EditDocument method of NotesUIWorkspace, there is a parameter (documentAnchor$) that allows you to open the document to an anchor link. But wait...how can you use this in a form? Therein lies the trick. Go to any old document and create a new anchor link, giving it whatever name you want to use. Now select and copy this anchor link. You can then paste it wherever you'd like on your form and it will then be available to use programmatically in any document that uses that form. You can see this in the sample database by looking at the Shopping Cart tab on the tabbed table in the main form. Pretty sweet...


While it seems there are a lot of odd ball hacks happening here, the bottom line is that in usability testing, our users found the functionality exhibited here to be very easy and relatively obvious. We actually observed users that were completely new to the process and new to Notes who had no difficulty figuring out how to add, update and delete documents using the embedded editor. While some might frown on this code for not being "pure" or "elegant", the fact remains that it has had a positive impact on this business process, which, in the end, is what really counts.


[Update: People were having problems with getting the sample database from box.net, so I moved it and made it a direct download. You can get it here. Cheers...-cmb