Comment on "Show Functions" - Caching Templates?

[greggman]

Please take this in the spirit of trying to give helpful feedback.

Maybe I'm just being stupid but I got at little lost reading the "Show Functions" chapter. I have no idea what the CouchApp is as this is the first mention of it so that was confusing.

Then, it's mentioned the show function must have no side effects. Maybe I'm mis-understanding what that means. I kind of assumed it meant that couchdb will look at the request URI and if the document referenced has not changed then your show function will not be called because couchdb can just serve the cached version. How are templates then handled? What mechanism lets couchdb know that I changed the template therefore all previously cached runs on the show function are out of date? I guess because templates are a macro expansion it's that anytime the show function is updated all cached versions are invalidated?

But then, with the first example with templates

function(doc, req) {
  // !json templates.edit
  // !json blog
  // !code vendor/couchapp/path.js
  // !code vendor/couchapp/template.js

  // we only show html
  return template(templates.edit, {
    doc : doc,
    docid : toJSON((doc && doc._id) || null),
    blog : blog,
    assets : assetPath(),
    index : listPath('index','recent-posts',{descending:true,limit:8})
  });
}

shows listPath with recent-posts. I have no idea what that does but assuming it's going to somehow generate a list of recent posts that would seem uncacheable. Or rather there's nothing in the arguments to show that indicates that calling it again with the same doc may generate different data because of some list of recent posts which has no relation to the doc passed in.

Maybe show is always called? The result is compared to the previous result, and in that case couchdb just tells the browser "Use the version you already have?" But in that case then it would seem this statement "Show functions, as they are called, have a constrained API designed to ensure cacheability" is wrong. Or what am I missing?

Sorry if I'm being dumb.