When you have an embedded outline and you click a link on the outline, you can, of course, have Notes highlight your selection.
You: "Yeah, ok, great...tell us something we don't know".
Me: "Wait...don't go away...this will be cool I promise. Did you also know that you can programmatically set the outline selection?"
You: "Duh...no need, it gets highlighted when I click it"
Me: "Ah...that's true. But...what if you go about selecting the element associated with a certain outline element WITHOUT clicking on the outline?"
You:(in a Homer Simpson-esque way)* "Hmmm...go on..."
Here's the deal. I've had several developers ask me through the years why there is a 'Name' property for an embedded outline. This is the one I'm referring to:
The name in this case can be used programmatically, just like in a tabbed table. When you place the outline on the form and create a document based on that form, a new field called "$OUTLINE_NAME" (where OUTLINE_NAME is the name you provide in the embedded outline properties) is added to the document. This field holds a number that corresponds to the outline entry currently selected. The outline entries are labeled 1 through (max number of entries) in the order that they appear in the design (see below).
Thus, if you wanted to highlight the fourth entry in the embedded outline, your code would be a simple:
At this point, you might still be wondering why you would actually use this. Let me show you a scenario from one of my production applications that should help illustrate the idea. In the last post, I told you about an application in which I use a programmable tabbed table and embedded outline to display various sections to a user. The sections on this form can vary based on document status, user input, etc. The embedded outline is used to make navigating through the sections easy. That is, if the user wants to jump from the first section to the last, they can just click the appropriate link in the outline. But many times the user wants to progress through the form in the logical way that was designed based on business process rules. In this case, the user is certainly free to use the outline, but we have also provided them with simple 'Next and 'Previous' links that allow them to navigate one section at a time (see the screenshot below).
In order to make sure that the appropriate link is highlighted in the embedded outline (which is another visual reminder to the user of where they are) when these links are triggered, we make use of the programmable nature of the outline using the simple formula language snippet detailed earlier.
I think this is pretty slick on Lotus' part. What about you?
Don't forget about the fact that it might be desirable to reset the outline highlight to the first entry the next time the user opens the document (as I discussed for programmable tables in my last post). You can handle this scenario in the same way. Either set the $OUTLINE_NAME field back to 1 when the user saves the document or do so when the document is being loaded in the UI.
Finally, there's one little 'GOTCHA' to be aware of when using this technique. The number you use to highlight a particular outline entry can actually change based on the entries that are displayed in the UI, so you have to account for this in your code. For example, assume that you have an outline with six entries. In a particular scenario, the first two entries on the outline are hidden. In this situation, the third entry is considered entry number 1 as far as programmatic access is concerned. This can be a bit tricky if you are showing and hiding things a lot. If you are careful and put some thought into the way the entries are arranged on your outline, this usually isn't too bad...nothing a simple @If can't handle, but it's important you know about it so you don't end up pulling out your hair!
OK...that's it...another short and sweet post. If you weren't already aware of this technique, I hope it comes in handy for you some time in the future. As always, feel free to leave your comments or drop me a line if you have any questions. Cheers!
*Disclaimer: I am not implying that my readers are like Homer Simpson...I just like when he says that! :-D