PK VpCK@ @ - django-html5-appcache-0.3.1/installation.html
To get started using django-html5-appcache install it with pip:
$ pip install django-html5-appcache
If you want to use the development version install from github:
$ pip install git+https://github.com/nephila/django-html5-appcache.git#egg=django-html5-appcache
Requirements will be automatically installed.
Run migrate command to sync your database:
$ python manage.py migrate html5_appcache
Warning
Migrations have been added in 0.3.0. Don’t skip this if you are upgrading from 0.2.
Add html5_appcache to INSTALLED_APPS.
Include in your URLCONF:
urlpatterns += patterns('',
url('^', include('html5_appcache.urls')),
)
Warning
on Django 1.4+ (or django CMS 2.4+) you may need to use i18npatterns instead of patterns above, depending on you project layout.
Enable appcache discovery by adding the lines below in urls.py:
import html5_appcache
html5_appcache.autodiscover()
Add the middleware just below django.middleware.cache.UpdateCacheMiddleware, if used, or at the topmost position:
'html5_appcache.middleware.appcache_middleware.AppCacheAssetsFromResponse'
Insert appcache_link template tag in your templates:
{% load appcache_tags %}
<html {% appcache_link %} >
<head>
...
</head>
<body>
...
</body>
</html>
Enable the cache for your project. Refer to Django CACHES configuration.
django-html5-appcache supports django CMS out-of-the-box.
django CMS integration delivers support for all the the default plugins; to enable your own plugins see django CMS plugins below.
To enable, add the following to INSTALLED_APPS:
If you use applications hooked to django CMS AppHooks, you have to write the AppCache class; if you use the sitemap method to discover the urls, you must add conditional urls loading to the main``urls.py``.
As the scraping uses the internal testserver to deliver the contents, Apphooks are not hooked so you have to provide an alternate method to attach the urls.
For this purpose use the following snippet:
if getattr(settings, 'HTML5_APPCACHE_OVERRIDDEN_URLCONF', False):
urlpatterns += patterns('',
url(r'^my-url', include("my-app.urls")),
...
)
Where my-url is the url where the apphook is attached to, and my-app.urls is the urlconf of you application. Repeat for every attached apphook and for every slug they are attached to.
To enable cache invalidation for your own plugins, you must create an AppCache class for your plugin models too.
The example below is the implementation of an appcache for django CMS text plugin:
from html5_appcache import appcache_registry
from html5_appcache.appcache_base import BaseAppCache
from cms.plugins.text.models import Text
class CmsTextAppCache(BaseAppCache):
models = (Text, )
def signal_connector(self, instance, **kwargs):
self.manager.reset_manifest()
appcache_registry.register(CmsTextAppCache())
django-html5-appcache leverages django cache, test and signals frameworks to explore project pages and assets and generate an appcache manifest file.
The manifest file is generated collecting all the cached urls and exploring them using the test client to gather asset urls and including them in the manifest itself.
This can be quite resource intensive, so the manifest file is saved in the cache; the view that actually delivers the file manifest to the browser can thus use the cache to serve it with no performance impact.
The manifest file is generated out-of-band using a django command so you can execute the command manually or in a cron job. Since 0.3.0 a view is provided, see Web interface
Whenever a registered model is saved or deleted (see Enabling caching in your application on how to enable this for your application), manifest cache is marked as dirty; this has no immediate effect on the manifest file served, as the oudated copy is still served.
django-html5-appcache uses the sitemap as a primary mean to discover urls in the web application.
This is a two steps process:
In the scraping phase, the actual HTML of each page is generated and analyed.
Currently django-html5-appcache extracts data from img, script and link tags. See AppCacheAssetsFromResponse for more in depth details.
See Markup on how to customize the assets extraction in your markup.
Additional to the sitemap method above, you can define your own custom url list; in this case, it’s your duty to define the list of assets in those urls.
django-html5-appcache define two commands to control the manifest cache:
update_manifest is the command to update the manifest cache.
Run:
$ python manage.py update_manifest
and your manifest file will be updated.
Mostly a debugging tool, clear_manifest wipe the manifest cache completely.
h | ||
html5_appcache | ||
html5_appcache.appcache_base | ||
html5_appcache.middleware.appcache_middleware |
Since 0.3.0 django-html5-appcache has a small web interface to check the cache status and update the manifest file.
The appcache_icon templatag show the cache status icon and hooks it to an ajax call that trigger the manifest update.
Add the following lines to any template you want the cache status badge to appear:
{% load appcache_tags %}
...
...
{% appcache_link %}
Both the view that shows the cache status and the view to update the manifest are subject to specific permissions:
You need to explicitly add these permissions to any user who manages the appcache.
Both the views and the templatetag checks this permissions, so you can actually write your own code to call the views and your code will still be safe.