December 2012 - Page 2 of 3

Custom Pystache Template And Loader Classes For Django

Update: I’ve posted the code at github here.

Wanting to keep my server-side and client-side templates identical, I noticed there wasn’t a good solution for using Mustache/Pystache/Handlebars templates alongside the Django templating language.

The existing one that I saw used Pystache internals, and I’m not even sure they’re still valid in the latest Pystache versions.

The other existing one that I saw let you do the equivalent of #include “something.mustache” within the Django templates, which wasn’t what I was looking for either.

So I went ahead and wrote a set of PystacheTemplate and Pystache*Loader classes which do it all within the specifications of the Django infrastructure, and, I set them up so that you can specify the exact file extensions you want them to operate on, i.e. just .mustache, .handlebars, and .hbs files by default. This doesn’t mean you can mix Mustache directly into Django templates, which doesn’t make sense (and is mildly redundant), but it does mean you can render complete Mustache template files directly, which is awesome if you’re wanting to share those templates or partials between client and server.

Copy this file somewhere into your project or app folders:

"""
Copyright (c) 2012 Max Vilimpoc

Permission is hereby granted, free of charge, to any person obtaining 
a copy of this software and associated documentation files (the "Software"), 
to deal in the Software without restriction, including without limitation 
the rights to use, copy, modify, merge, publish, distribute, sublicense, 
and/or sell copies of the Software, and to permit persons to whom 
the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be 
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE 
OR OTHER DEALINGS IN THE SOFTWARE.
"""

from django.template.loaders import app_directories, filesystem
from django.template.base import TemplateDoesNotExist
import pystache
import os

"""
Based on:

https://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.Template
https://docs.djangoproject.com/en/dev/ref/templates/api/#loading-templates
https://docs.djangoproject.com/en/dev/ref/templates/api/#using-an-alternative-template-language
"""

class PystacheTemplate():
    def __init__(self, templateString):
        self.parsed   = pystache.parse(templateString)
        self.renderer = pystache.Renderer()

    def render(self, context):
        # Flatten the Django Context into a single dictionary.
        flatContext = {}
        for d in context.dicts:
            flatContext.update(d)

        return self.renderer.render(self.parsed, flatContext)

"""
Based on:

https://docs.djangoproject.com/en/dev/ref/templates/api/#loader-types

Yeah, it's two identical classes separated by a name.
Metaprogramming comes to mind.

According to django.template.loader.BaseLoader:

"A loader may return an already-compiled template instead of the actual
template source. In that case the path returned should be None, since the
path information is associated with the template during the compilation,
which has already been done."

---

We can make the Loader check the file extension as well,
so it will only parse Mustache-compatible files:

.handlebars, .hbs, .mustache, and so on.

This means you can actually keep using the normal Django loaders
too, for other file extensions!

---

The key piece is in django/template/loader.py

def find_template(name, dirs=None):
    [...]
    for loader in template_source_loaders:
        try:
            source, display_name = loader(name, dirs)
            return (source, make_origin(display_name, loader, name, dirs))
        except TemplateDoesNotExist:
            pass
    raise TemplateDoesNotExist(name)
    [...]

Note: 

This could still mess up if the custom loader passes 
through a Handlebars template with an .html extension.

Later loaders would then throw a fit.
"""

EXTENSIONS = ['.handlebars', '.hbs', '.mustache']

class PystacheAppDirectoriesLoader(app_directories.Loader):
    is_usable = True

    def load_template(self, template_name, template_dirs=None):
        # Only allow certain template types.
        filename, extension = os.path.splitext(template_name)
        if extension not in EXTENSIONS:
            raise TemplateDoesNotExist

        source, origin = self.load_template_source(template_name, template_dirs)
        template = PystacheTemplate(source)
        return template, None

class PystacheFilesystemLoader(filesystem.Loader):
    is_usable = True

    def load_template(self, template_name, template_dirs=None):
        # Only allow certain template types.
        filename, extension = os.path.splitext(template_name)
        if extension not in EXTENSIONS:
            raise TemplateDoesNotExist

        source, origin = self.load_template_source(template_name, template_dirs)
        template = PystacheTemplate(source)
        return template, None

"""
Now update the settings.py file to use the custom Loaders,
putting them ahead of Django's default Loaders in the
TEMPLATE_LOADERS setting.

TEMPLATE_LOADERS = (
    'project.templates.PystacheFilesystemLoader',
    'project.templates.PystacheAppDirectoriesLoader',
    [...]
)
"""

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

"""

Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the "Software"),

to deal in the Software without restriction, including without limitation

the rights to use, copy, modify, merge, publish, distribute, sublicense,

and/or sell copies of the Software, and to permit persons to whom

the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be

included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL

THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR

OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,

ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE

OR OTHER DEALINGS IN THE SOFTWARE.

"""

from django.template.loaders import app_directories, filesystem

from django.template.base import TemplateDoesNotExist

import pystache

import os

"""

Based on:

https://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.Template

https://docs.djangoproject.com/en/dev/ref/templates/api/#loading-templates

https://docs.djangoproject.com/en/dev/ref/templates/api/#using-an-alternative-template-language

"""

class PystacheTemplate():

def __init__(self, templateString):

self.parsed = pystache.parse(templateString)

self.renderer = pystache.Renderer()

def render(self, context):

# Flatten the Django Context into a single dictionary.

flatContext = {}

for d in context.dicts:

flatContext.update(d)

return self.renderer.render(self.parsed, flatContext)

"""

Based on:

https://docs.djangoproject.com/en/dev/ref/templates/api/#loader-types

Yeah, it's two identical classes separated by a name.

Metaprogramming comes to mind.

According to django.template.loader.BaseLoader:

"A loader may return an already-compiled template instead of the actual

template source. In that case the path returned should be None, since the

path information is associated with the template during the compilation,

which has already been done."

---

We can make the Loader check the file extension as well,

so it will only parse Mustache-compatible files:

.handlebars, .hbs, .mustache, and so on.

This means you can actually keep using the normal Django loaders

too, for other file extensions!

---

The key piece is in django/template/loader.py

def find_template(name, dirs=None):

[...]

for loader in template_source_loaders:

try:

source, display_name = loader(name, dirs)

return (source, make_origin(display_name, loader, name, dirs))

except TemplateDoesNotExist:

pass

raise TemplateDoesNotExist(name)

[...]

Note:

This could still mess up if the custom loader passes

through a Handlebars template with an .html extension.

Later loaders would then throw a fit.

"""

EXTENSIONS = ['.handlebars', '.hbs', '.mustache']

class PystacheAppDirectoriesLoader(app_directories.Loader):

is_usable = True

def load_template(self, template_name, template_dirs=None):

# Only allow certain template types.

filename, extension = os.path.splitext(template_name)

if extension not in EXTENSIONS:

raise TemplateDoesNotExist

source, origin = self.load_template_source(template_name, template_dirs)

template = PystacheTemplate(source)

return template, None

class PystacheFilesystemLoader(filesystem.Loader):

is_usable = True

def load_template(self, template_name, template_dirs=None):

# Only allow certain template types.

filename, extension = os.path.splitext(template_name)

if extension not in EXTENSIONS:

raise TemplateDoesNotExist

source, origin = self.load_template_source(template_name, template_dirs)

template = PystacheTemplate(source)

return template, None

"""

Now update the settings.py file to use the custom Loaders,

putting them ahead of Django's default Loaders in the

TEMPLATE_LOADERS setting.

TEMPLATE_LOADERS = (

'project.templates.PystacheFilesystemLoader',

'project.templates.PystacheAppDirectoriesLoader',

[...]

)

"""

Then you can just update the settings.py file to use the custom Loaders, putting them ahead of Django’s default Loaders in the TEMPLATE_LOADERS setting:

TEMPLATE_LOADERS = (
    'project.templates.PystacheFilesystemLoader',
    'project.templates.PystacheAppDirectoriesLoader',
    [...]
)

TEMPLATE_LOADERS = (

'project.templates.PystacheFilesystemLoader',

'project.templates.PystacheAppDirectoriesLoader',

[...]

)

Then if you have, say, a file called index.handlebars somewhere in one of your app directory template/ folders or somewhere else in the TEMPLATE_DIRS list, you can just do this in one of your views:

def someView(request):
    return render_to_response('index.handlebars', { 'title': 'Hello, Awesome.' })

1 2	def someView(request): return render_to_response('index.handlebars', { 'title': 'Hello, Awesome.' })

And all will be good.

Please let me know in the comments if you have any problems with this. (Speed might one of them, I haven’t extensively tested this yet. But I plan to cache these using the Django template cache loader.)

Generating List Of Mustache Tags In A Template

Google falls over again looking for:

“generating list of mustache tags in a template”
“regular expression list of mustache tags in a template”
“grep list of mustache tags in a template”
“get list of mustache tags in a template”
“grep expression for mustache tags”

What am I trying to do? I have a Mustache template, and I want to pull out the list of tags I am using in it, because I need to filter a bigger chunk of JSON data to only contain those tags. This JSON data will eventually be used as the context that is then used to .render() the output.

Google needs to reinstate exact-quote indexing, the fuzzy searches of the past few years are making it really hard to find relevant links. (Yes, I probably should have the regex rules memorized, but this can’t be the first time someone’s been looking for this.)

For the record, the command I used to generate this list:

grep -o -E "{{(w+)}}" file.mustache | sort --unique

1	grep -o -E "{{(w+)}}" file.mustache \| sort --unique

Update 2 March 2013:

The above command was perhaps a bit too simple, it gives the tags in the form of a list of “{{tag}}”.

To get rid of the mustache brackets, you have to run the point through sed.

grep -o -E -e "{{(w+)}}" index.handlebars | sort --unique | sed -e 's_{{__g' -e 's_}}__g'

1	grep -o -E -e "{{(w+)}}" index.handlebars \| sort --unique \| sed -e 's_{{__g' -e 's_}}__g'

In Python, the following regex will also give you all the tag names, sans brackets:

import re
sorted(set(re.findall('{{[^/#]*(w+)}}', template_text)))

1 2	import re sorted(set(re.findall('{{[^/#]*(w+)}}', template_text)))

Implicit Things

As a learning exercise, I converted a piece of Javascript code i’d written into CoffeeScript.

So what’s wrong with this?

initialize = ->
    $('select[name="language"]').change (e) ->
        renderLocalizedText $(@).val()
    return

# Initialize the application on DOM ready event.                                                                                                     
$(document).on 'ready', ->
    console.log "hello, world"
    initialize

initialize = ->

$('select[name="language"]').change (e) ->

renderLocalizedText $(@).val()

return

# Initialize the application on DOM ready event.

$(document).on 'ready', ->

console.log "hello, world"

initialize

Oh that’s right, initialize doesn’t get called.

It must be “initialize()” when you want to call a function w/no params. But when you do have params, you can leave the parens off. What inconsistent bullshit is this? I guess it’s nice that “initialize” by itself is a statement w/o a side effect. But then when you run it through the compiler (when the hanging return isn’t there), it spits out “return initialize;”, which isn’t what I meant at all and could be a side effect for anyone trying to maintain this down the road. Better to make it explicit that this thing won’t return anything a caller can (ab)use, until and unless I choose to make that the case.

So I’ve been adding hanging returns so the compiled code returns nothing as often as it should.

Sigh, I don’t know that I dig the whole implicit “return whatever was on the last line” thing that so many of these terse scripting languages have. And it strikes me as a weird idea to try and save on parens.

So the CoffeeScript adventure begins, but I’ll be damned if I’m not already building the defensive programming idioms in.

emacs Settings

emacs is incredibly powerful, but configuration can be a royal pain sometime.

Here’s me trying to set the indentation levels when editing HTML. (Because it’s not obvious at all.)

M-x customize-group RET nxml

1	M-x customize-group RET nxml

Go to Nxml Child Indent, set that to what you want. In my case, I use 4 spaces per TAB.

These are the settings in my .emacs (you can see that I’m really trying to just set 4 spaces per TAB for all the modes):

(setq-default tab-width 4)
(custom-set-variables
  ;; custom-set-variables was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 '(django-indent-width 4)
 '(nxhtml-default-encoding (quote utf-8))
 '(nxml-child-indent 4))
(custom-set-faces
  ;; custom-set-faces was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 )

(add-hook 'html-mode-hook
  (lambda ()
    ;; Default indentation is usually 2 spaces, changing to 4.
    (set (make-local-variable 'sgml-basic-offset) 4)))

(setq-default tab-width 4)

(custom-set-variables

;; custom-set-variables was added by Custom.

;; If you edit it by hand, you could mess it up, so be careful.

;; Your init file should contain only one such instance.

;; If there is more than one, they won't work right.

'(django-indent-width 4)

'(nxhtml-default-encoding (quote utf-8))

'(nxml-child-indent 4))

(custom-set-faces

;; custom-set-faces was added by Custom.

;; If you edit it by hand, you could mess it up, so be careful.

;; Your init file should contain only one such instance.

;; If there is more than one, they won't work right.

)

(add-hook 'html-mode-hook

(lambda ()

;; Default indentation is usually 2 spaces, changing to 4.

(set (make-local-variable 'sgml-basic-offset) 4)))

Emacs can be annoying in the sheer number of uncorrelated variables it uses for the various modes.

Building An Assets Subdirectory When Using Brunch

Brunch has an opinion about the app/assets/ directory that it generates as part of an app skeleton. It simply copies these files over to the deployment directory, w/o running them through any minification.

But let’s say I want to build a standalone page under the assets/ directory, maybe for a signup form for my website (which I don’t really feel like making into a Backbone View). This form could share the vendor/ minified files, but would not have a need for the app.js or app.css files.

By default, Brunch wouldn’t process those files, as they would be somewhere under, say, app/assets/signup.

Here’s a custom config_signup.coffee file that builds files in the assets/signup/ directory and copies them where I expect. It would be pretty sweet if this could be somehow chained onto the main CoffeeScript file.

Now when I run brunch build -c config_signup.coffee –minify, I can get the same processing on this particular subset of the site.

# Manages the build for the signup page.                                                                                                              
exports.config =
    # See docs at http://brunch.readthedocs.org/en/latest/config.html.                                                                                
    paths:
        public: '/path/to/deployment/signup'

    coffeelint:
	pattern: /^app/.*.coffee$/
	options:
            indentation:
		value: 4
		level: "error"

    files:
        javascripts:
            joinTo:
                'index.js': /^app(/|\)assets(/|\)signup/

	stylesheets:
            joinTo: 'index.css': /^app(/|\)assets(/|\)signup/

    conventions:
	ignored: -> false
	assets: -> false

# Manages the build for the signup page.

exports.config =

# See docs at http://brunch.readthedocs.org/en/latest/config.html.

paths:

public: '/path/to/deployment/signup'

coffeelint:

pattern: /^app/.*.coffee$/

options:

indentation:

value: 4

level: "error"

files:

javascripts:

joinTo:

'index.js': /^app(/|\)assets(/|\)signup/

stylesheets:

joinTo: 'index.css': /^app(/|\)assets(/|\)signup/

conventions:

ignored: -> false

assets: -> false