RSS is quickly gaining in popularity as a way in which to be notified when new content is added to a Web site or application. By adding a few new design elements and tweaking some existing ones, you can provide RSS feeds for binders in Lotus Domino Document Manager. Your Lotus Domino Document Manager users may find that this is a simple way to keep track of their favorite binders.
This article gives a quick overview of RSS, so you have an idea of what it is created in this article. There are far better RSS resources on the Web that you may want to refer to if you are new to RSS. The rest of the article guides you through the steps needed to set up an RSS feed for Lotus Domino Document Manager. This article assumes that you are an experienced Lotus Notes/Domino application developer and that you are familiar with Lotus Domino Document Manager.
A basic RSS feed consists of formatted XML. The first few lines of a feed describe it. These lines contain the title of the feed, a URL for the source, and a description of the feed.
<rss version="2.0"> <channel> <title>Another binder</title> <link>http://server.hostname.com/database/view/document</link> <description>Another binder</description>
The next set of lines can be thought of as the actual content of the feed. Details about each item in the feed are enclosed in an <item> tag. To keep it simple in this article, you add only necessary information in each <item> tag. Each item contains a title, link, description, published date, and a unique identifier. After all the items are listed, there are just a few more lines that end the XML feed.
<item> <title>Bold red.doc</title> <link>http://server.hostname.com/database/view/document</link> <description> <html><table><tr><td><b>Description:</b></td></tr> <tr><td>imported</td></tr><tr><td> </td></tr> <tr><td><b>Comments:</b></td></tr> <tr><td></td></tr></table></html> </description> <pubDate>02/08/2006 03:10:25 PM</pubDate> <guid>68446C2B10B8DEB58525710F006EBDFC</guid> </item>
Because you want to provide a feed of documents in a binder, the best method is to create the XML using a view. You can have the view create the <item> objects for each document, and then place the rest of the XML in a view template. Because most RSS readers request feed updates every few hours, you want to ensure the method you use to create the XML doesn't hinder server performance. A view has its index already created when a feed update is requested, so there should not be much impact.
A view also provides document-level security, so you can be sure that users see only documents to which they have access. Other methods, such as an agent or Java servlet can be used, but they may not perform as well or may not provide the document-level security that is required. The design elements described in this article are provided in a Domino database for download, so you do not need to recreate them.
Creating the view
First, you start by creating a blank view in your File Cabinet template database (filecab.ntf is the default). Name the view (rssBinderView) and give it an alias of rssBinderView. On the Advanced tab of the View property box, select the option "Treat view contents as HTML," if not already selected (see figure 1). This option prevents Lotus Domino from creating HTML for you, which breaks the XML that you create.
Figure 1. View property box
The view's selection formula is:
SELECT ObjectType = "Document" & IsLatest = "1" & ISWIPVer != "1" & ShouldBeDeleted != "1" & BinderID != ""
This formula selects all current documents in the database.
Hide the first column in the view, sort it ascending, and categorize it. The view should not have a title because titles break the XML. The column's value displays the BinderID field to ensure that the feed displays only the documents of one binder. More will be said about this first column later in the article.
The second column in the view should also be hidden, but sorted descending. Again, the view should not have a title. The column's value should be the Last Modified date. This column ensures the most recently edited document is first in the feed.
The third and final column should be visible and unsorted with no titles. This column creates the RSS XML for an individual document. The following code snippet generates the XML:
On the first line, the basic URL is hard-coded to generate the URL to the document. You hard code the URL because you cannot perform an @DbLookup in a view column. Normally, you can pull this information from the HTTP header, but the HTTP header isn't available because the view is built on the server. If you don't want to hard code this URL, you can create a setting in your server's Notes.ini file to look up that value. Using the Notes.ini method, you can deploy on multiple servers without hard-coding the information.
The next few lines create the item in the feed. Use an @ReplaceSubstring for the Title field because if any documents have an ampersand character in the title, the XML will break. By replacing the ampersand with the entity &, you solve this problem. Also, in the <description> tag, many characters have been escaped (for instance, < is now <). This is also done so you can provide HTML in the description tag and not break the XML. You can modify the <description> tag to contain anything you like. The code above creates a table with the document's description and the comment entered when the document was checked in.
That's it for the view. Save and close it, and let's move on.
Creating a view template
You need to create a view template for the view you just created. This template is used to filter the view to one binder and to provide the XML that wraps around the <item> values the view creates. To create the template, create a new form and name it $$ViewTemplate for rssBinderView. On the Defaults tab of the Form property box, set the Content type to Other and in the field beside the option, type text/xml (see figure 2). This prevents Lotus Domino from adding any of its own HTML to the form when it renders it for HTTP users. It also tells the RSS reader that you are providing XML.
Figure 2. Form property box
Some hidden fields are added at the top of the form. These fields contain the query string and the values of the HTTP headers as well as parse the query string. The BinderID is contained in the query string of the feed's URL to allow you to use one view for all binders. If you have large File Cabinets, you may want to create a view for each binder. Using one view for a large File Cabinet impacts performance negatively because the view takes a long time to build, to update, and to filter.
The next few lines after the hidden fields start the XML for the feed. Notice in this sample, we use the binder's title for the feed's title. You may want to customize this. For example, you can add the library and the File Cabinet's name to make the title more descriptive (for example, Library::File Cabinet::Binder). The next line provides a URL that goes straight to the binder. The last line before the embedded view contains a description for the feed. This could be anything you like. In this example, we use the binder's title.
The following code snippet gets the binder's title. The variable qsBinderID is a field at the top of the form that parses the binder's ID from the URL's query string.
BinderRepID := @DbLookup(""; ""; "Maintenance"; _"GlobalProfile"; "BinderDBReplicaID"); @If( @IsError(BinderRepID); "Error getting BinderRepID - " + @Text(BinderRepID); @Text( @DbLookup(""; @Left(BinderRepID; 8) + ":" + _@Right(BinderRepID; 8); "(BinderLookup)"; qsBinderID; "Title") ) )
Next, you embed the view you created in the previous step. You need to change a few properties to display this view correctly. On the Embedded View property box, you must display the view using HTML as opposed to a Java applet. Using the Java applet breaks the XML. It is also necessary to set the value for Show single category to qsBinderID to display only the documents for the requested binder.
After the embedded view, there are two lines to end the RSS feed: </channel> and </rss>. Save and close the form. With the combination of the view and the template, you have successfully built your feed.
Modifying existing design elements
Now that the view is done, you can add an icon so users can access the RSS feed, and you can modify a few other design elements, so your links in the feed work correctly. First, modify the agent (DDMAutoLaunch), which launches a document profile given its ID and version number. The modifications made to this agent enable it to launch the document's file as well as its profile. The code has also been changed to use Option Explicit, so all variables are declared before being used. It is probably easiest to remove the existing agent, and then to copy and paste it from the supplied database to your template. Be sure to open and save the agent after pasting it to make sure it compiles correctly.
Second, change the existing File Cabinet HTML form. The changes made to the form enable it to launch a binder view given its ID in the query string. A new field is added to the form (htmlBinderUNID) to parse the binder's UNID from the URL query string, if it exists. The other change is made to the HTMLTags field. The field is changed so that if htmlBinderUNID contains a value, it creates a URL to launch that binder. Here is the new code for the HTMLTags field:
titleTemp := "Document Manager"; DbName:= @ReplaceSubstring(@Subset(@DbName;-1);"\\";"/"); LibReplicaID:= @DbLookup("";"";"(InternalAdmin)";"GlobalProfile";"LibraryReplicaID"); varPath:=@If( htmlDocUNID!=""; "/AllByUnid/" + htmlDocUNID + "?OpenDocument\">"; htmlBinderUNID != ""; "/(WebFindTOCUNID)?OpenAgent&BinderID=" + htmlBinderID + _"&BinderUNID=" + htmlBinderUNID + "\">"; "/Web+All+Binders?OpenView\">"); "<Title>" + titleTemp + "</Title> <FRAMESET FRAMEBORDER=1 BORDER=1 bordercolor = \"white\" FRAMESPACING=3 COLS=\"175,*\"> <frameset frameborder=0 border=1 framespacing=0 rows=\"134,*\"> <FRAME NAME=\"Left\" SRC=\"/" + LibReplicaID + "/WebNavigationPanel?OpenForm\" MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=\"NO\"><FRAME NAME=\"Tree\" SRC=\"/" + LibReplicaID + "/BlankForm?ReadForm\" MARGINWIDTH=0 MARGINHEIGHT=0 ></frameset> <FRAMESET FRAMEBORDER=0 BORDER=0 FRAMESPACING=0 ROWS=\"53,*\"><FRAME NAME=\"Header\" SRC=\"/" + LibReplicaID + "/WebHeaderPanel?OpenForm\" MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=\"NO\"><FRAME NAME=\"Bottom\" MARGINWIDTH=0 MARGINHEIGHT=0 SRC=\"/" + DbName + varPath + "</FRAMESET></FRAMESET>"
Again, the easiest way to incorporate these changes is to copy and paste the form. Be sure to either remove or rename the existing HTML form first.
Lastly, you need to display a link to the feed. Add a standard feed icon, such as available from Feed Icons Web site, in the binder's view. To do this, modify the WebTaskBarBinder subform. Towards the bottom of the subform, you see a table. This table contains the breadcrumb trail that is displayed in the binder view. Add a column to this table and add a field that generates the URL for the feed. You want to align the new column to the right, so the icon is displayed on the right-hand side of the browser window. To do this, make sure the cursor is in the new cell and open the Table property box.
On the Table Programming tab, set the Other field in the Cell HTML Tags section to Align=right (see figure 3).
Figure 3. Table property box
DbFilename:= @ReplaceSubstring(@Subset(@DbName;-1);"\\";"/"); "<script>document.write(\"<a href='/" + DbFilename + "/(rssBinderView)?OpenView&binderid=\" + parent._BinderID + \"'><img src='/icons/xmlrss2.jpg' border=0></a>\")</script>"
At this point, you have made all the design changes required. Now, make sure the design elements are signed with the correct ID, and then load design from the server's console. Figure 4 displays an image of what the new icon looks like in a binder view.
Figure 4. Binder view
Figure 5 displays an image of what the feed looks like in an RSS reader.
Figure 5. RSS reader
Accessing the feed
Accessing the feed is quite simple. In your Web browser, navigate to a binder to view its contents. To the far right, there is the feed icon that you supplied. Click it to load the RSS data. To make this more user friendly, you may want to add a page that describes what a feed is. For example, you can add a link next to the icon that says, "About this icon." The linked to page can describe what a feed is and how it helps the user keep track of binders and possibly suggest an RSS reader for the user to try. This is a good approach because users may get confused when they click the icon, and then see raw XML.
To add the URL to your RSS reader, simple copy and paste it. Depending upon your Domino authentication scheme, you may either see the contents of the binder or be prompted for a password.
A note about authentication
Most RSS readers can handle basic authentication. However, many people use some form of single sign-on (SSO). Typically, RSS readers don't understand SSO, so they don't load the feed correctly, if at all. One way around this is to paste the feed's URL into the reader's browser window (if it has one). That should display the SSO login page. After authenticating, the feed should now load correctly. You can also disable SSO.
Yet another alternative is to set up a replica Lotus Domino Document Manager server and to configure it with basic authentication. Then, modify the URL that the rssIcon field on the WebTaskbarBinder generates to point to the other server.
By adding two design elements and modifying three others, you can provide a simple RSS feed for binders in Lotus Domino Document Manager. This feed provides users an easy way to be notified when new content is added or modified. You can extend this simple approach to provide File Cabinet-level feeds or even feeds for other non-Lotus Domino Document Manager databases.
|Sample Notes database||rss.nsf||448KB|
- developerWorks article, "Content feeds with RSS 2.0"
- developerWorks article, "An introduction to RSS news feeds"
- developerWorks Lotus Domino Document Manager page
Get products and technologies
- Participate in the discussion forum.
- Participate in developerWorks blogs and get involved in the developerWorks community.