Saturday, January 19, 2013

Versioned APIs with Express

After reading and watching some of the stuff coming out from Apigee about API Design, I've been convinced that APIs should probably be versioned in the URL using a scheme like this:
http://api.whatever.com/v1/jobs

By the time I realized this the API I had been building with node.js was basically already complete, so I was a little bit sad that I'd have to come up with some complicated versioning scheme.

After a bit of fretting I realized that express can handle this super easy using an interesting feature of the express() instance that it can be mounted to another route using app.use().

This means that your routes don't know which version they are!

Here's your main app file.

app.js file

Then you'll put each version of your API in the routes/ folder named after the version.

routes/v0.js file
Each version of the API can have middleware (such as unique authentication) that only works on that version of the API. One thing that this doesn't cover is unique models per version, but I'll leave that up to you to figure out how to accomplish, because the needs of each app very quite a bit by app. Hope this tip helps!

Tuesday, August 14, 2012

Everything I Know About SVG


Everything I Know About SVGSVG is arguably going to be the main image format of the modern web. I recently wrote an article for Safari Books Online called SVG Icons for New Devices that covers some of the basics of dealing with SVG. This article tries to focus more on the pain points of using SVG in production and it turns out there are many. Read along to see what I’m talking about.

Plain Old <img> Tags

Here’s how you link to your amazing vector image.
<img src="/images/logo.svg">
This is pretty straightforward and should work very well for most of your cases. You can also specifcy width and height this way or in your CSS.

Vector is XML

SVG files are supposed to be human readable, but XML is terrible, so it’s been slow going for me. That being said I have noticed one strange thing about the content of SVG files, notably the fact that there are width and height attributes:
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" width="15px" height="15px" viewBox="0 0 15 15" enable-background="new 0 0 15 15" xml:space="preserve">
Sometimes in Firefox when you scale up SVG images (browser-zoom) you get some weird bluriness. If you change the width and height from px to em this bluriness seems to myseriously dissappear. Because in this case it’s a sqaure 1em and 1em work great. I’m not sure if this is a bug in Firefox or if it’s even still a problem in the newer versions. Your mileage may very.

Basic Icons

It’s pretty easy to use SVG for icons and just make them background images. This is probably your standard use case for SVG anyway.
.icon {
    height: 16px;        
    width: 16px;
    background-size: 16px 16px;
}

.icon-arrow {
    background: url("/images/icon-arrow.svg") no-repeat;
}

<div class="icon icon-arrow"></div>

Relatively Easy EM Icons

EM’s are relative to font-size, so you can easily use them to size your SVG images relative to some text, which can be really helpful in a lot of cases. Here’s an exaple of putting them next to some headings.
h1 {
    font-size: 24px;
}

h2 {
    font-size: 18px;
}

.icon-before {
    background-size: 1em 1em;
    padding-left: 1em;
}

.icon-arrow {
    background: url("/images/icon-arrow.svg") no-repeat;
}

<h1 class="icon-before icon-arrow">Header 1 w/Icon</h1>
<h2 class="icon-before icon-arrow">Header 2 w/Icon</h2>

Fallbacks

If you care about IE8 or Android 2.x or other browsers that don’t support SVG images you can combine some fanciness like this with a simple custom build of modernizr to easily fallback without too much ugliness.
.icon {
    height: 16px;        
    width: 16px;
    background-size: 16px 16px;
    background-repeat: no-repeat;
}

/* only show svg icon */
.svg .icon-arrow {
    background-image: url("/images/icon.svg");
}

/* don't show anything but png */
.no-svg .icon-arrow {
    background-image: url("/images/icon.png");
}    

<div class="icon icon-arrow"></div>
Note: With this approach we do have to wait until modernizr adds our svg or no-svg classes to the pages <body> before the images show up. Other fallback approaches can avoid the wait, but this guarantees the right thing will show up in the right browser.
Another Note: Someone really needs to write a Sass plugin one day to create the PNG images directly from the SVG, so that we don’t have to bug the designer for it.

Data-URIs

Data URI’s are this amazing way to embed binary image content directly into your CSS files. This results in a reduce number of seperate downloads and can improve performance in some situations (hover states, etc).
.icon {
    height: 16px;        
    width: 16px;
    background-size: 16px 16px;
    background-repeat: no-repeat;
}

.icon-arrow {
    background-image: url(data:image/svg+xml;base64,..);
}

<div class="icon icon-arrow"></div>
Compass provides the inline-data() helper to assist with base64ing images and bringing them into your stylesheets. You can also drag and drop your SVG images into the SVG is Rad tool I wrote to get the proper CSS.

Weird Bugs

In some versions of WebKit (Chrome < 18 and Safari < 6) you cannot combine SVG data-URIs and background-repeat: repeat-x. The image turns into a blurry mess! Because of this bug in some cases I had to switch to referencing the SVG from a file and it was fine.

MIME Types

If you try to link to external SVG files for background images and don’t specify the correct mime type they just won’t show up. This happened to us after we switched from base-64 encoded SVGs to linking to files, because the so-called magic mime type detection script in our version of Apache noticed that our SVG files looked like XML and served them up as text/xml.
You can add this to your .htaccess file if Apache is doing the same thing to you (hat tip: this 5 year old article):
AddType image/svg+xml svg svgz
AddEncoding gzip svgz
If you’re on NGINX check out this stackoverflow question about SVG MIME types and NGINX.

Related Research

Other people are doing a lot of interesting things with SVGs at the moment. Here are some topics I don’t know quite enough about at the moment:
  1. Spriting with SVG Images
  2. Styling SVG with CSS
  3. SVG Stacks

Thursday, May 3, 2012

Sass Mixins

I was asked to make some buttons at work. I thought it might be a good idea to play with Sass mixins to generate the buttons. I got really excited about this and tried my hardest to generate the buttons from a single base color. It was fun and hard at the same time. It ended up being kind of crap.

In my earlier post about Sass color palettes I was playing with keeping all my colors in a single file. this way we can keep track of them and easily change them in the future. We won't get lost in slightly difference shades of blue everywhere. It's a good idea.

Not being an expert at color theory, I couldn't have told you how to get from one shade to another with anything other than Sass's built-in lighten() and darken() functions. That quickly got me a really terrible looking button, so I had try more complicated approaches.

I had the original CSS styles to work with already, so I tried to make legitimate guesses as to how to get from say the top of the gradient color to the bottom of the gradient color. I did math around the rgb() and though about adding or subtracting various amounts of red, green, or blue. The gradients weren't too bad, but the borders were tricky, they weren't just darker, they were redder, but only for the orange button.

So then I had the idea to inspect the hue, lightness, and saturation. I could get each colors hsl() codes, I could then figure out how different each part of the button was from the other colors, hopefully finding a way to pick a good base color. This proved a decent approach, and it seemed to work pretty much universally, well you know, it worked out okay for most of the darker colors, but lighter colors presented another problem.

It turns out that the trick is dealing with gray, especially light gray, because all of the sudden all of the supporting colors have to change and where you were once lightening colors, you may have to darken them. A decent measure of grayness was to look at saturation. Once I established grayness I also had to look at lightness before deciding which color text to use.

I spent maybe 1 to 3 hours on this and found it a fairly tedious process. It not something I'd wish on anyone else, but I did learn a bit. What do you think of the results?

Conclusion

This experiment was worthwhile, but we ended up just sass-ifying the webkit-only CSS the designer gave us and hard-coding each button separately. Two different buttons might have different box-shadow lengths or border sizes, not to mention hover states. I'm still glad I learned about how mixins work and that this sort of thing was definitely doable. Like a lot of approaches to design (grids, etc) I think it really takes working with a designer that can see the value in the approach and work closely with you on it from the start. Anyone have suggestions on how it could been done better?

Friday, April 6, 2012

JSConf 2012 Notes






Introduction

JSConf has a pretty great reputation. Node.js, Phonegap and other huge projects were announced in JSConf's past. There are legendary parties and fantastic speakers. This year was no exception. As such, the 250 conference tickets sold out in less than 5 minutes. We dressed up like cowboys, rode a mechanical bull and even had shoot-outs. It was a pretty awesome adventure. 

Themes

I try to look for themes in the talks that I saw to figure out what's going on in the community right now. Other than the cowboy theme there were a couple of ideas I heard repeated more than once:
  1. Experimentation / play leads to great ideas.
  2. Everyone is working really hard to make JS faster.
  3. We need more women/diversity in JS.
  4. Build tools / dependencies let us do cooler things.

My Talk

I gave a quick talk about some things I think are important to the JS community.
  1. Open Source
  2. Respecting Diversity
  3. Helping New People
  4. Startup/DIY Culture
You can see the slides here: JavaScript as a Subculture

While no one mentioned it directly, this popular tweet was in response to my talk: Talk about JS culture: "we hated ie, we hated tables,.. What's the new enemy? Someone answers: the threat of native" good answer @jsconf. I'm famous!

Big Announcements

People look to JSConf for big announcements. There were a few of those. It usually takes a few years though to see which ones actually end up panning out.
  1. Project Bikeshed client/server-side flash -> js converter by UXEBU
  2. Grunt ant/rake for JS, by Ben Alman
  3. Everyone got Mozilla B2G Phones for hacking. Sooo cool.
  4. Joyent's node.js PaaS is being phased out and moved to Nodejitsu.
  5. The Chrome team introduced Source Maps for debugging minified code.

Best Talks

I obviously couldn't see all of the talks, so I may have missed a few things, but here were some of the top talks I saw at least in relation to front-end development, which is what I do at my day job. Many other amazing talks were also given about improving JS Performance in the browser, other programming languages and politics.

Jeff Archibald: AppCache is a Douchebag


Summary: AppCache is not progressive enhancement, it completely changes how the browser handles your site.

This talk laid out basically all of the flaws and awkward parts of using HTML5 AppCache and how to use localStorage, iframes and other hacks to get it to behave properly. He made a separation between "get stuff" sites like blogs and wikipedia, and "do stuff" sites like drawing apps and games. It was really entertaining, but ultimately a depressing talk, because of how hard it is to get the AppCache to work properly :(
  1. http://lanyrd.com/2012/jsconf-us/sqxcz/
  2. http://dl.dropbox.com/u/2501978/appcache-diagram.svg

Remy Sharp: Build Anything


Summary:
Use HTML5's JS APIs to progressively enhance your site.

A good reminder of the latest crop of fairly well supported HTML5/JS APIs. We're already using most of these at oDesk, but some that we are not yet using include the HTML5 Drag'n'Drop API to handle file uploading, HTML5 input types, HTML5 History/PushState API, and EventSource (Server sent events).
  1. http://lanyrd.com/2012/jsconf-us/sqxcb/

Paul Irish: Tools


Summary:
There are a lot of great tools out there to help web development. Embrace these dependencies.

Paul Irish laid out every testing framework, css pre-processor, debug tool, and CI Server you could use to maintain your site. He also talked about source maps and some mobile web tools. He mentioned Jenkins and Travis as decent CI Servers.
  1. http://dl.dropbox.com/u/39519/talks/jsconf-tools/index.html

Jacob Thornton: Brûlons les musées


Summary:
We can make things better by starting over, but we need to have clear specs/tests to make sure our new thing still works the same.

The creator of Twitter Bootstrap and ender.js took us for a journey through Dada-ism and french futurism, finally landing on a quote by a famous futurist which translates to "burn the libraries". Jacob tried doing that with ender.js and it ended up being kind of awesome, but quickly people realized small differences with jQuery made it really hard to use. He took a similar approach at re-writing mustache.js in a project called Hogan, which ended up being really successful, because mustache.js had unit tests that could be used to ensure it was perfectly compatible. His approach ended up being significantly faster than the original and eventually was accepted into the mustache.js core. Super funny talk. Final quote "Burn all the libraries without tests".
  1. http://lanyrd.com/2012/jsconf-us/sqxkg/

New Friends

  1. I briefly talked to Nicole Sullivan, who was nice nice nice and seemed pleased as punch we were doing OOCSS at oDesk. She gave me some tips on grids and HTML5, which I'll share with my teams.
  2. I spoke with @substack who made browserling/testling who said we could get it to work behind our VPN if we opened up an SSH Tunnel somehow.
  3. I spoke with Devrim Yasar from Koding about his in-browser IDE. It's very similar to Cloud9, but it's more friendly to non-js environments. I'd really love to give something like this a try, but it will take some work to tweak our dev infrastructure.
  4. Ben Alman from Bocoup showed me his command-line tool Grunt, which is similar to my odesklint tool. It has built-in jshint, minification, and can run qUnit on the server-side with PhantonJS out-of-the box (almost). Grunt has a plugin architecture and may be a good starting point for future tools. I'm going to try and get the unit testing thing working and integrated with a CI server. :)
  5. I talked to the guys from Twillio, who make a really easy to use API for building SMS sender/receivers. Think user-verification and other use-cases. Fantastic stuff.
  6. John David Dalton had some ideas about how to speed up ES5 shims for things like Array.forEach. Really smart guy!
  7. I had a two total fanboy moments when I got to meet Rebecca Murphey and Remy Sharp, but you know everyone has their favorites. I met a bunch of other cool people too. Yay for talking to people. It can be so hard!

Tuesday, March 20, 2012

Mobile Web Anti-Patterns

I'm trying to capture some common mobile web anti-patterns, so we can learn from the mistakes of others. I found a couple of mobile-optimized sites that were well, not so optimized. Please add to the comments if you've seen some of these or other anti-patterns!

Beware the Landing Page



Contrary to what ABC News had in mind, I was trying to find the website not the app. I may have even clicked on a link from Google News or something, but when I saw this I immediately thought, "nevermind".

Native-only




I clicked a link from my Twitter client to hear a song and what do I get? There's no way to actually listen to the song without downloading the app and presumably searching for it. I don't even know the name of the song, just the artist. Worthless. :(

Where Are You?

 

Use your Google Maps app to look up the Post Office, because there website is too hard to use in a mobile situation. It's a mobile optimized site. It knows where I am. One of the biggest mobile web anti-patterns is asking for information you already have.

Too Small Text
 



There sandwiches are great, but if I can't read what they sell or even zoom-in, what is the point of having a website. Your site may be pretty and small, but it's not optimized for mobile if I'm not able to read anything. In this case the problem was using images instead of CSS3 and web fonts to create its look. Other sites don't let you zoom in at all.


Need Examples...

Phone Numbers as Text
Forgetting Map Links on Addresses
Serving Tablet's the Phone Site
What else?

Monday, March 12, 2012

On Tech Reading & Learning

I recently posted mini-book reviews of tech books. This got me thinking about the worth of books in the digital era for learning new technologies.

Personal E-Book History

When the iPad came out I was working at Rain and they were happy to buy me e-books to help me learn the latest and greatest technology, but I was slow to embrace the digital medium for reading, Mostly I really liked the way holding a book in-front of me felt. After I left Rain and wanted some new tech books and I noticed that O'Reilly regularly offered significant discounts on their e-books. Similarly, the fantastic A Book Apart series offers e-book versions of their mini-books for $8. It quickly became difficult to justify purchasing the paperback version of these books, so I started reading technical e-books pretty much exclusively.

Learning Styles

A great thing about books, both the paper and e varieties,  is that they have fewer distractions than a lot of other modern learning mediums. Think about Twitter. It encourages distraction. You might see 5 interesting links since yesterday. You have no way to read all of them thoroughly. The topics are wide ranging and the content decent, but you also want to stay up with the latest posts. Each of those links may have comments and a sidebar full of interesting stuff. It's not a focused experience. Books offer the ability to dive into something a little deeper and stay focused on them a little longer.
 Portability

Moving to e-books I found that I could read books wherever I went. I read most of CSS3 for Web Designers on my iPhone while my wife and I were shopping at Old Navy. Suddenly the structured learning experience that books provide was completely portable.

Lately, I've been doing a lot of reading at the gym as I run on the treadmill. Normal tech books just don't work well in this environment, because they're either too big or the pages don't stay open. E-books on the other hand are perfect. Being able to read a book at the gym helps me stay focused and not think about the treadmill moving under my feet, so I read a lot and get fit while I'm doing it!

Negatives 

In this age of digital learning are books still the ideal way to learn? I'll just lay out some of their obvious downsides.

Technical books are inherently static. You can't interact with them physically. They don't update automatically. They're essentially out of date the day they're published.

They're one sided. Web discussions and forums provide many viewpoints, because anyone can comment. A book may have one or two preset ways of looking at things, but it can hardly be expected to cover all of them.

Books can be really long. They must think they're really important for technical books to venture into the 800 page range (actually the post-120 range is pretty much enough for me). I don't have a huge attention span. While books encourage focus, they can only hold that focus for so long. It's hard to wade through all of the content of the multi-hundred page book.


Book I Like Best

While I'm really good at looking up information on the Internet. I don't always know what I should be looking up. For all of their former glory books with titles like Bible, Definitive Guide and Cookbook  are losing the battle for my attention span. In this I'll much more likely hit up the MDN or StackOverflow than pull out of a paper-back guide when I'm in the middle of a project. Despite their waning appeal there are still books out there that I value greatly.


Books that appeal to me are short.
Books that appeal to me are specific.
Books that appeal to me introduce me to new concepts.
Books that appeal to me often use color to make them clearer.

As I read books that meet these criteria I'm able to learn something new wherever I am and then when I get back to a computer somewhere I know what terms I want to use in my search for more about the topic. These books open my mind up to a new concept or idea. The practical knowledge of how to apply that idea to my specific situation is something I'd probably much rather find online where it will be up-to-date, littered with helpful comments, and checked out by the community at large.



Friday, March 9, 2012

Short Tech Book Reviews

Inspired by this thread on Google+  https://plus.google.com/u/0/116910304844117268718/posts/c3A4wgSAgx4 I decided to put together a bunch of short book reviews of tech books I've read recently.


Introducing HTML5
Great overview of new tags and JS APIs w/some good examples and demos.

HTML5 For Web Designers Loved it
Essential, short, colorful guide to HTML5.

Canvas Pocket Reference
It's like the MDN for when you don't have a computer.

Developing with Web Standards
A bit long, but still it has great chapters on accessibility, CSS, and web standards.

JavaScript: The Good Parts Loved it
Essential, concise, opinionated guide to JavaScript. Covers regexes, functions, objects, etc.

JavaScript Patterns Loved it
Every JS developer should read this book. It's a fantastic review of types, patterns and best practices.  Personally, I prefer the NPM Coding Standards for my server side JS, but this book is still essential.

CSS3 For Web Designers [e-book] Loved it
Read the entire thing on my iPhone. Great, short read. Extremely useful. Totally sold me on rgba().

Mobile First [e-book]
Decent essay on why mobile is becoming more and more important. Best given to someone who's not already steeped in mobile.

Supercharged JavaScript Graphics [e-book]
Stupid title, but plenty of interesting tidbits. Wished it were shorter and only covered Canvas.

JavaScript Web Applications [e-book] Loved it
The best book on web app fundamentals (w/backbone.js, spine, etc.) Covers MVC, HTML5 drag & drop and other APIs. Read it mostly at the gym and on airplanes.

Big Data Glossary [e-book]
Would be more useful as a PDF or even better a wiki.

  
Secrets of the JavaScript Ninja [e-book]
Lots of crazy stuff about prototypes, testing, etc. Been in progress since like 2009 and it's not finished, so we get updates every couple of weeks.

Android in Action [e-book]
Too long.

Hardboiled Web Design [e-book] Loved it
I wish I would have paid to get a hard copy of this, because it's beautiful. Great essay on why we should build cool websites now with some killer examples.



Hello Android
Perfect for Android beginners who want the basics. 

MongoDB: The Definitive Guide [e-book] 
Awesome guide for anyone doing anything with Mongo

Tapworthy [e-book] Loved it
Essential mobile UX & design. 

Recipes with Backbone [e-book]
A ton of great examples about design patterns and testing backbone apps.

50 Tips & Tricks for MongoDB Developers [e-book] Loved it
Essential MongoDB tips for n00bs like me.
 
Learning the iOS 4 SDK for JavaScript Programmers [e-book]
Basically worthless if you've read a beginner tutorial on using XCode. Used it once or twice as a reference for splitting strings into arrays.

Getting Started with GEO, CouchDB and Node.js [e-book]
I now know a little bit about GeoJSON and CouchDB. Kind of weird. Kind of cool. Don't know.

High Performance JavaScript [e-book]
Informative. Don't forget to strike a balance between performance, readability, and maintainability.

Responsive Web Design [e-book] 
Pretty nearly essential book about how the web is changing and how to react to it.