benpoole.com

“It is a very sad thing that nowadays there is so little useless information.”

Coding a ‘What’s new’ agent for Domino

Written by Chris Molloy on 21 Oct 2002
Categories / keywords: Web development, Agents
(click on a term to search for related articles at this site)

Add a comment...


Editor’s note

My first guest column! Chris is a top bloke — you can see his bio by clicking on the link at the end of this article — and you should find this code useful. So many sites have a "What’s new" kind of a link, and I’d say that this is one of the more elegant solutions out there. Sure, you can just show the five most recent documents or whatever, but this example is more intelligent than that, and can be seen on Chris’ very own site at christophermolloy.com. Handy for your regular visitors!

Coding the algorithm

The simple algorithm to do this goes something like this:

Code all of the above into a Notes agent, call it with an http://[host]/[database]/[agent]?OpenAgent -type URL and, “hey presto” you have an auto-generated “What’s New” page.

So far, so good.But there are some bells-and-whistles that can refine the algorithm above. The two I’m going to talk more about are: what if there aren’t any documents that have been modified in the last ‘x days’?; and how do I ensure that browser caching doesn’t disturb this process?

What if there aren’t any documents that have been modified in the last ‘x days’?
For a "What’s New" page to be an effective resource it needs to find a good balance between too much and too little information. In order to ensure you don’t get too many results (which will put off all but the most dedicated user) you can use a small value for ‘x days’ and use the third parameter of the NotesDatabase.Search call to set a hard limit - easy. But what if your small value for ‘x days’ causes nothing to be returned sometimes - this will also put users off as it will look like you don’t have anything that’s "new". Hmmm.

Here’s what I did...

I set up three constants:

The algorithm above is now augmented to initialise your search date to be (today + constAdjust) and to continue to adjust your search date by ‘constAdjust’ until some results are returned (or until we’ve regressed by ‘constAdjustCutOff’ days). If you keep a track of how many days your search has regressed then you can even display this number on your results page e.g.:

<title>What’s new @ mysite.com (in the last x days)</title>").

How do I ensure that browser caching doesn’t disturb this process?

Your "What’s New" page will be next to useless if it is cached by the user’s browser, but how do you control this? The classic answer is to use the <meta http-equiv="Pragma" content="no-cache"> meta-tag in your page. Unfortunately not all browsers behave quite as you’d expect when they encounter this meta-tag.

Internet Explorer treats the meta-tag as an immediate command, i.e. it flushes its cache when it hits the meta-tag and then continues to load the rest of the page into its cache. Thus, if your meta-tag is at the top of your page (as is normal — meta-tags sit in your <head> section, after all), your page still gets cached. Doh! The work around from Uncle Bill says to add a second <head> section to the end of your page (after your </body> tag but before your </html> tag) that holds a second version of your ‘no-cache’ meta-tag. Nice one, Bill. Also IE5.0+ has a further issue that requires you to also use the ‘page expiry’ meta-tag (in addition to the ‘no-cache’ meta-tag) to ensure no caching occurs. To be on the safe side you should probably stick this in both of your <head> sections, too. Thus your agent’s HTML output will look something like this:

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>What's new @ mysite.com</title>
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="-1">
</head>
<body>
...
</body>
<head>
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="-1">
</head>
</html>

Now before you Netscape users begin to sneer too loudly, I’m afraid you guys have an issue also. It only manifests itself when using SSL, so I’m not going to go into it here (see http://home.netscape.com/security/notes/nocache.html, if you’re interested), but it does look like even more of a pain to work around.

And there you have it ...

... a "What’s New" page that strikes just the right balance between too much and too little information and that isn’t cached by an overly helpful browser. Nice.

* - To get an agent to output a web page simply ‘Print’ each line of HTML. Don’t forget to add ‘Content-Type’ flags to the top of your output to ensure Domino doesn’t wrap your output in its own page code, i.e.:

Print {Content-Type:text/plain}
Print {Content-Type:text/html}
Print {<html xmlns="http://www.w3.org/1999/xhtml">}
Print {<head>}
Print {<title>What's new @ mysite.com</title>}

Further reading:


   » Coding a ‘What’s new’ agent for Domino (Chris Molloy 21 Oct 2002)
   ... Re: Coding a 'What's new' agent for Domino (Chris Molloy 16 Nov 2002)
   ... Re: Coding a 'What's new' agent for Domino (nw 4 Dec 2002)

Add a comment...