Mixins

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

Mixins allow you to easily share code between different pages of your website.

To include a mixin in a particular page, use the @mixin directive:

<!-- @mixin MyMixin -->

Depending on the mixin, the @mixin directive will do up to two things:

Mix the HTML code in the mixin with the HTML code output of your page
Output a specific code fragment where you use the @mixin directive in the page

You might use a mixin as a template for the pages in your site, to output a common lightbox widget in multiple locations across your site, or to quickly switch between the development version of a Javascript framework and a minified version by changing a single variable. Because mixins support all Dynamo tags (including referencing other mixins), they can easily become building blocks that you share commonly between multiple projects.

Defining mixins

Mixins are folders with an .esmixin extension that are stored within the Mixins folder inside the #.Espresso container of a particular project.

Template mixins

If your mixin contains a file named mixin.html, its contents will be mixed with the document that references it. This is most commonly useful for sharing a template across multiple pages in a site.

There are two ways that mixins mix their contents with the base document:

Head and body tags

If your mixin.html file contains <head> or <body> tags, their contents will be automatically appended to the <head> or <body> tag in the final document.

This is also useful for include-style mixins (for instance, to include a global stylesheet).

@sections

In addition to normal Dynamo directives, mixins support a special @section directive that allows you to define an area whose content will be supplied by the document that includes the mixin.

For instance, if you are using a mixin to define the template for your project you might have something like this inside MyTemplateMixin.esmixin/mixin.html:

<!DOCTYPE html>
<html lang="en">
<head>
	<title><!-- $title --></title>
	
	<!-- @section head -->
</head>
<body>
	<!-- @section body -->
</body>
</html>

Then in a given page on your site (e.g. index.html), you would reference the mixin like this:

<!-- @mixin MyTemplateMixin -->
<!-- $title: Homepage -->

<!-- @section head -->
<meta name="description" content="An awesome index page"/>

<!-- @section body -->
<h1>Welcome to my site</h1>

<p>You are awesome.</p>

Once the document was compiled, it would result in the following HTML:

<!DOCTYPE html>
<html lang="en">
<head>
	<title>Homepage</title>

	<meta name="description" content="An awesome index page"/>
</head>
<body>
	<h1>Welcome to my site</h1>

	<p>You are awesome.</p>
</body>
</html>

If your mixin uses the standardly named , then content in your document that is not explicitly assigned to a section will be automatically used to populate body.

@section directives have no closing tag; they are automatically terminated at the next @section directive, the closing tag for the parent element containing the @section tag, or the end of the file (whichever comes first).

Injection mixins

For mixins that define standalone widgets or similar, you will need to include a file named include.html in your mixin folder. The contents of this file will be output where the mixin is referenced in the parent document.

In this instance, your optional mixin.html file will contain <head> and/or <body> tags to automatically mix the contents of those tags with the parent document's head and body. The mixin.html file will be executed only once, while the include.html file will execute once every time you reference the mixin in the parent document.

For instance, you might have a lightbox mixin that requires specific Javascript and styling. In this case, your MyLightboxMixin.esmixin folder might contain the following:

js/lightbox.js
css/lightbox-styling.css
include.html
mixin.html

The include.html file would look something like this:

<a class="lightbox-trigger" href="<!-- $fullsize -->"><img src="<!-- $thumbnail -->" alt="" /></a>

While the mixin.html file would look like this:

<head>
	<!-- @stylesheet lightbox-styling -->
</head>
<body>
	<!-- @javascript lightbox -->
</body>

Your document, would then define the necessary variables to reference the full size and thumbnail images, and include the mixin like this:

<!DOCTYPE html>
<html lang="en">
<head>
	<title>Lightbox Example!</title>
	<!-- @stylesheet css/styles -->
</head>
<body>
	<h1>Check out this sweet image:</h1>
	
	<!-- $fullsize = images/bigimage.jpg -->
	<!-- $thumbnail = images/thumbnail.jpg -->
	<p><!-- @mixin MyLightboxMixin --></p>
</body>
</html>

Once your site is compiled, the final HTML would look like this:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Lightbox Example!</title>
  <link rel='stylesheet' href='css/styles.css'>

  <link rel='stylesheet' href='global/MyLightboxMixin/css/lightbox-styling.css'>
</head>
<body>
  <h1>Check out this sweet image:</h1>

  <p><a class="lightbox-trigger" href="images/bigimage.jpg"><img src="images/thumbnail.jpg" alt="" /></a></p>

  <script src='global/MyLightboxMixin/js/lightbox.js'></script>
</body>
</html>