A template that makes it easier to write sophisticated progressive enhancement, while keeping style rules in CSS without having to blatter them in Javascript. Also provides some standard blocks in the Django template language that we think you'll like.
What you need to know:
-
Add 'django_cape' to your
INSTALLED_APPS
, and extendcape/shell.html
. -
Set up Javascript variables in
javascript-variables
. -
Pull in libraries in
javascript-libraries
. -
Apply progressive enhancement in
javascript-enhance
. -
Asynchronous code, analytics and further behavioural changes (eg form submission) will generally go in
javascript-asynchronous
. -
If your primary language is not British English, override
html-lang
. -
If you need to add attributes to the
<html>
element, put them inhtml-attributes
. -
Add your normal page content in
body-sheath
. -
If you use analytics, put them in
javascript-analytics
. -
If you really need to put some JavaScript in the
<head>
(eg for measuring page timing) put it injavascript-head
.
When everything runs smoothly, the CSS flow is as follows:
html
: initial statehtml.js-capable
: script capability detected during load (can be useful to hide things that are being enhanced)html.js-ready
: libraries are loaded and your enhancement code has run
When things go wrong, the CSS flow is as follows:
html
: initial statehtml.js-capable
: script capability detected during load (can be useful to hide things that are being enhanced)html.js-timeout
: Javascript error or page load cancellation means that not all enhancement code has run (or maybe none has)
Generally you use .js-capable
to hide stuff, .js-timeout
to show it again, and don't actually use .js-ready
for very much as you'll actually add .enhanced
or something while running your code, or during jQuery plugin initialisation. If you can hide any enhanced content and show the non-enhanced versions, you can recover entirely; if you enhance content in-place then it may be harder for you to recover from Javascript failure. (Which may teach you to be sparing in your use of such techniques.)
Although CAPE is primarily about better progressive enhancement, we also provide a template with recommended slots for the <head>
of your pages, which
you use by extending cape/base.html
instead of cape/shell.html
. It contains the following blocks:
head-title-website
: name of the websitehead-title-page
: title of the pagehead-title
: override if you need more control over the<title>
taghead-html5shim
: included by default, override if you don't want ithead-viewport
: set todevice-width
with a scale of 1 by default, override if you hate mobile usershead-meta
: where to put any other<meta>
tagshead-icons
: where to declare your favicons and Apple touch iconshead-links
: where to put<link>
tags, such asrel=canonical
head-alternate
: where to put your Atom feedshead-css-stylesheet
: where to put the<link>
to your stylesheethead-css-localstyles
: where to put page-specific CSS links or blockshead-css
: override if you need more control over styles
CAPE was developed by Mark Norman Francis and James Aylett. Get in touch via our project page on github: https://github.com/devfort/django-cape.