API
@-Formulas
JavaScript
LotusScript
Reg Exp
Web Design
Notes Client
XPages
 
Showing Single Category - Warning
Sometimes in a web application, you want to make use of the "Show Single Category" feature on an embedded view to limit the documents a user will see. One use of the "Show Single Category" value would be to limit the documents to the ones for the current user. Another use would be to limit the documents to those under a certain date. There are may other uses as well.

However, we have discovered something that you have to be aware of, if you have multiple levels of categorization. The best way to explain would be to go through an example.

Let's say you're keeping track of lottery numbers over different dates in different states, and you've divided the states up into regions. Figure 1 shows how this view looks in the Notes client. There are two levels of categorization - the first is the date (in YYYYMMDD format) and the second is the region.

In the Domino Designer, you can set up this view to show a single category. The category to show will be the date. To make the application more dynamic, the category to show can be computed. In this example, it is computed to the value in the URL in an &Date= parameter. See figure 2 to view what this formula looks like in the designer client.

Notice in figure 2 the formula for computing the single category to show. The formula takes its everything after &Date= in the Query_String, and then pulls out just the date (Domino may add another & character or a # character to the end of the URL).

After building the view template, when you look at the view with a web browser and include a valid YYYYMMDD combination in the &Date= parameter, you can see just that category of documents in your browser, as can be seen in figure 3.

Notice in figure 3 how the top-level category doesn't show, but the second-level category does show. When using "Show Single Category", the Domino server just grabs everything under that category to show and then builds a "partial view" out of that information. The server doesn't care if there's another level of categorization or not. In the example, there are 4 categories being shown under the "single category" computed based on the URL. You can click on the East region to see the documents under that region, as seen in figure 4.

Taking a look at figure 4 again, notice the URL at the top. Domino put the same &Date= parameter that we had before at the end of the URL, followed by #1 to tell the browser to move to the start of that category (which is really a sub-category).

As it turns out, it's pure luck that the second-level categorization even works. It's lucky because the value being used is "&Date=". If something else were used, it wouldn't work. For example, in figure 5 the view template was changed to use "&D=" instead of "&Date=". The view opens up initially just fine, but when you click on the East region, Domino doesn't put the "&D=" parameter into the URL it generates, and you end up with figure 6. So the view template can't figure out the single category to show (it's looking for "&D=" in the Query_String) and therefore the "No documents found" message appears.

So, what's the moral of the story? If you're going to use the "Show Single Category" feature and want the category to be computed at run time, and you have multiple levels of categorization in your view (that's a few "ifs"), you have to use "&Date=" as your parameter. The good news is, it doesn't seem to matter what value is in your "&Date=" (i.e. you could have "&Date=junk" and it would still work). So, I guess it would just be a bit confusing when &Date= is your parameter and you're actually referring to a country or something.