Labs/Bespin/ProjectTemplates

Project Templates

What are these for?

When a new user signs up, they automatically get a sample project and BespinSettings. New projects are created for these, and then a "project template" is installed (using the Project.install_template method).

For custom Bespin installations, you can also set up your own project templates.

The Template Path

Templates are found via a search path which, by default, includes the location of Bespin's default templates. The template path is set in a variable config.c.template_path. This is a list, and you can append more paths to it.

What do templates look like?

A template is a directory of files. All of the files and directories inside of that directory will be installed into the target project. The root of the template will be chopped off when determining the destination filename. For example, if you have a template like this:

foo/
    README-{project}.txt
    bar/
        new.js

The README file will end up in the top level directory of the project it's installed into.

Dynamic values

In the example above, you undoubtedly noticed the rather odd name of the README file: README-{project}.txt. When installing a template, the Python server uses the JSON Template template engine on both the filenames and the file contents.

So, if this template is installed into a project called "helloworld", you would see README-helloworld.txt at the top level of the project.

By default, the following variables are available:

project

the project name

username

the username of the project's owner

filename

the name of the file that is being generated

You can pass in additional values. Any undefined variables referenced in the template are simply replaced with an empty string.

Web API

POST/project/template/[projectname]/ 

the body of the POST is just the name of the template to install (the template must already be available on the server). This will install the template into the project, creating the project if necessary. It will not delete the project, so you can install multiple templates into a single project.

Python API

On Project, there is this method:

   def install_template(self, template="template", other_vars=None):
       """Installs a set of template files into a new project.
       
       The template directory will be found by searching 
       config.c.template_path to find a matching directory name.
       The files inside of that directory will be installed into
       the project, with the common root for the files chopped off.
       
       Additionally, filenames containing { will be treated as JSON Template
       templates and the contents of files will be treated as JSON Template
       templates. This means that the filenames can contain variables
       that are substituted when the template is installed into the
       user's project. The contents of the files can also have variables
       and small amounts of logic.
       
       These JSON Template templates automatically have the following
       variables:
       
       * project: the project name
       * username: the project owner's username
       * filename: the name of the file being generated
       
       You can pass in a dictionary for other_vars and those values 
       will also be available in the templates.
       """