I got turned on to Yeoman back at the Modern Mobile Conference back in September.
In October, I started working with Yeoman to build up a small mobile Bootstrap based site of a dozen pages or so. My objective is to use a team of students to help with development, keep the app as browser-based and make it work on mobile devices.
The plan is to integrate some simple features. These include:
- leaflet
- leaflet-hash
- leaflet-locatecontrol
- touchSwipe
- handlebars
Here's some notes on how this project is progressing.
First, working with Yeoman, Bower and Grunt is pretty great. There are a lot of nice starter tutorials out there that will help you get nodejs, yeoman and yeoman generators installed. Google is your friend in getting started.
Beyond the initial scaffolding of the app, I started to run into challenges when I wanted to include things like include Leafletjs or figure out how to load my work into a git repo so I could track what I was doing. The basic tutorials stop before you get here. Hopefully, this article will help someone else who gets stuck.
Challenge 0 - Uh, Bootstrap isn't working?
The model here is that you have to add script tags to pull in bower_components. So, you'll have to add the css and js files you want included.
Challenge 1 - How and what do I put in git?
Turns out this is dead easy. After you scaffold a web app with Yeoman, you can push most of the scaffolding into git. Note the .gitignore file. That is intended to keep all the dependency files from being pushed into git; you aren't going to need them in the repo.
Add the contents of the directory. The .gitignore will leave out what you don't need. It's just not obvious when watching the tutorials.
When you clone your work back onto another machine, you're going to run npm install & bower installwhich will go out and grab all those dependency files for you.
Challenge 2 - How do I add Leafletjs to my project?
Turns out this is pretty easy too. I found the answer on the Bower page. Bower is a package manager. Bower uses the file bower.json to track the packages it is managing in your project. Leaflet is the package we want, so we use bower to install the package and the flag --save to add this to the bower.json file. Thus:
bower install leaflet --save
Note: There's still a problem to solve. Bower will install leaflet from git. However, what comes back does not have a leaflet.js file in the dist/ directory. This is a known issue. To build leaflet.js, you'll need to go back to the leaflet download page. You may need to install jake, npm install -g jake and npm install. There's probably a better way to do this, but I haven't found it yet.
Challenge 3 - How do I add a Leafletjs plugin to my project?
Similar type of problem. I know where the src is located on github, but how and what do I add to my proejct? Bower again. In reading the Bower pages, you'll see that we can use bower search to look for javascript packages. When I searched for leaflet-hash, it didn't exist. Hmm. Turns out you can register a package in Bower:
bower register <my-package-name> <git-endpoint>
So, I registered leaflet-hash and later leaflet-locatecontrol. Then I used Bower to install and save them in my bower.json file and project. Then I commited to git which updated the bower.json file with my recent changes.
Challenge 4 - Grunt won't compile my added packages!
When you get ready to deploy your project, grunt build runs through the code and does its magic. It compresses, minifies, optimizes. So, you end up with a page like map.html. On that page, you've included your leafletjs and plugins in the app/ directory. It was working ok there, but it doesn't show up when grunt build is run.
There's lots of info on grunt, tasks, etc. For my challenge, it was pretty simple. I just needed to modify my Gruntfile.js useminPrep task to inlcude an array of file names. By default, it knew my index.html page, but it didn't know any of the other pages in my project. So I found an similar problem in StackExchange and applied it to my issue. Thus,
this:
html: '<%= yeoman.app %>/index.html',
became this:
html: ['<%= yeoman.app %>/index.html', '<%= yeoman.app %>/map.html'],
Challenge 5 - Boostrap glyphicons won't display!
I spent about four hours fiddling with getting glyphicons to work correctly on a build made via the grunt build command. I read all the issues I could find. Still no luck. Lot's of ideas for work arounds, none of which were easy to install and maintain during a dev cycle. The easiest was to simply use a link href to the CDN version of bootstrap.min.css.
[update - 12/4/13] After researching, modifying the Grunfile.js, I've come to find that there's a webapp-generator bug. It seems that we're pulling in the sass-bootstrap fork. When we compile via grunt build, I can now get all the files and direcotries located, but an edit to the compiled css file does not include the correct path to fonts. It needs to be edited such that url(../) is added to each of the 4 glyphicon paths.
Also, I resolved some problems with leaflet plugins and icons by pulling them out of the concat and minification processes. I was generating errors about setting L.Icon.Path. That was fixed with some paths being added to Gruntfile copy task.
That's it for now. Next to work with is using Modernizr, yepnope and touchSwipe to determine if I've got a touch enabled browser and then figure out what makes sense for gesture use in our app.