ETags ----- ETags are used in to check whether pages need to be re-calculated or can be served from cache. An ETag is simply a string. Under ``plone.app.caching``, it is a string of tokens separated by pipe characters. The tokens hold values such as a user id, the current skin name, or a counter indicating how many objects have been added to the site. The idea is that the browser sends a request with the ETag included in an ``If-None-Match`` header. Plone can then quickly calculate the current ETag for the requested resource. If the ETag is the same, Plone can reply with ``304 NOT MODIFIED`` response, telling the browser to use its cached copy. Otherwise, Plone renders the page and returns it as normal. Many caching operations use ETags. The tokens to include are typically listed in an ``etags`` tuple in the operation's options. The ETag names tokens supported by default are: * userid The current user's id * roles A list of the current user's roles in the given context * language The language(s) accepted by the browser, in the ``ACCEPT_LANGUAGE`` header * userLanguage The current user's preferred language * gzip Whether or not the content is going to be served compressed * lastModified A timestamp indicating the last-modified date of the given context * catalogCounter A counter that is incremented each time the catalog is updated, i.e. each time content in the site is changed. * locked Whether or not the given context is locked for editing. * skin The name of the current skin (theme) * resourceRegistries A timestamp indicating the most recent last-modified date for all three Resource Registries. This is useful for avoiding requests for expired resources from cached pages. It is possible to provide additional tokens by registering an ``IETagValue`` adapter. This should be a named adapter on the published object (typically a view, file resource or Zope page template object) and request, with a unique name. The name is used to look up the component. Thus, you can also override one of the tokens above for a particular type of context or request (e.g. via a browser layer), by registering a more specific adapter with the same name. As an example, here is the ``language`` adapter:: from zope.interface import implements from zope.interface import Interface from zope.component import adapts from plone.app.caching.interfaces import IETagValue class Language(object): """The ``language`` etag component, returning the value of the HTTP_ACCEPT_LANGUAGE request key. """ implements(IETagValue) adapts(Interface, Interface) def __init__(self, published, request): self.published = published self.request = request def __call__(self): return self.request.get('HTTP_ACCEPT_LANGUAGE', '') This is registered in ZCML like so::