Today I want to share a few more extensions I've made to them, which help massively when it comes to getting documents from views.

Imagine the following use scenario:

Dim factory As New CustomerFactory()
Dim coll As CustomerCollection

'Let's get a collection from a view
Set coll = factory.GetAll()

'Or you could to this
Set coll = factory.GetAllByID()

'Or you could to this

Set coll = factory.GetAllByCountry()

'Or you could to this
Set coll = factory.GetCustomersMatching("foo")

This code utilises the following functions in the CustomerFactory class:

Class CustomerFactory As DocumentFactory

  Private Function FromView(ViewName As String) As CustomerCollection
    Set FromView = New CustomerCollection(GetViewNavigator(ViewName))
  End Function

  Function GetAll() As CustomerCollection
    Set GetAll = FromView("AllCustomers")
  End Function
  
  Function GetAllByCity() As CustomerCollection
    Set GetAllBySite = FromView("CustomersByCity")
  End Function

  Function GetAllByCountry() As CustomerCollection
    Set GetAllBySite = FromView("CustomersByCountry")
  End Function
  
  Function GetAllByStatus() As CustomerCollection
    Set GetAllByStatus = FromView("CustomersByStatus")
  End Function

  Function GetCustomerByID( id As String ) As Customer
    Set GetCustomerByID = New Customer( GetDocumentByKey( "CustomersByID", id ) )
  End Function
  
  Function GetCustomersMatching(query As String) As CustomerCollection
    Set GetCustomersMatching= New CustomerCollection(GetViewEntriesByKey("(LU-CustomersByAllKeys)", query, False))
  End Function
End Class

In turn the above code relies on a few additions to the base DocumentFactory class:

Class DocumentFactory
  Function GetViewEntriesByKey(ViewName As String, SearchTerm As Variant, ExactMatch As Boolean) As NotesViewEntryCollection
    Set GetViewEntriesByKey = GetView(ViewName).Getallentriesbykey(SearchTerm, Exactmatch)
  End Function

  Function GetViewNavigator(ViewName As String) As NotesViewNavigator
    Set GetViewNavigator = GetView(ViewName).Createviewnav()
  End Function

  Function GetAllViewEntries(ViewName As String) As NotesViewEntryCollection
    Set GetViewNavigator = GetView(ViewName).AllEntries
  End Function
  
  Function GetDocumentByKey(ViewName As String, Lookup As Variant) As NotesDocument
    Set GetDocumentByKey = GetView(ViewName).Getdocumentbykey( Lookup, True )
  End Function
End Class

What all this does is make it a lot less tiresome to get a handle on document(s) relating to a particular business object (in this case documents based on the "Customer" form). The base DocumentCollection class now has helper functions to get all view entries or simply a view navigator object. It also has a GetDocumentByKey method which defaults the ExactMatch option to True, because it always is, thus saving us passing it in to the call.

Going Forward

I've also been using these classes extensively in a new Domino database I've been lucky enough to create from scratch and have been working on lately. As I've gone along I've been tweaking and extending the classes and now feel they're at a solid point ready for wider use.

I don't want to bang my own drum too much, but they're amazing. You maybe have to use them to see why, but, once you do, there's no going back. If this were ten years ago they'd be almost revolutionary.

Talking of going back; will I ever!? Will I ever be asked to create a new Domino-based web app from scratch? Never say never and all that, but I have a feeling I won't. Which makes it a shame that I developed such a rich and powerful way of working with Notes objects via LotusScript so late in my days with Notes.

Either way, if you're still working with and creating new Notes apps I implore you to give these classes a go. You'll love them.

My plan is to scrub them all a bit, document them better and then share on Github, along with a demo database. Assuming there's interest?

The one thing I never liked about using Email in a browser is that I constantly close and re-open the browser. Thus, in effect, closing my email client, which I then have to remember to re-open.

Now though I've made it seem like a real app. You can do this using Chrome's "application shortcuts". Here's how.

First I setup a CNAME record in my DNS so that mail.mydomain.com points to Gmail. Then I visited the new URL in Chrome and, from the Options menu I chose Tools -> "Create application shortcuts...." which brings up this option dialog:

When I clicked Create it added a shortcut to my Taskbar, as below.

As you can see it looks just like a real application. It even tells me how many unreads there are.

The app runs in a chrome-less version of Chrome, as below:

I can now open and close my actual Chrome browser as many times as I like and my "mail client" stays open.

Did you notice the custom logo being used? Here's how.

You can also configure notifications to make it even more like a true mail client experience, where new email alerts appear on the bottom right of your screen.

All in all it makes for a nice experience. Now if only I could shake the un-nerving sense that I could lose all my mail at any point...

Hopefully you've been inspired by my recent adventures in creating custom LotusScript classes. If so, you'll have noticed that, when creating your own properties and methods in these classes that they get their own comments added in.

For example, if you type "property get foo as string" and then press return, you'll see something like this:

%REM
        Property Get Foo
        Description: Comments for Property Get
%END REM
Property Get Foo As String

End Property

Domino Design auto-adds the comments above the property for you.

It's easy to see this as an annoyance and find yourself taking the comments out to keep your code tidy. However, I've forced myself to stop doing that and now make a point of adding in a meaningful comment. Like so:

%REM
        Property Get Action
        Description: Value of the "Action" field, which is used by the
        workflow associated with most documents
        
        Value is only available when editing/saving
        (not stored on document)!
%END REM
Property Get Action As String
        Action = GetFieldValue("Action")
End Property

The benefit of doing so is manifold. Not only does it remind yourself what your intentions were but also, more importantly, future maintainers of the code.

But the real tip here is that, if you comment code using the standard way then, when you hover the mouse over a call to that property in use in your code you get to see the "documentation" inline. As below:

That alone makes it worth the time to document properly. Even if just for your own benefit as a quick reminder of what everything is.

Here's my desk now, following a recent overhaul:

The two main differences from before: The Lenovo T400 laptop and its docking station have gone and the left-most monitor has moved positions to be on the right.

My desk needs to not only keep up with the way I work, but also the changes of the times. I decided it was time I got "with the times" and "embrace the cloud" and all that stuff.

For years my main work PC has been a laptop. For the obvious reasons, such as being able to work anywhere, being able to hide it when I go on holiday etc. It used to be that I'd undock the T400 each night and take it indoors of a night time. Then I bought the Yoga 13, which fast became my "house laptop" and the T400 was confined to the office.  The T400 was getting on for being 3 years old and had the noisiest damned fan in its docking station! It's days were numbered!!

While using a laptop as my main PC I have always missed having a dual monitor setup, which laptops can't deal with. Not easily anyway.

So, I've bought a Lenovo E31 SFF and stuck 32GB of RAM in it. This is now my main work PC and drives the two monitors to the right. I've missed having dual monitors!

Using the recently-discovered Hyper-V Manager tool for Windows 7 means I don't need the monitor attached directly to server. As you can see above the second monitor is showing a Domino server running in a VM on the server. It makes day-to-day Domino development so much easier having ready access to the server console.

No Email Client

The cloud now means I'm not tied to a single machine. When I do go "on the road" I can easily take everything with me.

For the first time in as long as I can remember using a PC with email I'm not going to install a Mail app. I've used various email clients over the years: Opera, Outlook Express, Lotus Notes, Thunderbird, Postbox, Mail.app. Now I'm just going to use Gmail.com online. Got to admit I don't like the idea that all messages aren't backed up on my own PCs. But hey. Brave new world and all that.

The only non-cloud-stored data I work with are Notes database. I tried using Dropbox to store my Notes Data folder, but, unsurprisingly, it didn't work. It probably could work if you made sure to only have Notes running on one PC at a time.

Moving from one PC to another this time was a lot less painful than it has been in the past. Still took a couple of hours. Not the full day of time it used to though.

Who knows what the 2014 update will bring. I just hope I'm still lucky enough to be working from my own little home-office, so that it matters either way.

<a class="btn" href="foo"><i class="icon icon-plus"></i> Add New</a>

And I get something like this:

The choice of icons is documented here and the icons themselves are based on Glyphicons "halflings".

All is good.

However, recently I found myself wanting to use an icon to show that a document had some attachments. Naturally, I wanted a paperclip. Just like a magnifying glass denotes searching, a paperclip denotes a file attachment. Who knows why!

To my surprise the available set of icons listed on the Bootstrap site didn't include a paperclip. Really? But on further investigation it became apparent that the current version of Glyphicons did include a paperclip!

Here are the icons currently supplied with Bootstrap. It's a single flat image, which is used as a CSS Sprite:

And here's the image which represents the current release of Glypicons:

Notice the difference?

There are a few very slight differences. But the main difference is that the latter image has an extra row of icons. Not only that but one of them is a paperclip! Get in!!

Luckily (for me) the makers of Glypicons add new icons to the end of the grid, without changing the positions of the existing icons. This meant I could simply replace the image currently used by my copy of Bootstrap with the latest Glyphicons release. Without breaking the existing CSS/icons!

Once the new image was in place all I had to do was work out the grid size used, which, it turns out is 24 by 24 pixels. Before long I'd extended the available Bootstraps icons by adding the following CSS:

.icon-attachment {
  background-position: -24px -168px;
}

Job done. I love Bootstrap!

For example, let's say you have an object based on the Customer class and you want to find all their Invoices. Wouldn't it be nice to write code like this in a WQO agent:

Dim customer As Customer, invoice As Invoice
Set customer = New Customer(web.document)

If customer.Invoices.Count > 0 Then
  Set invoice = customer.Invoices.getFirst()
  
  While Not invoice Is Nothing 
    'Do what you like here
    
    Set invoice = customer.Invoices.getNext()
  Wend
End If

When you start using code like this in your day-to-day LotusScripting that's when it all starts to gel and there's no going back.

Imagine also that you wanted to know how many other invoices the customer for any given invoice has. You can do it like this:

Print "This invoice's customer has " + Cstr(invoice.Customer.Invoices.Count - 1) + " other invoices"

Cool, no?

Adding Collection Properties

But how do we add this "Invoices" property? Easy. Just do something like this in the Invoice class:

Class Customer as DocumentWrapper
 Private Invoices_ As InvoiceCollection
 Private Factory_ As InvoiceFactory

 Property Get Invoices As InvoiceCollection
  'lazy load the invoices!
  If Invoices_ Is Nothing Then
   Set Factory_ = new InvoiceFactory()
   Set Invoices_ = Factory_.GetInvoicesForCustomer(Me)
  End If

  Invoices = Invoices_
 End Property
End Class

Noticed we've defined a class-level InvoiceCollection and InvoiceFactory (we need to do this so they stay in scope). We then "lazy load" them the InvoiceCollection when it's first requested.

Here we're only going one level of sub-class deep. But you could go as many levels deep as you needed.

In the example above I've called a method called GetInvoicesForCustomer(). How this works depends on how your data is structured. Maybe the invoices are child documents of the Customer. Maybe they're just tied together by an "id" field. Either way, it doesn't really matter.

Imagine that, anywhere in your LotusScript, you could write this:

Set invoice = New Invoice(web.database.CreateDocument)
invoice.Number = factory.GetNextInvoiceNumber()
invoice.Value = 12345.98
invoice.Save()

Wouldn't that be cool!?

It's quite simple to do. To help take some of the pain out creating new documents of a certain type you can use the "New()" method of the derived class to check if it's a new document being created. If it is new then we can "initialise" it by adding some of the key fields and values. Such as the "Form" field.

So, for the Invoice class the New() method would look like this:

Class Invoice As DocumentWrapper
 Sub New(doc As NotesDocument), DocumentWrapper(doc) 
    If doc.IsNewNote Then 
         SetFieldValue "Form", "Invoice" 
         AllowedEditors = web.user.Canonical
         AllowedReaders = Split("*/ACME;[Administrators]", ";")
        'Any other fields this form *needs* to have!?
    End If 
 End Sub

 Property Set Value As Variant
  SetFieldValue "Value", CCur(Value)
 End Property

 Property Set Number As String
  SetFieldValue "Number", Number
 End Property

End Class

So far the derived classes I've shown only had "getter" properties, which returned field values. But the above two snippets of code demonstrate the user of "setter" properties also.

Notice the AllowedEditors and AllowedReaders properties. These are a new addition to the base DocumentWrapper class, which we can use to add Names-type fields. In turn they rely on a new AddNamesField method, like so:

Property Set AllowedEditors As Variant
 AddNamesField "DocAuthors", AllowedEditors, AUTHORS 
End Property
        
Property Set AllowedReaders As Variant
 AddNamesField "DocReaders", AllowedReaders, READERS
End Property


Sub AddNamesField(FieldName As String, UserNames As Variant, FieldType As Integer)
  Dim item As New NotesItem(document_, FieldName, UserNames, FieldType)
End Sub

All document creation logic for each business class/model can now be encapsulated in one place. Then, no matter where in your code you find yourself creating new instances from, you don't need to worry about what the form name is or what fields are needed.

As I keep saying: the more I use and extend these three classes the more I wonder how I got by without them...

So, taking it further. Let's extend the DocumentWrapper class some more. Since first writing about them  on here I've been busy using and extending them as I go. Here are a few examples of some of the properties I've added

Simple Helper Properties

Some very simple properties: WebLink, UNID and IsNew.

Property Get WebLink As String
  WebLink = "/" + Replace(web.database.Filepath, "\", "/") + "/0/" + UNID + "?OpenDocument"
End Property
        
Property Get UNID As String
  UNID = Document.Universalid
End Property
        
Property Get IsNew As Boolean
  IsNew = document.Isnewnote
End Property

These don't do anything that can't already be done. They just make it simpler and quicker to code.

Logging Document Actions

Properties are all well and good. But they're just borne of laziness really. Let's add a method or two, to make it really useful. How about adding a new method to the base class called LogAction() which you might use like this:

invoice.LogAction("Invoice Approved")

And the method might look like this (it assumes all your Forms have a standard field called "ActionLog"):

Sub LogAction( Action As String )
  Dim item as NotesItem
  Set item = document.GetFirstItem( "ActionLog" )
  Call item.AppendToTextList( Action + " on " + Format(Now, "dd mmm yy") +_
   " at " + Format(Now, "hh:nn:ss") + " by " + web.User.Abbreviated )
End Sub

The web.user part assumes you're already using my WebSession Class.

Deleting Documents

If you never actually delete documents, but merely flag them as deleted then you can give all objects based on the DocumentWrapper class a Delete() method, like so:

Sub MarkDeleted()
 Call SetFieldValue("Delete", "1")
 Call LogAction("Document Deleted")
End Sub

You can then add an IsDeleted property to the DocumentWrapper class, like so:

Property IsDeleted As Boolean
  IsDeleted = (GetFieldValue("Deleted")="1")
End If

At this point you might consider moving some of the field name and their values to "static strings" at the top of the class, then changes the corresponding methods, like this:

Const DELETED_FIELD_NAME = "Deleted"
Const DELETED_FIELD_VALUE = "1"

Sub MarkDeleted()
  Call SetFieldValue(DELETED_FIELD_NAME, DELETED_FIELD_VALUE)
End Sub

Property IsDeleted As Boolean
  IsDeleted = (GetFieldValue(DELETED_FIELD_NAME) = DELETED_FIELD_VALUE)
End If

Naturally you might want to add an UnDelete() method too...

Extending Derived Classes

So far I've talked about extending the base DocumentWrapper class. Everything we add there is available to all classes derived from it. But, obviously, you can also add properties and methods to the derived classes. For example, the Invoice class might want an Approve() method. This could either simply flag it as approved or perform some more complex workflow logic, passing it between approvers.

Class Invoice As DocumentWrapper
 Sub Approve()
  'Do whatever 
  LogAction("Approved")
 End Sub
 
 Sub AddItem(Description as String, Value as Currency)
  'Add to the relevant fields
 End Sub
End Class

Notice I added a call to LogAction() inside the Approve() method. That way you never forget to log the approval no matter where you call the Approve() method from.

The possibilities are almost endless.

Summary

These wrapper classes have completely changed the way I code my Domino web apps! My dream has always been to be a "proper coder". I'd love to be able to work completely in Visual Studio writing C#. Unless you've done that you won't appreciate what a pleasure it can be. I get a buzz from writing my own classes and then using them. This is a buzz I've never really had while coding for Domino. Until now. These wrapper classes will have to do for the time being.

Next week I'll talk even more about them and show how to handle collections of documents that belong to other documents. While I go, I'm working on a demo app that brings it all together.

It always surprises (worries!) me when I'm asked to either share a downloadable copy of a demo or write a how-to about it. Particularly when it's something that's all but completely web-based. The code is there to see; just a click away.

That said, in this case, unless you're familiar with jQuery and/or jQuery plugins it might not make much sense and warrants some explaining, so here goes.

First bit of code you see is at the very bottom of the scrolling view page and looks like this:

//Setup the "infinite" scrolling view
$(document).ready(function(){
    $('#invoices').infiniteScroller({
        URL: "(getInvoices)?OpenAgent",
        viewName: "InvoicesByDate",
        emptyArraySize:1,
        pageSize: 40,
        itemTemplate: "<tr><td><%=Document.Created.Formatted%><td><%=Title%></td><td><%=Customer.FullNameReversed%></td><td style=\"text-align: right;\"><%=Value.Formatted%></td>"+
        "<td><span class=\"label <%=Status.LabelClass%>\"><%=Status.Description%></span></td>"+
        "<td><a class=\"btn btn-link\" href=\"0/<%=Document.UNID%>?Open\">View &raquo;</a></td></tr>",
        endTemplate: "<tr><td colspan=\"6\" style=\"text-align:center\"><strong>There are no more invoices to load!</strong></td></tr>"
    });
});

You may recognise the .ready() bit as being jQuery's way of having the enclosed code run as soon as the document is done loading/rendered.

But what about that $().infiniteScroller() bit!? Well, that's a call to the jQuery plugin part that I wrote. That might sound difficult, but it's not.

In essence you can define a jQuery plugin, which I've done in the "Application.js" file, like this:

(function ($) {
    var Scroller = function (element, options) {
        this.$element = $(element);
        this.options  = options;

        //Do what you like here.
        //Remember that this.$element always points to
        //the HTML element we "invoked" infiniteScroller on!

    }

    $.fn.infiniteScroller = function (options) {
            return new Scroller(this, options);
    };

})(window.jQuery);

Notice the part in bold! This is where we extend jQuery's $() selector with our own method name. Simple, but so powerful.

Obviously I've missed out most of the actual code above. All that the missing code does is call an Agent via Ajax and append the resulting data as HTML <tr> elements on to this.$element.

The only tricky part is handling the auto-scrolling. To do this we bind an event handler to the windows onScroll event when the page has loaded, like so:

$(window).bind('scroll', {scroller: this}, this.scrollHandler);

This adds the Scroller's scrollHandler method as a listener and passes a reference to the current Scroller in to the event's data. Which we can use in the scrollHandler method, like so:

Scroller.prototype.scrollHandler =  function(event){
    var $this = event.data.scroller; 
        
    //Are we at (or as near) the bottom?
    if( $(window).scrollTop() + $(window).height() > $(document).height() - $this.options.pixelBuffer ) {
        $this.currentPage++;
        $this.loadData();
    }  
};

Fairly simple, no? It just tests to see if you're at the bottom of the page. Using the "pixelBuffer" option you can make it so they don't need to be right at the bottom, if, for reason, scrolling needs to happen before they get to the bottom. You could even pre-empt them getting there by loading when they're getting close to the bottom and they'd never need to wait.

What About the Backend?

Back on the server things are actually quite simple. Perhaps you thought that wasn't the case?

To get it to work the first thing I did was extend the DocumentCollection wrapper class I talked about a few weeks back by adding a getNth() method to it.

Now, all my Agent needs to do is this:

Dim factory As New InvoiceFactory
Dim invoices As InvoiceCollection
Dim invoice As Invoice
        
Dim start As Long, count As Integer, i As Integer
Dim View As String
        
start = CLng(web.query("start", "1"))
count = CInt(web.query("count", "40"))
view = web.query("view", "InvoicesByTitle")
        
Set invoices = factory.GetAllInvoices(view)

'Invoice to start at
Set invoice = invoices.getNth(start)
        
Print "content-type: " + JSON_CONTENT_TYPE
        
Print "["
        
While Not invoice Is Nothing And i<count

        Print invoice.AsJSON + |,|
                
        i = i + 1
        Set invoice = invoices.getNext()
Wend

Print |null]| 'NASTY, NASTY hack to avoid dropping last , from array. Yack!

Note that the "web" object referred to above is based on the WebSession class which has been a mainstay of my Domino development for the past 5 or 6 years.

The more I use these new "wrapper classes" in LotusScript the more I kick myself for not having thought of them earlier on in my career. Although I am now using them on a daily basis and they're saving me time I keep thinking of how much time they could have saved over the years.

Having said that, just last week, for the first time in ages, I pressed Ctrl+N in Domino Designer and started a new Domino project from scratch (who says Notes is dead!?). The wrapper classes are an integral part of this new project.

Talking of the wrapper classes. I'll be updating and talking about them shortly. I've made significant changes to them and I think you'll like.

I then (over-)promised to show some alternatives. Hopefully you're not expecting anything revolutionary, coz that they ain't. Just something different. Extra tools for the toolbox.

Infinite Scrolling

The first alternative is to use "infinite scrolling". This is something you'll be used to if you use Twitter or Pinterest. The pages load the most recent content and, when you scroll to the end of that list, it loads more. And so on, until there's no more to load.

The screenshot below is of this Domino-based "infinite scrolling" view.

Combined with the fact some of the column headers are sortable/clickable it makes the "Invoices by X" links in the nav bar redundant, as it does page navigation.

What surprised me was how "simple" it was to implement. At first I'd gone looking for ready-built jQuery plugins to do it, but they all weighed in at +20kb and were either overkill or not particularly suited to Domino (nothing ever is!).

So I wrote my own jQuery plugin to do the job, using about 20 - 30 lines of code. I'll talk more next post on the code involved. For now I want to discuss the pros and cons of these types of view.

Advantages

Hmm. What are the advantages? I'm not really sure. They're nice, I guess. Saves the user having to press the "Next Page" link each time they get to the bottom. Other than that...

Disadvantages

Oddly, I can think of plenty of these, even though I'm suggesting they're use as an alternative to the normal way of doing things.

• What I find most annoying about these views is that the scrollbar jumps out of each if, like me, you use the mouse to click the scrollbar and pull it down to scroll. Once more content loads the scrollbar puller moves and you have to move your mouse back up to grab hold of it again.
• Once the first page loads you can't use the scrollbar's size as a visual indicator to work out how much content there actually is.
• It breaks the back button (although there are ways round that)
• It blocks access to the page's footer area, as you can never quite get to it until all the content has loaded! In the example above, there isn't anything in the footer, but if you do have something like FAQ or Contact Us links you don't want to prevent people ever being able to scroll down to them!

As with everything and as I always say, it's a case of "horses for courses". Hopefully when I show the code in the next post you'll see these auto-scrolling views aren't as hard to implement as you might have thought.