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 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
@mixindirective in the page
Mixins are folders with an
.esmixin extension that are stored within ~/Library/Application Support/Espresso/Mixins/ (for globally shared mixins) or the Mixins folder inside the #.Espresso container of a particular project.
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:
If your mixin.html file contains
<body> tags, their contents will be automatically appended to the
<body> tag in the final document.
This is also useful for include-style mixins (for instance, to include a global stylesheet).
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
<!-- @section body -->, then content in your document that is not explicitly assigned to a section will be automatically used to populate
@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).
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
<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.
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:
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>