How many times have you created an email with a Button, which you've coded with Formula or - hopefully - LotusScript that's been designed to perform some function? And how many times do people just ignore those emails? Sure, they open the email once, but they never click on your button for whatever silly reason they have. Ultimately, you're hard work is ignored and didn't get the chance to do whatever you wanted/needed it to do.

Most of the time I'm contacted by a fellow yellowbleeder and presented with a question that has me asking two questions for their every one. I'm fine with this - don't get me wrong - as it's something that I do literally every day.

"Can this be done?" is often met with a "What are you ultimately trying to do?" and "How is this going to be used?" from me, as I find that most of the time a person is set on a way of doing things well before they even ask a question. Which - again, don't get me wrong - is fine, but as we all know there are about 50 different ways to get the same results, and quite frankly setting your mind to only one of those methods when looking to another geek for suggestions can often limit your end product.

As I am ever discussing the need to separate the NotesDocument from Form Design Element binding - in other words, separating UI from the DataStore - I thought that I'd pass you a quick tip.

First, the scenario:

I have a Lotus Notes Client-based application that contains a simple document approval engine. Each approval document is a response NotesDocument to the parent NotesDocument which contains the overall status and miscellaneous document data. There is a business logic to which NotesDocument and Form Design Element is displayed based on who you are in the system or the current state of the NotesDocument.

For example, while the NotesView shows me the given document, I might be launching my individual review response NotesDocument, or a reader response NotesDocument, or the actual document.

Use Form Formula? Well, I do... but not how you might suspect. See, remember that I might need to launch the document or one of it's specific responses (my review NotesDocument).

Simply put, I need to be able to control what's opened regardless of how it's opened.

The tip:

document is not a UI component per se, but rather a "stub" Design Element that relies on the application logic to render a given NotesDocument via it's PostOpen event.

Example A Sub Postopen(Source As Notesuidocument)

  Dim s As New NotesSession
  Dim w As New NotesUIWorkspace
  Dim rcol As NotesDocumentCollection
  Dim rdoc As NotesDocument

  Set db = s.CurrentDatabase

  Set rdoc = Nothing
  Set rcol = source.Document.Responses
  If (rcol.Count > 0) Then
   Call rcol.FTSearch(|[reviewer] = "| & s.CommonUserName & |"|, 0)
   Set rdoc = rcol.GetFirstDocument
   Call w.EditDocument(True, rdoc)
  End If

 Call source.Close(True)

End Sub

Pretty basic right? Well, here's the trick that will allow you to open that - in the above case - review NotesDocument with any Form you wish.

Example: Sub Postopen(Source As Notesuidocument)

  Dim s As New NotesSession
  Dim w As New NotesUIWorkspace
  Dim rcol As NotesDocumentCollection
  Dim rdoc As NotesDocument

  Set db = s.CurrentDatabase

  Set rdoc = Nothing
  Set rcol = source.Document.Responses
  If (rcol.Count > 0) Then
   Call rcol.FTSearch(|[reviewer] = "| & s.CommonUserName & |"|, 0)
   Set rdoc = rcol.GetFirstDocument
   Call rdoc.replaceItemValue("form", "reader")
   Call w.EditDocument(True, rdoc)
  End If

 Call source.Close(True)

End Sub

Pretty simple right?

This allows me to open rdoc with the reader Form Design Element.

The only caveat to this approach would be if I needed to actually save content back to rdoc but wanted to ensure that the form NotesItem wasn't overwritten with my reader value.

... which is something I'll save for tomorrow's post.

I was contacted by Keith the other day asking me for a downloadable example from my WML-enabling a Personal Address Book - It's in the cards.... article.

Instead of going the multi-Design Element route (as the original article called for a View Design Element and a Form Design Element), I thought that I would take a second to simplify the approach and instead deliver the same functionality with a single Agent Design Element.

The Agent - named mobile - can be added to any Lotus Notes Personal Address Book Template-based NotesDatabase, have that NotesDatabase setup with an appropriately configured Access Control List, put in on a Domino HTTP-enabled Server, and simply point your mobile devices to NotesDatabase/mobile.

The Agent itself is very simple - by design - and can allow for customization via tweaking to meet the needs of the particular customer:

Sub Initialize

 Dim s As New NotesSession
 Dim db As NotesDatabase
 Dim col As NotesDocumentCollection
 Dim doc As NotesDocument
 Dim markup_options As String
 Dim markup_cards As String
 
 Set db = s.CurrentDatabase
 Set col = db.AllDocuments
 Call col.FTSearch(|[form] = "Person"|, 0)
 
 Print |Content-type: text/vnd.wap.wml|
 
 If (col.Count > 0) Then
  
  Set doc = col.GetFirstDocument
  
  Do Until (doc Is Nothing)
   markup_options = markup_options + |<option value="| + Join(doc.GetItemValue("fullname"), "") + |"><onevent type="onpick"><go href="#card_| + Cstr(doc.UniversalID) + |" /></onevent>| + Join(doc.GetItemValue("fullname"), "") + |</option>|
   markup_cards = markup_cards + |<card id="card_| + Cstr(doc.UniversalID) + |" title="Contact Info"><p><b>| + Join(doc.GetItemValue("fullname"), "") + |</b><br />| + Join(doc.GetItemValue("mailaddress"), "") + |<br />| + Join(doc.GetItemValue("officephonenumber"), "") + |</p></card>|
     Set doc = col.GetNextDocument(doc)
  Loop
  
  Print |<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml">|
  Print |<wml><card id="card1" title="| + Cstr(db.Title) + |"><p><select name="name">| + markup_options + |</select></p></card>| + markup_cards + |</wml>|
  
 Else
  
  Print |<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml">|
  Print |<wml><card id="card1" title="| + Cstr(db.Title) + |"><p><b>Unable to load Contacts</b></p><p>There appears to be an issue with this address book. Please contact support.</p></card></wml>|
  
 End If
 
End Sub

Pretty simple stuff here, which renders the following WML markup:

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>

<card id="card1" title="Example WAP NAB">
<p>
<option value="Chris Toohey">
<onevent type="onpick">
<go href="#card_3CEDB7D07E5327D98525760200117ECA" />
</onevent>Chris Toohey</option>
</select>
</p>
</card>

<card id="card_3CEDB7D07E5327D98525760200117ECA" title="Contact Info">
<p>
<b>Chris Toohey</b><br />
ctoohey@dominoguru.com<br />
610.417.1700</p>
</card>

</wml>

So feel free to take the above LotusScript-based Agent Design Element code and use it to add a mobile device WAP UI to any Group Address Books and such that you might have lying around. Also, feel free to point your mobile device WAP-friendly browser to check-out the online demo that I've setup.

(Note: I wrote this in an Agent and leveraged things like FTSearch from within the mobile Agent. I do this so you can easily pinpoint what's going on and apply any required modifications.)

Now, for a killer solution: combine this with Showtime and deliver via Channel Push - for example - as many icon-laden WAP-enabled Personal Address Books that your customer teams require.

So, to review:

To implement this solution, you can simply create a new Agent Design Element named mobile, past in my code, and point any WAP-friendly mobile device to /mobile.

I posted a question yesterday across the various social networks (Facebook, MySpace, Twitter, LinkedIn, BrightKite, etc.) asking the following:

Do you prefer db/view/doc or db/doc?open&UNID=X architecture for the front-end of the Domino CRUD API & web development?

Every Domino Web Application Developer has used the db/view/notesdocument URL Schema for accessing a NotesDocument in a Domino-based NotesDatabase. That's the standard usage scenario. It's what we have all been taught. It's how Domino RAD drives us to develop.

But I'm curious... is there a better way? Specifically, does the db/Page_or_Form?open&UNID=X URL Schema, when combined with @URLQueryString and @GetDocField, lend to a better NotesDocument and NotesData access scenario?

No, I haven't done benchmark testing yet on this, but avoiding a View Design Element that does nothing at times but add bloat to a NotesDatabase - to me - is just one of the many potential benefits to this approach.

Now, a few things that people brought up and that I think definitely should be mentioned:

1. This can impact/break URL Walking
   Simply put, you can't delete the NotesDocument and expect to see the View.

2. Most Domino Web Application Usage Experiences warrant Views
   ... so why not just use the View.

3. This can impact URL Permalinking
   Basing the URL up a NotesDocument UNID is easy, but it breaks any permalinking functionality, which can cause problems for bookmarking content or Search Engine Optimization.

Now, I have an address for each of these items:

1. This really depends on the expected usage experience. Do I want to return - potentially - a listing of all content if I navigate away from a specific content entry (NotesDocument)? Depending on the application, I might not want to. As for this "breaking", you can handle a missing UNID and where to redirect in that event in the design architecture.

2. Again, depends on what you need the application to do. For an application like Email, this meta-viewing of entries makes sense. For an application like a requisition, helpdesk, or jobs database, I don't think you'd want to return the customer back to a listing of all entries.

   As far as rendering a NotesDocumentCollection in the UI, some could argue that unless there is a continuous update on View Entry contents, using a View can be unnecessary overhead. For example, if I were to render an entire "View Index" into a single NotesDocument as JSON and return those contents, I'm getting the exact functionality I would require without that overhead... but I'm getting ahead of myself here.

3. This... this I'm working on.

For that last one, consider a technique that I've mentioned in the past (Nathan T. Freeman's Andrew's Allusion (or Creating Primary Keys in NSFs)), where with db/Page_or_Form?open&UNID=X, X is something like index.html. The content - when created - is assigned a plain-text UNID by the customer (ie., index.html). Post submission, the NotesDocument UNID is set to @ReplaceSubString(@Password(UNID); "(":")":":";""). This hash - for those curious - would result in a completely valid UNID (3A8A735F029991B9844D181AE297DDDE).

But I'm again getting ahead of myself.

Back to the original question: which method works best? I personally think that - once you have a handle on the UNID, @GetDocUNID would return a NotesDocument much faster than lookup via NotesView. Why? Well, consider this:

When you access a NotesDocument by it's UNID from the Web Browser Client via the db/view/UNID URL schema, the view simply becomes a placeholder, and is quite frankly ignored. Next time you see a Domino Web Application that uses this UNID URL schema, replace the view with either a 0 (zero) or thisviewdoesnotexist. Both will result in the NotesDocument being rendered. The View however is considered for things like Form Formula etc., as long as you don't use a zero or a non-existing element name.

I dunno, that sounds more dangerous to me than breaking the URL Walking and could potentially be another feather in the cap for the db/Page_or_Form?open&UNID=X URL Schema.

But like I said, I've yet to do any real benchmarking on this to see which is indeed faster or weigh the true benefits of one approach over another. For that, I'll open up the comments. Weigh in and let us know what you're thinking. If we get enough interest, I'll update the Understanding the Domino CRUD API Example Database to use both techniques.