django-grunt provides settings, management commands, a view mixin and a template context processor to improve your workflow using Grunt with Django.
Grunt is great for managing tasks that manipulate your project's static files. You can use its plugins to compile LESS or SASS into CSS. You can minify JavaScript or build production files for use with RequireJS. The possibilities are limitless if you put in the effort to build your own Grunt plugins.
The problem is that typical Django projects use the staticfiles app for
managing static files. Static files are usually stored in several
locations without a common directory ancestor. Before you can use Grunt
to manipulate your static files, you need to run the collectstatic management
command to gather all of your static files into one common directory.
After running Grunt to process your collected static files, you need to change
some settings and use the runserver management command to test out the
processed files in your browser.
django-grunt helps to simplify this process with management commands and template context variables.
django-grunt is available on PyPI, so you should install it with pip:
pip install django-grunt
To use the management commands, you should add "grunt" to
INSTALLED_APPS in your settings file.
django-grunt provides two management commands to simplify your workflow:
This command runs Django's collectstatic command and then invokes grunt
with the given [grunt command ...] labels.
If you have a Grunt build command set up in your Gruntfile.js configuration,
you can run manage.py grunt build to collect your static files into the
settings.STATIC_ROOT directory and then run grunt build on them.
This command configures your project's settings so that runserver will
serve the files from settings.STATIC_ROOT and then invokes runserver.
It also configures some settings values that you can pass to your templates with the provided view mixin or context processor. These values can be used by your templates to decide which CSS and JavaScript sources to load.
The command also turns on Django's GZipMiddleware so that you can simulate
a proper gzip setup on your production server. This can help you get an
accurate feel for your project's static files payload in a production
environment.
django-grunt provides a view mixin and context processor that you can use
to pass Grunt-related context variables to your templates. Both methods
set boolean values named grunt_js and grunt_css, which your templates can
use to decide whether to serve "normal" static files or static files which
have been processed by Grunt. These values are False by default. Generally,
they'll be False in development and True in your production server's
settings file. The gruntserver management command sets them to True so you
can simulate your production setup.
The view mixin is located in grunt.views.mixins.GruntConfigMixin. You
should call its grunt_config() method to retrieve or update a dictionary
of context variables. It accepts an optional dictionary to update in the
config parameter.
If your project uses class-based views, a useful pattern is to override
Django's generic views with additional mixins that provide global configuration
data to all of your templates. As an example, suppose you have a core
application in your project and that it defines generic view overrides.
Your core.views module can provide its own TemplateView using the
GruntConfigMixin like so:
from django.views import generic
from grunt.views.mixins import GruntConfigMixin
class ConfigMixin(GruntConfigMixin, generic.base.ContextMixin):
"""
Global configuration context mixin for all generic views.
"""
def get_context_data(self, **context):
return self.grunt_config(
super(ConfigMixin, self).get_context_data(**context))
class TemplateView(ConfigMixin, generic.TemplateView):
passNow, rather than inheriting from django.views.generic.TemplateView, your
project's views should inherit from core.views.TemplateView, and they'll
automatically pass the grunt_js and grunt_css context variables to your
templates.
Note that django.views.generic.base.ContextMixin is only available in
Django 1.5+, so you'll need to make some adjustments for older versions of
Django. The refactor of the generic view get_context_data() method into
its own mixin base class was a great change, because it allows you to set
up mixin classes like this that safely call super() and simply need to be
inherited to override generic view functionality.
If you're not using class-based views, or you're not ready to commit to
providing your own generic view class overrides, you can alternatively
add "grunt.context_processors.grunt_config" to
TEMPLATE_CONTEXT_PROCESSORS in your settings file. This will add the
grunt_js and grunt_css boolean values to all of your templates whose
views use a RequestContext.
For both the mixin and the context processor, you can nest the grunt_js
and grunt_css context variables under a key in the context dictionary.
For the mixin, pass a key argument to the grunt_config() call. For
the context processor, add a GRUNT_TEMPLATE_CONTEXT_KEY to your settings
file.
I built this project to improve my workflow with Django and Grunt. I work in a *nix environment, so I didn't bother with trying to support other platforms.
The grunt management command checks for the availability of Grunt on the
command line by running the *nix command which grunt. This will fail
on other platforms. I wasn't satisfied with the various cross-platform
hacks for this problem that I found with a cursory Web search, so
this Django application is only useful on *nix platforms for now.
The management command API that django-grunt previously defined has been extracted and expanded into its own project, django-commando. If you need to write, override or sequence existing management commands, consider using django-commando.
This project currently lacks tests. I'm not feeling particularly motivated to figure out a decent way to test the management commands. The code is pretty straightforward and succinct, but it would be better with some test coverage.
When I have some more time, I'm hoping to add tools to seamlessly integrate Grunt unit testing tools with Django. However, my goal is to keep the project as generic as possible, so that it's not tied to any specific Grunt plugins.
Pull requests are always welcome if you have ideas to fix this project's shortcomings or add new, useful features. Happy coding!