It’s funny how you rarely use some bits of script, and then within a week find you need them more than once. An example of this I’ve just had is the NotesViewNavigator class.
The only previous occasion I used the class was for dashboard reporting some time ago, because I wanted the entries in the same order as the view and wanted to push totals to a function. One of the added benefits of this approach over NotesDocumentCollections was that I could get the full total regardless of the user’s access to the actual documents, so long as they had access to at least one document in the category (see the gotchas at the bottom).
Having forgotten about that use, I used last week for some email reports. I was using an existing view to trigger emails of support calls for my team. This was categorised on status, then developer, then customer. I was already aware of the gotcha that GetAllDocumentsByKey and GetAllEntriesByKey get only the first sub-category in a categorised view. So for the view below, view.GetAllDocumentsByKey(“Outstanding”, True) and view.GetAllEntriesByKey(“Outstanding”, True) will just get the entries/documents in the red box in the screenshot below.
But I wanted to loop through each of the sub-categories, reporting on each. So instead I used view.CreateViewNavFromCategory(“Outstanding”), then the various NotesViewNavigator methods (GetFirst, GetChild, GetNextSibling etc) to loop through them. Incidentally, the email I was generating also became my first experience of using the various NotesRichTextItem properties and methods to create and update a table in a rich text item.
Then today I was looking at dojo charting in XPages, using server-side javascript to get various column values of my view entries. So I started typing var viewEnt:NotesViewEntry = view1.getFirstEntry(). That was when I found there was no such method. The solution was to use view1.createViewNav() and the NotesViewNavigator methods getFirst() and getNext().
A couple of other gotchas to do with view entry handling worth noting, if you haven’t had much experience in this area:
1) NotesViewNavigators use all entries in the view, regardless of any search performed on the view. It’s mentioned in the help, but could be easily overlooked. This may mean you need to add checking into your code or add a new view.
2) GetEntryByKey gets the first entry of type Document. This means if you’re using categories to retrieve a total, you need to use a NotesViewNavigator and get the parent NotesViewEntry, as in the code fragment below. This also means if you don’t have access to at least one document in the category, you can’t get its total!
