Creating-your-templates.md

Customize SwiftGen templates

This document describes how to make your own templates for SwiftGen, so it can generate code more to your liking and code following your own coding conventions. For in depth documentation of the bundled templates, we refer you to the documentation for each specific template.

Templates files on disk (Search Path priority)

When you invoke SwiftGen, you can specify templates by name or by path.

Using a full path

If you use the --templatePath (or -p) option, you'll need to specify the full path to the template you want to use. This allows you to store your templates anywhere you want and name them anyhow you want, but can become quite annoying to type.

Using a name

When you use the --template (or -t) option, you only specify a template name. SwiftGen then searches a matching template using the following rules (where <subcommand> is one of colors, xcassets, storyboards or strings depending on the subcommand you invoke):

• It searches for a file named <name>.stencil in ~/Library/Application Support/SwiftGen/templates/<subcommand>/, which is supposed to contain your own custom templates for that particular subcommand.
• If it does not find one, it searches for a file named <name>.stencil in <installdir>/share/swiftgen/templates/<subcommand> which contains the templates bundled with SwiftGen for that particular subcommand.

For example swiftgen xcassets -t foo DIR will search for a template named foo.stencil in Application Support, then in /usr/local/share/SwiftGen/templates/xcassets (assuming you installed SwiftGen using Homebrew in /usr/local)

List installed templates

The swiftgen templates list command will list all the installed templates (as YAML output) for each subcommand, both for bundled templates and custom templates.

$ swiftgen templates list
colors:
  custom:
  bundled:
   - swift2
   - swift3
storyboards:
  custom:
   - mytemplate
  bundled:
   - swift2
   - swift3
strings:
  custom:
   - mycustomtemplate
  bundled:
   - flat-swift2
   - flat-swift3
   - structured-swift2
   - structured-swift3
xcassets:
  custom:
  bundled:
   - swift2
   - swift3

Printing a template, creating a new template

You can use the swiftgen templates cat <subcommand> <templatename> command to print the template of that given name for that given subcommand to stdout. e.g. swiftgen templates cat fonts swift3 will print to your terminal the template that would be used if you invoke swiftgen fonts -t swift3 ….

You can use this feature to easily create a new template from an existing one. In particular, the easiest way to create your own templates is to:

• duplicate an existing template by dumping it into a new file like this: swiftgen templates cat fonts swift3 >my-custom-fonts-template.stencil
• then edit the new my-custom-fonts-template.stencil file to make your modifications to that template
• Once you've done this you can then simply use swiftgen fonts -p my-custom-fonts-template.stencil … to use you customized template!

Templates Format, Nodes and Filters

Templates in SwiftGen are based on Stencil, a template engine inspired by Django and Mustache. The syntax of the templates is explained in Stencil's documentation.

Additionally to the tags and filters provided by Stencil, SwiftGen provides some additional ones, documented in the StencilSwiftKit framework.

Templates Contexts

When SwiftGen generates your code, it provides a context (a dictionary) with the variables containing what assets/colors/strings/… the subcommand did detect, to render your Stencil template using those variables.

A full documentation of the produced context for each command can be found in the SwiftGenKit documentation.