breakdown 1.0.4

Lightweight jinja2 template prototyping server

Description

Breakdown is a lightweight python webserver that parses jinja2 templates. It’s intended to be used by designers for doing rapid prototyping.

Basic Usage

Breakdown needs a templates directory and a static directory to serve from. If your working directory contains these, you can simply run breakdown with no arguments:

$ breakdown

Or, you can specify the path to a directory containing templates and static:

$ breakdown /path/to/project

Breakdown will also work with a django project structure. If the project path contains an apps directory, breakdown will automatically detect this and combine the static and templates directories for each django app. You’ll also get a listing of the directories it found. Here’s the output of running breakdown on a django project with two apps: ‘mainsite’ and ‘blog’:

$ breakdown ~/django/myproject
Serving templates from:
  /Users/josh/django/myproject/apps/blog/templates
  /Users/josh/django/myproject/apps/mainsite/templates

Serving static data from:
  /Users/josh/django/myproject/apps/blog/static
  /Users/josh/django/myproject/apps/mainsite/static

Template Context Objects

When loading a template, breakdown will attempt to load a json dictionary of the same name from the context directory (context by default) and add it to the page context. For example, when loading base.html breakdown will try to load <project root>/context/base.json, and when loading blog/article_detail.html breakdown will look for <project root>/context/blog/article_detail.json.

Objects defined in a context dictionary become available to the template. For example, if we define base.json like this:

{
 "request": {
    "user": {
         "name":"Austin",
         "member": "Member #4812"
     }
 },
 "object": {
    "id": 555,
    "title": "Excellent Blog Post"
 }
}

then request and object become available to the base.html template, and {{request.user.name}} yields Austin.

You can specify a function by adding a key with trailing parentheses:

{
 "request": {
    "user": {
         "name":"Austin",
         "is_authenticated()": true,
         "birth_year()": 1982,
         "middle_name()": "David",
         "member": "Member #4812"
     }
 }
}

The trailing parentheses are removed, and now {{request.user.is_authenticated()}} returns True. Functions defined in this way ignore any arguments and return the value specified in the json dictionary. {{request.user.is_authenticated(arg1, arg2, arg3)}} also returns True.

Viewing Templates

Once breakdown is running, it will print the local URL the webserver is listening on:

Server running at http://127.0.0.1:5000 ...

You can now view templates in your browser by navigating to http://127.0.0.1:5000. However, you won’t see anything here unless one of your template directories contains a file named index.html. The URL of any template (besides index.html) will be identical to its filename, with all relative paths preserved. Below is an example of template filenames and their corresponding URL on the local server:

Template	URL
index.html	http://127.0.0.1:5000/
article.html	http://127.0.0.1:5000/article
blog/index.html	http://127.0.0.1:5000/blog
blog/post.html	http://127.0.0.1:5000/blog/post

Note: The server will accept template URLs with or without .html appended to them

Additional Features

Template tags

For convenience, A few template functions have been added to the jinja2 template API:

{{ greeking() }}

Generates a block of randomized lorem ipsum text marked-up with various HTML elements: <em>, <strong>, <code>, <a>, <ol>, and <ul>.

{{ image(width, height) }}

If you have PIL installed, you can use this function to generate an <img> tag with a sample image of the specified size (without PIL, the width/height are ignored and you get a large sample image)

{{ url(*args, **kwargs) }}

Ignores all arguments and returns '#'.

CleverCSS

Breakdown also supports automatic CleverCSS parsing. If the file foo.css is requested and not found, breakdown will then look for a matching foo.clevercss and compile it to vanilla css on the fly.

Advanced

Command line options:

-h, --help

show this help message and exit

-p PORT, --port=PORT

run server on an alternate port (default is 5000)

-m, --media

treat MEDIA_URL as STATIC_URL in templates

-v, --version

display the version number and exit

-c DIR, --context_dir_name=DIR

set the directory name for context object files (default is context)