Home

This week our challenge was to create a website to document our progress through Fab Academy. Add a sketch and description of a potential final project. And push it all back up to the central repository using Mercurial.

I picked up Notepad++ and Brackets to script in. Brackets has a live preview (that works on every PC but mine) and can import PSDs as a reference. Notepad++ is simple but reliable.

Other useful resources I ran into include:
Kiwipsum.com – for generating filler text to see how your site behaves.
Normalize.css - for dealing with strange browser defaults.
Braceios tags - a super simple hack for building static sites without repeating yourself lots.
Davidwalsh’s parallax - for when normal scrolling just isn’t enough.
W3schools - for referencing anything html / css / javascript related.

There are a whole number of things that I’m unhappy with on the current site but hopefully I’ll get a bit of spare time to address those over the coming weeks.

Big shout out to Bry Ashman and Zenna Fiscella for helping me out with my coding. And to Anna aflalo, Ben Matthes and Jasmin Cheng for hangingout out over the weekend and letting me bounce silly ideas off them.
You guys rock.

Quickly hacking together the guts of my site served as a nice refresher on HTML and CSS but after completing the first revision I was left wanting to make a whole pile of changes. These were either aesthetic HTML changes to the page layout and navigation. I had also done a bit of research into some of the static site generators that exist and was interested in implementing one of them to control the functional changes around the sites back end structure.

To start off I checked out parts of a tutorial that Zenna Fiscella found, covering best practise for setting up dynamic HTML 5 sites.

This gave me a much better understanding of concepts behind some of the structual changes that have been made between HTML4 and 5 and also covered a few cool CSS3 tricks along the way. W3schools also has a great referance for all the new goodies that HTML 5 has brought.

The key changes I made to my site at this point were:
A re-hack of the page layout to actually take advantage of HTML5.
Replacing some of my javascript menu code with CSS transitions.
Introducing javascript driven css selector to choose an appropriate style based on the device viewing the site.

This HTML provided the template that would be placed on top of the static site generator once an appropriate one was selected and implemented.

With the HTML framework built the next challenge was to investigate and implement a static site builder. This isn’t really necessary but Fab Academy seems like the perfect excuse to try out some new work-flows so I started digging around to see what was available. It turns out that there are quite a few static site generators. So the challenge became selecting an appropriate one.

In the end I settled on metalsmith. Its based on node.js as opposed to ruby or pearl so I was optimistically hoping for some level of familiarity between it the the plain old JavaScript that Id been using up till that point. It also pitches its self as being “extremely simple” with easy to use plug-ins to extend functionality.

Metalsmith is built on node.js so the first step was to get all the dependencies installed. Specifically node.js 0.10.36 and npm 2.4.1., both of whom have great documentation to help beginners to get everything installed easily. While stumbling through metalsmiths documentation I came across a ground up tutorial by robin thrift that I used to build the initial framework of what would become me site.

Metalsmith has a simple directory strucutre that it uses to covert supplied content into HTML goodness.

Static content and content that need to be processed is stored in the src folder and combined with templates from the template folder before being output to the build folder.

Out of the box Metalsmith does almost nothing, but has a selection of plug-ins that can extend its functionality.
My site makes use of the following:
Collections allows for grouping of posts based on location or meta-data.
Markdown converts supplied markdown content into html
Templates supplied template files into html for use as page layout.
Permalinks changes the file structure to create nicely nested files for linking.

All of the above plug-ins are important but templates and markdown deserve a special mention. These two do all of the heavy lifting of converting the supplied content and structure into HTML. By using a markup language im able to focus on creating content, like these blog posts, and ony have to pay minimal attention to the formatting by using the markdown syntax. Using a templating language, in my case handlebars, achieves the same thing for the actual page structure. Allowing for the specification of all or part of a page as well as defing where content from the markdown files should be placed.

With all the plug-ins and content in pace it was time to build my site.

The site had been successfully generated but unfortunately this highlighted a slight over-site I had made earlier. All the outputted HTML files were looking for their js or css files as if they were in the same directory as the initial index page and changing the file path on the template files changed it for all of the HTML files. Meaning that either the top level or the lower level link would be broken. Running out of time I came up with an incredibly hacky fix using another meta tag to correct the file path.
<script src="{{depth}}js/init.js"></script>
This allowed all the generated pages to find their javascript css selector code but then a new incantation of the same problem immediately reappeared. The JavaScript looks at the devices screen width and select an appropriate css template to use like so:
media: '(max-width: 736px)', href: 'styles/style-small.css',
So once again CSS would only work for the high level or low level pages but not both. Luckly for me Bry Ashman came to the rescue by pointing out that I could apply the same hack in JavaScript if I passed it the variable from the rendered html pages. Adding this to my html header:
<script type="text/javascript">window.depth="{{depth}}"</script>
and this to my JavaScript:
href: window.depth + 'styles/style-small.css',
resolved the issue and now every page had pretty css. This is pretty far from an ideal fix and i suspect that a better option would be to use the collections and permalinks plug-ins in combo to modify the links dynamicly on output but in the time available I wasn’t able to get them playing nicely to do that. There also probably a much nicer solution that deals with this, presumably common, problem but I have yet to find it. If you have a good idea on how please feel free to let me know.

Retrospectively Metalsmith might not have been the perfect choice, while the javascript similarities were occasionally helpful for troubleshooting, the lack on an active community made finding support hard. There are a limited number of tutorials and both their forums and IRC channels were surprisingly quite, though the latter is potentially just due to my time zone.

This week we were introduced to the exciting world of version control using mercurial. Fab central runs a mercurial server that also doubles as a web server, allowing students to show their progress to the world without having to set up their own server. It also provides a handy place to check out the cool work that pervious years student have done and get inspired. We will be using it for the rest of the course to update our website documenting our progress.

To update my website each week I run some of the following commands:

hg pull download any changes from the repo since we last updated.
hg update add those changes to my working file set.
Add all my updates to my folder.
hg addremove tell mercurial to take note of any new files i’ve added or old ones that have been removed. (its not an awesome idea to upload large file and then removed them as the repositery will still have a copy of it, sitting around taking up space.)
hg commit -m '(a meaningful commit message)' take a snapshot of the changes made and write a short note about what has been changed.
hg push push those changes back to the central repository.

But often someone else has pushed in the time it took me to update everything so…
hg pull pull down a copy of the new changes
hg merge merge my changes and the new changes togeather
hg commit -m 'merged changes' commit the new merged version
hg push push it back up and hope no more changes have arrived.
Mercurial is really good at letting you know what went wrong and how to fix errors. If something funny is going on it will often remind you to do things like merging.

Some of my class mate like to wait till just after i’ve pulled to push their work. Pretty sneaky guys, but im on to you!

I’ve created a new page for my final project where I’ll be putting all of the development that doesn’t fall into the weekly modules. Check out my concept sketch here.