Using assemble.io with yeoman.io's webapp Gruntfile
With Effeckt.css I discovered assemble.io, a node-based static site generator for ... well ... assembling HTML files from different parts.
A tool like that was much needed by our department once we switched from an inconvenient clutter of Ant builds, PHP includes, CodeKit and command line calls to our yeoman/grunt setup, so I gave it a try. And I was stunned how easy the set up was and how perfect it fits into the environment we created based upon yeoman's web app generator.
In this short article, I'll show you how you can use assemble.io with Handlebars templates and the basic yeoman.io web app generator Gruntfile.
The Basics
When compiling, assemble.io clutches together bits and pieces from three different resource groups:
- Layouts: The basic layouts, with all the basic HTML setup, navigations, wrappers, and so on.
- Pages: Every page without the clutter around it. Just the "content" of a site
- Partials: Reusable Modules that can be included with different parameters on any of the above. Partials can also include other partials.
The assembling process goes as follows: Every page is included into a layout, with partials completing everything in-between.
Layouts
A basic layout can be like that:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!-- the title from the page -->
<title>{{title}}</title>
</head>
<body>
<!-- Include a nav from partials -->
{{>nav}}
<div class="wrapper">
<!-- The body of the page -->
{{>body}}
</div>
<!-- Another partial -->
{{>footer}}
</body>
</html>
We already included some partials (navigation and footer), as well as some parts we define later in the pages. Either with parameters (title) or with content (body).
Pages
With the whole HTML layout in the layout modules, a page is a lot cleaner. It defines parameters in a sort of setup header, after that there's the content that is included when calling \{\{> body\}\}
---
title: About
---
<h1>About everything</h1>
<p>Lorem Ipsum is not good for content</p>
<ul>
...
</ul>
Easy!
Partials
I guess you get the idea by now... I'll cover the usage of parameters and stuff sometime later. This is all about the grunt setup.
Folder structure
For our websites, those module categories do have separated folders in a template folder in our app directory:
app
|-- templates
|-- layouts
|-- pages
|-- partials
Adding it to yeoman.io's webapp Gruntfile
yeoman.io's webapp setup is the best way to start any web related project. Plus, the generator can be easily adapted to be used with your workflow in particular (I guess this will also be an article for later).
Anyhow: The cool thing with its Gruntfile is, that you not only get compiling and building done, but also have some sort of developing environment, where you can easily access all the files in it's plain source, unminified and as-is. We will now setup grunt for both the building process, as well as the "grunt server" task for your dev environment.
assemble.io setup
First of all: Be sure to install assemble correctly after scaffolding your web app:
yo webapp
npm install --save-dev assemble
Open your Gruntfile.js, and add assemble right after defining the module:
module.exports = function (grunt) {
grunt.loadNpmTasks('assemble');
...
};
With that done, we can do the basic setup for the assemble task. Just add this part anywhere inside the .initConfig scope:
assemble: {
options: {
flatten: true,
layout: 'layout.hbs',
layoutdir: '<%= yeoman.app %>/templates/layouts',
assets: 'dist/images',
partials: ['<%= yeoman.app %>/templates/partials/*.hbs']
},
...
}
Pretty self-explanatory. We'll define the location of layout, partials, and some other stuff which you can ignore for now. Note that partials can be an array of folders, make use of that.
grunt build
Before we'll check on the (oh so sweet) on the fly compiling when spawning a project dependent server, we just check on how to compile this baby when creating a build.
With the setup being complete, just add a line for the "dist" target. This is yeoman's default target for anything building and distribution related.
assemble: {
options: {
flatten: true,
layout: 'layout.hbs',
layoutdir: '<%= yeoman.app %>;/templates/layouts',
assets: 'dist/images',
partials: ['<%= yeoman.app %>;/templates/partials/*.hbs']
},
dist: {
files: {
'<%= yeoman.dist %>;/': ['<%= yeoman.app %>;/templates/pages/*.hbs']
}
}
}
We have defined layouts and partials in the setup, the dist-target tells us where pages are located and where the assembled output should land. It's pretty straightforward: Just put all the pages in <%= yeoman.dist %>/, the output directory of the build process.
Note: This can create some conflicts if you're using the htmlmin task, since it tries for itself to copy everything HTML related from <%= yeoman.app %>/ to <%= yeoman.dist %>/. Just put everything done by assemble into a temporary directory, and let htmlmin (which strangely never worked for me...) fetch the files from there:
assemble: {
options: {
flatten: true,
layout: 'layout.hbs',
layoutdir: '<%= yeoman.app %>/templates/layouts',
assets: 'dist/images',
partials: ['<%= yeoman.app %>/templates/partials/*.hbs']
},
dist: {
files: {
'.tmp': ['<%= yeoman.app %>/templates/pages/*.hbs']
}
}
}
htmlmin: {
dist: {
options: {
},
files: [{
expand: true,
cwd: '.tmp',
src: '*.html',
dest: '<%= yeoman.dist %>'
}]
}
},
Voil&aaucte;, you're done.
grunt server
Now for the fun part: Having it compiled on the fly while changing your source files, and live reload it in your browser.
This part of the yeoman Gruntfile actually got me interested into the scaffolding tool in the first place, since it's a LOT more convenient to have your changes displayed directly after doing them. No matter if it's in Sass, HTML or JavaScript.
To achieve that, grunt creates a TMP directory where it puts all compiled stuff into. The server also points to that directory. So for having our HTML files assembled, just add this line of code to our assemble setup:
assemble: {
...
server: {
files: {
'.tmp/': ['<%= yeoman.app %>/templates/pages/*.hbs']
}
}
}
If you start your server the first time, all pages are compiled and available. If you want to update your server anytime a *.hbs file changes, add the following line to the watch task:
watch: {
...
assemble: {
files: ['<%= yeoman.app %>/templates/layouts/*.hbs',
'<%= yeoman.app %>/templates/pages/*.hbs',
'<%= yeoman.app %>/templates/partials/*.hbs'],
tasks: ['assemble:server']
}
},
...
Which actually just says: If anything changed in our layout/pages/partials folder, execute the assemble task again!
To have the changes displayed without refreshing, tell livereload to have a look at the HTML files compiled into the TMP directory of the server:
watch: {
...
livereload: {
options: {
livereload: LIVERELOAD_PORT
},
files: [
'.tmp/*.html', // Add this
...
]
}
},
And you're done! Enjoy!
Updates
I got some great feedback in the comments. Thank you guys, you're amazing! Here are some issues I forgot to address:
Peter pointed out that with the current setup, usemin won't be able to run through your code and compile scripts and style files. You can either point the useminPrepare task to one of the template or partial files, or you just direct them to the .tmp directory:
useminPrepare: {
options: {
dest: '<%= yeoman.dist %>'
},
html: '.tmp/index.html'
},
Just run useminPrepare after assemble, which I forgot to add anyways. Thanks Sarith for pointing me onto that one!
...
concurrent: {
server: [
'compass',
'jst',
'assemble'
],
dist: [
'compass',
'jst',
'assemble',
'imagemin',
'svgmin'
]
}
...
grunt.registerTask('build', [
'clean:dist',
'concurrent:dist',
'useminPrepare',
'concat',
'cssmin',
'uglify',
'copy:dist',
'usemin'
]);
Thanks again for the great feedback! I really appreciate it!
As Mark Paul pointed out, you need some updates in your usemin configuration, otherwise you won't get any rev updates:
// Performs rewrites based on rev and the useminPrepare configuration
...
usemin: {
options: {
assetsDirs: ['<%= config.dist %>', '<%= config.dist %>/images']
},
html: ['<%= config.dist %>/{,*/}*.html', '.tmp/{,*/}*.html'],
css: ['<%= config.dist %>/styles/{,*/}*.css']
}
...
Thank you for mentioning!
Bottom line
Grunt and yeoman are found their way into our development process rather quickly, and I think assemble.io will also be a part in our development future.
Setting up was rather easy and took me -- including research on how to use this in the first place -- about half an our. Plus, assemble.io solves major issues we faced after switching to yeoman+grunt:
- PHP includes weren't possible anymore, with assemble we can put template parts in separated files again
- With the much cleaner Handlebars syntax it's possible to prepare those modules for a later refining, e.g. to produce TYPO3/Wordpress/Name-your-CMS modules.
If your website deployment is based upon yeoman and/or grunt, you should definitely give it a try.