Generators

Please note: generators are a beta feature! Their usage, API, and features may change at any time.

A generator is a special type of mixin that explicitly defines how Dynamo should process a particular folder. This includes defining what files are copied into the built tree, what their filenames are, and generating listing pages (e.g. for blogs or newsfeeds).

Enabling generators

To process a particular folder using a generator, create a file named _mixins.json within the folder with the following contents:

{
	"generator": "MixinName"
}

Configuration variables

To configure a mixin, add a "config" dictionary to your _mixins.json file:

{
	"generator": "EspressoBlog",
	"config": {
		"baseRemoteURL": "http://macrabbit.com/blog/",

		"postsPerPage": 10,
		"otherCustomVariables": "here"
	}
}

The baseRemoteURL variable is a standard variable used by Dynamo when generating @paths within resources that need full URLs (like RSS feeds).

Any other variables within the config dictionary will depend on the configuration variables offered by the mixin; refer to the documentation for the particular mixin that you are using for information.

Iterator markup

In addition to standard Dynamo directives, files processed by generators also have access to the @iterate directive:

<!-- @iterate NAME -->
	<!-- @contents -->
<!-- @end iterate -->

The contents of the @iterate directive will be output once for every file included within the iterator. The <!-- @contents --> variable is a special variable that will automatically output the contents of the file's "body" @section (if no sections are defined, this is the entire contents of the file). Within the @iterate section, the variables assigned to the file will also be available.

For instance, if you are using a generator to create a blog, you might have a folder full of Markdown files for your blog posts. Here is an example post file:

<!-- $title: I love Christmas -->
<!-- $date:  2014-12-25 -->

I <3 CHRISTMAS SO MUCH.

When the generator runs, it looks for a template for your listing page and finds this file (how the template is located will vary depending on the generator):

<!-- @mixin BlogTemplate -->

<!-- @iterate posts -->
<div class="post">
	<h2><!-- $title | (untitled) --></h2>
	
	<div class="entry">
		<!-- @contents -->
	</div>
</div>
<!-- @if $date -->
<p class="metadata">written on <!-- $dateString --></p>
<!-- @end if -->
<!-- @end iterate -->

The code within the @iterate directive is output for every file, so for the example file above the final markup would look like this:

<div class="post">
	<h2>I love Christmas</h2>

	<div class="entry">
		<p>I <3 CHRISTMAS SO MUCH.</p>
	</div>
	<p class="metadata">written on 2014-12-25</p>
</div>

Depending on the generator, you might also have variables available for handling pagination, outputting nicely formatted dates, permalinks for the listed files, etc.

Authoring generators

To create a new generator mixin, add a generator.js file to your mixin folder. Within generator.js, you will be provided with a root-level generator object you can use to create the logic for your mixin. All generators require you to define this function:

generator.applyToOutputNode = function(outputFolderNode, inputFolderNode) {
	// Generator logic here
	// Return true or false
};

The outputFolderNode parameter will be the OutputFolderNode representing the output of your generator and the inputFolderNode will be an InputFolderNode providing you access to the folder being processed by the generator.

To access the variables defined in the config dictionary, you can use the generator.config object. For instance, the example code above would result in the following being true: generator.config.postsPerPage == 10.

You can find details about the properties and methods available to the generator script in the Generator API.