Wagon site templates allow you to create new wagon sites with a predefined set of files in order to expedite the development of new sites.
Built-in templates
Wagon comes with several built-in site templates. You can get a list of the existing templates using the wagon list_templates
command. The following built-in templates ship with Wagon.
Name | Description |
---|---|
blank | this is the default template. It consists only of an index page and a 404 page. No javascripts, stylesheets, or other assets are included. |
bootstrap2 | a minimal site including all assets necessary for Twitter Bootstrap v2.3.2 and Font Awesome 3.2.1. |
bootstrap3 | a minimal site including all assets necessary for Twitter Bootstrap v3.0.0 |
foundation | a minimal site including all assets necessary for Zurb Foundation v4.3.2 |
You make use of templates by running wagon init
with the --template
or -t
option, like so:
$ wagon init my_first_site --template=bootstrap2
or
$ wagon init my_first_site -t bootstrap2
Custom templates
Wagon version 1.4 and higher also supports creating your own site templates.
To start, create a directory to store your templates in. For this example, we will use the directory ~/wagon_generators
.
$ mkdir ~/wagon_generators
Next, we need to create a sub-directory that will hold our template. This sub-directory will simply be a collection of files to be created in the root directory of the wagon site when this template is used. We could create each of these files by hand, but to save time, this example will use a new, blank Wagon site as the base.
$ cd ~/wagon_generators
$ wagon init my_template
...
$ Do you prefer HAML templates ? no
...
The only thing left to make the my_template
directory into a template is to create a a new file, ~/wagon_generators/my_template.rb
, with the following contents.
class MyTemplate < Locomotive::Wagon::Generators::Site::Base
def self.source_root
File.join(File.dirname(__FILE__), 'my_template')
end
end
Locomotive::Wagon::Generators::Site.register(:my_template, MyTemplate, %{
A simple example of a site generator.
})
The new site template can now be used by running wagon commands with the --lib
option.
$ wagon list_templates --lib=~/wagon_generators/my_template.rb
blank - A blank LocomotiveCMS site with the minimal files.
bootstrap2 - A LocomotiveCMS site with Twitter Bootstrap (v2.3.2) and Font Awesome (v3.2.1).
bootstrap3 - A LocomotiveCMS site powered by Twitter bootstrap (v3.0.0).
foundation - A LocomotiveCMS site powered by Foundation (v4.3.2).
unzip - Unzip a local or remote (http, https, ftp) zipped LocomotiveCMS site.
my_template - A simple example of a site generator.
$ cd ~
$ wagon init new_site -t my_template --lib=~/wagon_generators/my_template.rb
Special Features
The instructions above show you how to create a collection of files to serve as a Wagon site tempalte. However, there are several other special features worth noting.
Empty directories
As you may have noticed, empty directories in a site template are not recreated in sites using the template. To force an empty directory to be created, include an empty file named .empty_directory
in the directory. So, for the site template we started above, we might want to add several .empty_directory
files, as shown below.
cd ~/wagon_generators/my_template
touch public/fonts/.empty_directory
touch public/images/.empty_directory
touch public/samples/.empty_directory
touch public/stylesheets/.empty_directory
touch public/javascripts/.empty_directory
touch app/views/snippets/.empty_directory
touch app/content_types/.empty_directory
touch data/.empty_directory
Thor templates
Since the wagon generate
command is powered by Thor, templates can make use of Thor's ERB templates. To demonstrate this ability, let's add a Thor template to our site template. Open ~/wagon_generators/my_template/Gemfile
source 'https://rubygems.org'
# ruby '1.9.3'
gem 'locomotivecms_wagon', '1.5.1'
group :development do
# Mac OS X
gem 'rb-fsevent', '~> 0.9.1', require: RUBY_PLATFORM.include?('darwin') && 'rb-fsevent'
# Unix
gem 'therubyracer', require: 'v8', platforms: :ruby
gem 'rb-inotify', '~> 0.9', require: RUBY_PLATFORM.include?('linux') && 'rb-inotify'
# Windows
gem 'wdm', '>= 0.1.0', require: RUBY_PLATFORM =~ /mswin|mingw/i && 'wdm'
end
group :misc do
# Add your extra gems here
# gem 'susy', require: 'susy'
# gem 'redcarpet', require: 'redcarpet'
end
In the future, surely the locomotive_wagon gem will eventually be updated again, but this Gemfile locks it at version 1.5.1. One solution might be to remove the version altogether.
gem 'locomotivecms_wagon', '1.5.1'
Just to try out Thor templates, let's change the Gemfile to lock Wagon at whatever version of Wagon was used to create a new site. Start by adding the tt
(Thor Template) extension to the file.
$ mv Gemfile Gemfile.tt
Then change the the line to be like the one below.
Let's change it so that the Gemfile will use whatever version of Wagon was used when the wagon site using this template was created.
gem 'locomotivecms_wagon', '<%= config[:version] -%>'
config
is made available to templates by Locomotive::Generators::Wagon::Site::Base
, the class that our MyTemplate
generator extends. By default, it has two values:
config[:version]
: the version of Wagon currently by usedconfig[:name]
: the name of the Wagon site as passed to theinit
command
Custom prompts
The final special feature this guides will cover is the ability to prompt for input when running wagon init
and then use that input in a site template.
For example, imagine you would like to pre-populate config/site.yml
with the desired locales for the site. To start, add a prompt asking what locales should be used to my_template.rb
. Insert the following method into the MyTemplate
class in my_template.rb
.
def copy_sources
@locales = ask('What locales will this site use?')
super
end
#copy_sources
is called when wagon init
copies all the files from a site template directory to the new wagon site's destination directory . In this case, we would like to ask the user what locales the site will have before copying the files. To do this, we make use of Thor's built-in Thor::Shell::Basic#ask
to prompt the user for locales and then store the input in an instance variable.
This instance variable can be accessed in Thor templates. Rename site.yml
to site.yml.tt
and change the locales line to read as follows.
locales: [<%= @locales %>]
Now, when creating a new site with this site template, we will be prompted for what locales to use.
$ wagon init another\_site -t my\_template --lib=~/wagon\_generators/my_template.rb
What locales will this site use? en, fr
...
And if you look at the newly generated another_site/config/site.yml
, you should see the following line:
locales: [en, fr]
Great! We were able to use a custom prompt to gather input from the wagon init
command and insert it into our created site.
Beyond
This guide has covered using site templates and the basics of creating your own site templates, but we've only just scratched the surface of what you can do with site templates.
If you are looking for further guidance when making your own templates, be sure to take a look at the template directories and ruby classes for the built-in site templates.
And since generators use the Thor gem, the Thor Documentation and Thor Wiki are also invaluable sources of information.