Problems With RestrictToCategory

Not sure where I should file this one. Maybe in the Simple things I really should know by now section or the Things I should probably investigate thoroughly before blogging about section (alongside crying wolf over LotusScript bugs). Maybe you can help me decide?

It's to do with the way the RestrictToCategory URL command behaves and it's something that caught me off guard just recently.

To demonstrate, take this site and the articles by category view. Categories include Agents, Forms, Java [1], JavaScript [2] etc. Open these last two links and you see what you'd expect - a view of documents in that category. Now open this category: JavaScr [3]. There are no articles in this category. So why do we see any?

Ignore the fact that these links use a Category parameter in the URL. This is just my way of keeping the URL simple. This "bug" is still the case when using a standard RestrictToCategory call.

The documents you see in the third link are the same as the second, which implies that Category=JavaScr shows documents where Category=JavaScript. To me it looks like RestrictToCategory operates in a similar way you'd expect the &StartKey= URL command would. It looks like it's missing the ExactMatch argument.

Is this "as designed"? Is there no equivalent to Exactmatch? There should be! If I say show me this category that's what I want to see. Not just something close to it.

There's a reason I'd not noticed this behaviour before. When using RestrictToCategory it's normally with categories that I know to exist. Take the articles view on this site. Notice the View By Category links on the right? They're built using an @DBColumn to the same view and so the categories have to exist.

There's a reason I noticed this behaviour. For each user of a system I wanted to check if they had any request documents in the database. This was done using Ajax. The requested XML was from a view at requests?ReadViewEntries&RestrictToCategory=jh10. The category is the user's ID. In this case it was user jh10 and I was expecting it to tell me there were no requests in the system. You can imagine my surprise when it told me there were three. Turned out they were for user jh100!

A solution fudge hack workaround to this is to close the category string with some random characters. In the column that is categorised change the formula to FieldName+"$*%" or something. Then the XML requested is requests?ReadViewEntries&RestrictToCategory=jh10$*%. The chance of a partial match should be close enough to zero to live with.

What's probably going to happen (now I've spent 30 minutes writing this out) is that the first person to comment will point out how wrong I am and I'll feel stupid (again!). If not then I am right and this doesn't make sense. Surely it should be an exact match?!


    • avatar
    • Peter
    • Thu 5 May 2005 05:13

    Hi Jake,

    I don't think you're wrong (or stupid for that matter ;-) ) on this one, in fact, I've had to use this workaround a few times already.

    There's even a technote available on this topic:



    Hopefully they'll "enhance" it (they claim it's not a bug), because I do mind cluttering the URL...

    • avatar
    • Jake Howlett
    • Thu 5 May 2005 05:23

    I love it ;o)

    "Domino and Notes are functioning as designed"


    "Request is being submitted to change the functionality to a more expected behavior"

    Come on Lotus!

    I notice Ed Brill was asking what feature we all want in R7. Don't bother with any new ones I say. Just spend more time making sure what you've got works properly!

    • avatar
    • Steve Smillie
    • Thu 5 May 2005 07:55

    I'm glad you pointed this out.

    I have not seen this problem but I should be seeing it. My case is


    and another

    ....?OpenView&RestrictToCategory=Auburn Hills&count=16

    I wonder if the space makes the difference, like it breaks on words or if maybe its the additional parameter after.

    I will look at this further.

  1. I know its the oldest web view trick in the book but, why dont you try in the category view column:

    @ReplaceSubString(@Password(Category); ")" : "("; "")

    Then when calculating the URL append:

    "RestrictToCategory=" + @ReplaceSubString(@Password(Category); ")" : "("; "")

    or LotusScript, Java equivalent.

    The unique key produced by @Password SHOULD be sufficently different prevent additional documents from other categories appearing in the results.

    This trick also helps if you have any characters that are not allowed in URLs e.g. spaces, non ASCII chars etc. Or they are disallowed by authentication mechanisms such as Siteminder.

    I know the URLs is not pretty but the results should be what you need.

    • avatar
    • Jake Howlett
    • Thu 5 May 2005 08:24

    Good tip John. Not sure it would work in my case though as I'm building URLs in JavaScript, based on field values. @Password isn't available to me. Unless the @Password algorithm is the same as one available in JS?

  2. No its not the same unfortunately. I spotted a Lotusscript routine that I THINK claimed to simulate @Password without calling @Password. I never tested it though, but if it did work, you could have re-written easily for javascript.

    You could just compute a global Javascript 2d array in the $$HTMLhead field using a @DbColumn etc.

    myKeys = (keyName, keyValue etc..)

    But then you new that.

  3. Great timing on this article! I've spent the last couple of days working on some web views using 'RestrictToCategory'!

    BTW - How did you use 'Category=xxx' instead of 'RestrictToCategory=xxx'? I'd like to do that in my project!

    • avatar
    • Jake Howlett
    • Thu 5 May 2005 09:40

    Easy Tony. In the "Show Single Category" property for the embedded view use the formula:


  4. Jake, I've been facing a similar problem when reading the "startkey", if the key doesn't exist, it returns the next set of documents, which is wrong. Now, if you add the "untilkey" to the url you can grab only the documents you need. This is true everytime you know how to compose the untilkey key, What I did was just adding a "_" to the end of my know startkey.

    for example:


    originally If I searched for "alexh" and the key doesn't exist, it returned the rest of the docs. now with the until key, it search for docs with ket between "alexh" and "alexh_" wich returns no documents, and that's what I expected.


    • avatar
    • Jake Howlett
    • Thu 5 May 2005 10:09

    Nice one Alex. Hadn't thought of that!

  5. What's screwing is that the category key gets treated as a partial match as long as there is no exact match. 'Java' is a substring of 'JavaScript', just as 'Java' is. If you had no 'java' documents, you'd end up with all the 'javascript' ones instead!

    Not only non-intuitive, I'm not sure what daft git decided that was somehow useful functionality in the first place.

    • avatar
    • Chad
    • Tue 10 May 2005 08:20

    I agree that Lotus should fix this issue.

    I got around this issue with calling an agent first to validate that an exact match was present. A simple view.getDocumentByKey( "Category" , true ). The trick is the true paramater for the exact match. If the match was not found then I had more control as to what to send back.

  6. seems to work now, must be 7.02 !

  7. Alex,

    The 'untilkey' parameter is exactly what I was looking for today! Excellent!

    • avatar
    • Pranay
    • Fri 6 Jul 2007 12:32 PM

    Hit a problem. Say I have a view, where I need to categorize on two columns. So I send a RestrictToCategory query string, and I've made my veiw such that the column I want to 'restrict' is the first one.

    However, I do not get documents categorized by the second categorized column anymore. Presumably, the RestrictToCategory has put a hold on that one.

    Any ideas on any workaround?

    • avatar
    • Pranay
    • Mon 9 Jul 2007 06:50 AM

    Figured that out.

    If you pass a RestrictToCategory parameter, it automatically hides the first column it sees in the view.

    In my case, since I had categorized on 2 columns and the first of those columns was hidden, passinga RestrictToCategory was automatically hiding the second column (as it was the first one visible I guess).

    Unhid the first column and now everything works fine.


  8. Thanks Dave :-)


Your Comments


About This Page

Written by Jake Howlett on Thu 5 May 2005

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »

More Content