Server side represent! (Part 2)

Last time we pried open the hood of WebManager for an in depth look at the server side includes. Even though I got positive feedback on that article, I felt that I weaseled out where it mattered most. Here is the excerpt of the blog that I am talking about:

Note: The Caching document briefly touches on the subject of how caching reacts to URLs. To learn the gritty details you are better off scouring the source of the standard presentation for "*Ssi.jspf" files with working examples.

...

But gritty details is what we love, don't we? It's them gritty details that make or break your code. It's them details that make you log in on saturday morning to do some tweaks even though you maybe had a few drinks too many the evening before. But I digress. ;-)

Time to make up for my omission!

Before I do that, a word of caution. Remember, we're peeking under the hood of WebManager. There are no guarantees that a few years from now under the hood WebManager will still work like this. However, this is how it works in march 2009 and knowing the details will aid you in your quest to understand WebManager and help you build the best SSI urls. So I guess a bit of in depth exploring won't hurt much.

Back to the subject. Server side includes have everything to do with caching. They use a different URL than the page they are on and the content is cached like any other request.

If you have worked with caching, you know that caching is not so much about "what is being stored?", but much more about "when is it going to be refreshed?". Refreshing cached content is handled with timestamps in several database tables. Basically, events in WebManager trigger the setting of a timestamp in one of the database tables. When a request reaches the caching module, it responds to the new value in the database by retrieving fresh content. Note that caching uses lazy evaluation, so unless URLs are requested, nothing is refreshed.

There are six tables in which WebManager stores timestamps. From the chapter "Timestamps in the database" of the document Caching:

By examining the URL of a request, the caching module decides what table to use for its timestamp. The request parameters below are sorted in order of importance, meaning the same order in which the caching module examines them. For example, if a URL contains "contentid=27181&tsobjectid=31415", the "tsobjectid" is most important and therefore used to determine the timestamp for this particular URL.

• cto or cachetimeout
• tsobjectid
• jelly
• jellycontentids
• mediaTermIds
• forum
• formelement
• typeofpage and dbid
• contentid
• id

I will delve deeper into these parameters below with a few examples.

cto or cachetimeout

These request parameters are used to determine a fixed number of seconds for the URL to be cached. So putting "cachetimeout=900" in your SSI URL will cause that URL to be cached for 15 minutes, regardless of what happens with timestamps in the database. You can either use "cto" or "cachetimeout", they are equivalent. Example usage:

<wm:link var="ssiLink" cachetimeout="900"
    passOn="cachetimeout"
    ssiObjectId="${presentationcontext.pagePart.id}"
    ssiObjectClassName="nl.gx.webmanager.cms.layout.PagePart" />

Setting the value for cachetimeout to something lower than the /web/setup setting "cache_timestamp_expire" is useless. That setting determines the minimum time before any timestamp is reconsidered.

tsobjectid

When "tsobjectid" is encountered in the querystring, that id is used to retrieve a timestamp from the "tsObjectTimestamp" table.

SELECT obj_timestamp
FROM tsObjectTimestamp
WHERE sw_object = ?

The timestamps for pages, page sections and certain elements are stored in this table.

<wm:link var="ssiLink" tsobjectid="${page.id}"
    passOn="tsobjectid"
    reference="${presentationcontext.page}" />

jelly

You can put "jelly=true" in the URL of your SSI to let the cached version expire when anything changes in the Media Repository. Note: "anything" is pretty wide, isn't it? How true! Every import from a feed, every edit in an article will cause a change and therefore will warrant a refresh for your URL. I advise against using "jelly=true", instead try using "cachetimeout".

jellycontentids

Put "jellycontentids=111,222,333,444" if you want your caching to depend on these four articles in the Media Repository. If one of those four articles changes, the URL will be refreshed. This is typically used for media list elements.

<wm:link var="ssiLink" jellycontentids="${contentIds}"
    ssiObjectId="${element.id}"
    ssiObjectClassName="nl.gx.webmanager.cms.mediarepository.MediaCollectionElement"
    passOn="${passOn}"
    webid="${presentationcontext.website.id}" />

You can verify the timestamp for those articles by doing:

SELECT content_timestamp
FROM tsJellyContentTimestamp
WHERE contentid = ?

mediaTermIds

Articles in the Media Repository can have terms assigned to them. When an article is edited, the timestamps for all assigned terms are also updated. You can make the caching of your URL dependant on the timestamp information for terms.

<wm:link var="ssiLink" mediaTermIds="${termIds}"
    passOn="${passOn}" ssiObjectId="${element.id}"
    ssiObjectClassName="nl.gx.webmanager.cms.mediarepository.MediaCollectionElement"
    webid="${presentationcontext.website.id}" />

The timestamps can be retrieved from the database by doing:

SELECT term_timestamp
FROM tsTermTimestamp
WHERE term = ?

forum

To make the caching of your URL dependant on the reactions for a specific discussion forum, use the "forum" request parameter.

<wm:link var="ssiLink" ssiObjectId="${forumElement.id}"
    ssiObjectClassName="nl.gx.webmanager.cms.forum.ForumElement"
    passOn="${passOn}"
    forum="${forumElement.forum.id}" />

You can verify the timestamp by doing:

SELECT disc_timestamp
FROM tsDiscussionTimestamp
WHERE discussion = ? AND thread = -1

formelement

The caching information for a form can be used as freshness indicator for your URL by putting "formelement" in the SSI URL. You can verify the value of the timestamp by doing:

SELECT obj_timestamp
FROM tsObjectTimestamp
WHERE sw_object = ?

typeofpage and dbid

Database items are defined by the "typeofpage" and "dbid" parameters. The timestamp information for a database item can be verified with the following URL:

SELECT dbid_timestamp
FROM tsDatabaseEntityTimestamp
WHERE database_entity = ? AND dbid = ?

contentid

Each article in the Media Repository has a "contentid" which can be used in your SSI link. If you do that, the URL will be refreshed when the article changes.

<wm:link var="ssiLink" contentid="${contentId}"
    passOn="${passOn}" ssiObjectId="${element.id}"
    ssiObjectClassName="nl.gx.webmanager.cms.mediarepository.MediaCollectionElement"
    webid="${presentationcontext.website.id}" />

You can verify the timestamp value of a particular article by doing:

SELECT content_timestamp
FROM tsJellyContentTimestamp
WHERE contentid = ?

id

The id of a page can also be used to make the caching of your SSI URL dependant on a page. Because the homepage can be called without id ("/web/show"), a "start_object_id" is defined in /web/setup as fallback. You can verify the timestamp for a page by doing:

SELECT obj_timestamp
FROM tsObjectTimestamp 
WHERE sw_object = ?

Come to think of it, why on earth would you want to create an SSI and then make it dependant on the page it is on? If the two need to be refreshed at the same time, skip creating an SSI and simply put the content on a page!

Summary

Well, there you have it; the parameters that you can use in your SSI link and the way they link to timestamps in the database.

Hopefully this info will allow you to get nice and close with WebManager and the caching module for squaky clean code. Kind of like the movie below. ^.^

Till next time!

Patrick