Creating Custom Templates

Boss templates are extremely easy to write. A basic template consists of the following:

  • A boss.json config file
  • One or more files/directories to copy for new projects

Boss doesn’t care what the contents of template files are, as long as it is a readable file. The following is an example python template:

-> python
    `----> @module@/
            `----> @module@.py

    `----> setup.py
    `----> setup.cfg
    `----> README
    `----> LICENSE
    `----> boss.yml

In this example, ‘@module@’ is a variable defined in the ‘boss.yml’ config for this template. When calling ‘boss create -t local:python’ Boss will ask the user to supply a value for ‘@module@’, and then when files/directories are copied that value will be replace at every occurrence of ‘@module@’ both in file/directory names as well as file contents.

Boss Template Configuration Files

Currently Boss only supports a ‘boss.json’ or boss.yml configuration file which is in the JSON or Yaml format respectively. The following is an example Yaml configuration file:

variables:
    version: Version
    module: Python Module Name
    class_prefix: Python Class Prefix
    project: Project Name
    description: Project Description
    creator: Project Creator
    email: Project Creator Email
    url: Project URL
    license: Project License

external_files:
    .gitignore: https://raw.github.com/github/gitignore/master/Python.gitignore
    LICENSE: https://raw.github.com/datafolklabs/license/master/@license@

The ‘variables’ setting is a list of lists. The first item in a list is the variable that is set, and the second is the question as presented to the user for input.

The ‘external_files’ is also a list of lists, and is optional. These are files that are pulled down externally. The first item in an external file definition is the destination path where that file should be saved to. The second is the remote URL to pull the contents from. In the above example we use external files to pull down a current .gitignore file from Github, as well as a LICENSE file for the given license if it exists.

Working with Variables

Boss treats all variables as strings. Therefore, it supports strings operations during the replacement process. For example, if I had a variable of ‘foo’, then in my templates I would reference that variable as ‘@foo@’. If the value of ‘@foo@’ were ‘bar’ for example, I could do things like:

  • @foo.capitalize@ => Bar
  • @foo.upper@ => BAR
  • @foo.lower@ => bar
  • @foo.title@ = Bar

These simple string operations are commonly used throughout templates. That said, don’t get carried away ... Boss doesn’t intend to be a robust templating language, but rather a facility to easily build and copy templates for new projects.

Delimiter

The default delimiter is ‘@’. In some cases, this might not work for your template. You can change this in your boss.yml or boss.json config:

delimiter: '%'