Django application for handling edge side include (ESI)
Warning
This document is speculative until this warning is removed. Don't expect the awesomeness described within as long as this is here.
Warning
This is a proof of concept level package. Don't use it in production unless you're willing to put up with potentially buggy code, bad performance, and all manner of things going wrong. If you're cool by that, go for it.
ESI allows you to specify sections of the site that require different caching strategies and can be sent to a smart caching layer for rendering.
For example, if you want to send a page that is identical for every user except for a welcome message, you would render that message like:
<html>
<body>
<esi:include "/esi/welcome-message.html" />
... the rest of the page ...
</body>
</html>
A smart proxy such as Varnish and the middleware included with
armstrong.esi can cache this page, then render it dropping in the dynamic
portions without having to talk to the app server again.
Use this package to specify sections of your templates that can be rendered via
ESI. You call the {% esi %} template tag and give it the name of a
registered view and it will replace itself with the appropriate
<esi:include> tag. For example, the above example becomes:
{% load esi %}
<html>
<body>
{% esi welcome_message %}
... the rest of the page ...
</body>
</html>
This replaces our {% esi %} tag with a <esi:include> tag pointing to
the URL for that view.
Varnish integrates fairly easily with armstrong.esi. The EsiHeaderMiddleware sets the 'X-ESI' header to 'true' if the page request has esi tags on it. To enable esi processing in varnish for pages that need it add the following to your vcl_fetch method:
if (beresp.http.X-ESI) {
set beresp.do_esi = true;
}
The template tag reads the DEBUG settings value [1] and if set to True
renders the view with the current request rather than including the
<esi:include> tag.
You can change this default behavior to through several settings:
TT_ESI_FORCE- Setting to
Truemeans that a<esi::include>tag will always be generated. (Default:False) TT_ESI_NEVER- Setting to
Truemeans that a<esi:include>tag will never be generated. TheTT_ESI_FORCEsetting always takes precedence. Any time it is set, this value has no meaning. (Default:True)
Recommending installation is through pip:
prompt> pip install -e git://github.com/texastribune/armstrong.esi#egg=armstrong.esi
Once installed, you must add the app to your INSTALLED_APPS inside your
settings:
'armstrong.esi',
You must also enable the custom middleware if you want to use the internal ESI
caching. To do this, add the following line to your MIDDLEWARE_CLASSES:
'armstrong.esi.middleware.EsiMiddleware',
Edge-Side Includes are great for increasing the cachability of your pages, but
they traditionally require additional overhead to get running.
armstrong.esi includes a middleware that can handle the caching for you so
you don't have to setup and maintain any additional server hardware.
.. todo:: add information explaining what is happening
Contributions are welcomed and encouraged. Please follow these instructions for making a contribution:
- Fork this repository
- Create a topic branch. Be descriptive with its name.
- Make some great addition, fix a bug, or clean it up
- Submit a Pull Request
You can also report bugs via Issue Tracker.
Footnotes
| [1] | http://docs.djangoproject.com/en/1.2/ref/settings/#debug |