The Particle Lab

Reserve your username

Thu, 10 Mar 2011 00:00:00 +0000

Several web application have launched recently with an invite system where you not only give them an email address to notify you but also reserve your username. Some even go a little further and ask you to connect with Facebook, Twitter etc. The latest one to do so is connect.me, which I signed up for when I had heard about it.

This triggered a brief discussion with a friend about this:

Don't know what connect.me really is, but I'm reserving my username now! http://cxt.me/sKQC8g #connectme
— Marc Roberts (@marcroberts) March 10, 2011

@marcroberts Why?
— Justin Stach (@juter) March 10, 2011

@juter cos I'm a web app whore, and there are other 'marcroberts' out there. So on the off chance it takes off I want that to be me
— Marc Roberts (@marcroberts) March 10, 2011

@marcroberts And you're happy to give them access to your Facebook/Twitter account based on that? Seems a little one-sided to me.
— Justin Stach (@juter) March 10, 2011

@juter it can have access to twitter for now, if it does anything nefarious its gone though. Probably need to explain more via other means
— Marc Roberts (@marcroberts) March 10, 2011

This discussion couldn't really continue on Twitter so has spawned this post.

I am lucky in that my full name is not that common, however I have not been able to get my preferred username of 'marcroberts' on both Facebook and Flickr. This has lead me to try to register with new web application early in order to secure my username, and why I described myself as a "web app whore" (I've also been an active member of Web Apps Stack Exchange site from conception, through its private beta to now so please don't interpret 'whore' as a bad thing!).

But it's not just about reserving a username, here at Neutron Creations we know the pains of launching a web app and so I like to encourage others. If this means signing up my email address, connecting with twitter or facebook then I'm ok with that assuming they don't do anything unwanted. Now obviously I can't know in advance whether they will, and I guess that's a risk I'm willing to take to help and support fellow web application developers.

As long as you haven't given your Twitter/Facebook password to them (and you shouldn't as OAuth should be used for both) you can remove that app from your Facebook and Twitter accounts easily and prevent any further access to your account. Of course this won't remove any data the app has retained, the app itself should provide a way to remove this data or delete/remove your account. There are also term of use with the Twitter/Facebook APIs which specify data retention rules that the app should honour.

There is one golden rule that all web apps that have connections to Facebook/Twitter should never EVER break, they should never post from your account without your explicit permission. Now my first tweet in the conversation may seem like an 'auto-tweet', and in fact if you search twitter for #connectme it seems like connect.me could be breaking this rule, however this was a purely optional step in the signup process (although heavily encouraged) and the text was editable (I did alter my tweet from the standard text).

What are you thoughts on connect.me and this trend of reserving usernames, or encouraging connections with social networks? Drop a comment below or give me a mention on twitter.

More about connect.me

Good API Documentation

Mon, 07 Feb 2011 00:00:00 +0000

So you're a developer (you're not a developer? then maybe this post isn't for you, but feel free to read on), and as with most developers you spend a lot of your time looking up things on Google, Stack Overflow or various API documentation (API docs).

The quicker we can find the information we need in these API docs, the quicker we can build the next game-changing web app. So what makes good API docs? Read on and I'll tell you.

We've all been there; you're "in the zone", just written loads of totally awesome code but can't remember the parameters for a function you need to use. No problem, you bring up Google, enter the name of the function (and maybe the language you're using or something else to get a better result, you know the drill) and BAM the top result sounds perfect. However it's not, the information is out of date and of course you don't find this out until you actual test your code some time later and it takes you hours to track it down to this one bad source of information.

So let's start at the beginning.

Accurate & Up to date

This is the most important aspect of any API docs and thankfully most producers also realise this and do their best to ensure theirs stay up to date. The best of these are any that are built automatically from the API source; javadoc and rdoc, for Java and Ruby respectively, are great examples.

What about maintaining API docs for multiple versions? Well, either have the complete set of docs for each version available separately like the Java API docs (1.4.2 / 1.5.0 ) or show clearly which version(s) a particular page/function/method applies to, check out the documentation for the jQuery .live() function.

Clear, concise and well structured

Having accurate and up to date documentation is next to useless if developers can't find anything. Unless the entire API docs take up barely more than one screen (exactly what 'one screen' or 'the fold' is can be saved for another time) there has to be a good excuse to not have a search function. Search has its place but some people prefer to navigate to what they're looking for so the API docs need to be very well organised, with a clear hierarchical system if necessary. Both of these need to be consistent, if something can be found via the search system it really should be able to be navigated to also, and vice versa.

There are some great examples of this all around the web; the latest jQuery API site is excellent, as is APIdock (which gets bonus points for also having archives of every past version) and the vzaar API docs.

Examples

Being well structured is all well and good if you know what you're looking for but for first time use the best place to start is with a tutorial or examples. Many times I have found that just looking over an example can be far more useful than pouring over pages and pages of documentation. It's also good to see a mixture of examples, ideally at least one simple example and a more complicated one.

Open source projects are often full of good examples in the documentation. There's no better way to encourage developers to use (and potentially help develop in future) your latest open source project than to provide them with a plethora of examples. Here are a few I used recently: Authlogic, Whenever and Cache Money

Discussion

Examples are great, but it's not feasible to come up with every possible use for the API. Why not let the developers do this, provide them with a great discussion environment; forums, mailing lists, IRC etc. This will also reflect well for prospective developers who will see an active community as a positive thing.

The PHP API docs are a great example of this, see the page for the strpos() function for example. Facebook has been making great progress on its API docs lately, but before that the best place to get information was in their developer forums.

Sandbox & Playground

For very large APIs its helpful to have a developer area where you can try out API calls with different inputs and see their outputs. Flickr have really nailed this with their API Explorer where you can try out any of their API with full debug output.

Going one step further, it would be really helpful to have access to a sandboxed version of the API. This allows creation of data that is completely separate and isolated from the live data but still operates in the same manner. For some application this is essential, particularly when developing with financial transactions. Luckily PayPal have a full sandbox environment where you can create accounts, balances, card and bank account all that respond to the public API.

Anything else?

I'd love to hear what else you think good API documentation needs and your opinions on any great or terrible API docs out

there, drop me a comment below or contact me on twitter.

Building a Custom HTML5 Audio Player with jQuery

Thu, 02 Sep 2010 00:00:00 +0100

We recently built an HTML5 audio player for Tim Van Damme's The Box, a new podcast where he interviews people who make cool stuff. Tim wanted an HTML5 audio player on the site, and we put together some jQuery to hook up the player interface he designed. In this article we'll run through the code to explain how it works, covering a few caveats along the way.

Here's the player interface, and the markup for it.

<p class="player">
  <span id="playtoggle" />
  <span id="gutter">
    <span id="loading" />
    <span id="handle" class="ui-slider-handle" />
  </span>
  <span id="timeleft" />
</p>

As you can see, we have a few span elements for each component of the interface:

playtoggle is the play/pause toggle button.
gutter is the timeline track
loading is the bar indicating the loading or buffering progress
handle is the circular element that serves as the playhead, indicating current position in the audio file, and also acting as a drag handle to move to a different point of the audio
timeleft is the play time remaining, in minutes and seconds

We won't cover the CSS for the player here, but if you want to see how it's styled you can inspect the styles on the live site.

We're going to use jQuery to detect support for HTML5 audio, and if it's supported, we'll insert the audio player markup and the audio tag itself. This means that browsers that don't have HTML5 audio support won't see an audio player interface they can't use. You could optionally fall back to a Flash based player, but as Tim is already providing a direct link to the MP3 file elsewhere on the page, the audio player is seen as progressive experience enrichment here.

if(!!document.createElement('audio').canPlayType) {

  var player = '<p class="player"> ... </p>\
    <audio>\
      <source src="/path/to/episode1.ogg" type="audio/ogg"></source>\
      <source src="/path/to/episode1.mp3" type="audio/mpeg"></source>\
      <source src="/path/to/episode1.wav" type="audio/x-wav"></source>\
    </audio>';

  $(player).insertAfter("#listen .photo");

}

The detection code on line 1 is taken from a guide to feature detection on the superb Dive Into HTML5 site. If support is detected, we go right ahead and insert the player code (abridged at the "..." in this code), and the audio tag.

Your audio tag should contain three source formats. The first is OGG Audio which is an open standard, supported by Firefox and Chrome. The second is our old friend MPEG-1 layer 3 (MP3) which is a commercial proprietary format supported by Safari. The third is a plain old WAVE file, which is what Opera wants to hear. Browsers will attempt to use sources in markup order, so for example Safari would fail to read the OGG format source, and use the MP3 source instead, while Opera will fail on the first two sources and use the third WAVE source.

Now we need to start adding functionality to our player:

audio = $('.player audio').get(0);
loadingIndicator = $('.player #loading');
positionIndicator = $('.player #handle');
timeleft = $('.player #timeleft');

if ((audio.buffered != undefined) && (audio.buffered.length != 0)) {
  $(audio).bind('progress', function() {
    var loaded = parseInt(((audio.buffered.end(0) / audio.duration) * 100), 10);
    loadingIndicator.css({width: loaded + '%'});
  });
}
else {
  loadingIndicator.remove();
}

We first save variable references to several key elements of our player so that we can refer to them quickly without querying the DOM each time.

We then look for support of the buffered property on our audio tag. This should contain information about how much of the audio file has been buffered. At the time of writing, Firefox doesn't provide the buffered property at all, while Opera has the property but doesn't put anything in it. For browsers that do (and for future versions of Firefox and Opera that have full support for the buffered property), we set up an event handler for the 'progress' event (fired as loading progress is made). As the audio file loads, we calculate the amount of the file that has been loaded as a percentage, and then use this value for the width of our loading indicator. If buffered progress support isn't available, we can simply remove the redundant loading indicator element from the DOM.

Now we'll write an event handler for the 'timeupdate' event, which is fired whenever the current play time is updated, either as we're playing the audio normally, or when we seek to a new position within the audio file.

$(audio).bind('timeupdate', function() {
		
  var rem = parseInt(audio.duration - audio.currentTime, 10),
  pos = (audio.currentTime / audio.duration) * 100,
  mins = Math.floor(rem/60,10),
  secs = rem - mins*60;
			
  timeleft.text('-' + mins + ':' + (secs > 9 ? secs : '0' + secs));
  if (!manualSeek) { positionIndicator.css({left: pos + '%'}); }
  if (!loaded) {
    loaded = true;
				
    $('.player #gutter').slider({
      value: 0,
      step: 0.01,
      orientation: "horizontal",
      range: "min",
      max: audio.duration,
      animate: true,					
      slide: function() {							
        manualSeek = true;
      },
      stop:function(e,ui) {
        manualSeek = false;					
        audio.currentTime = ui.value;
      }
    });
  }

});

First we calculate the play time remaining (in seconds), the position of the playhead as a percentage of total duration, and the minutes and seconds remaining.

We then update the displayed time remaining in the player interface, taking care to insert a leading 0 if necessary to the seconds figure.

If we haven't triggered this event by manually seeking (determined a bit further on in the code), we move the playhead position indicator along the gutter track. This basically just slides the indicator along as we listen, unless we're using the slider mechanism to move the playing position, in which case we don't want to interfere with the position of the indicator because the slider code will handle that for us.

Until the audio has started to load, the duration of the audio file is not available. We therefore check to see if the audio file has started to load, and proceed to set up the slider for the draggable playhead control. We're using jQuery UI for our slider here, and the basic configuration options should be self explanatory. We add two event handlers; one on slide where we set a flag that we are manually seeking to a new position, and stop, to unset the flag and tell the browser's audio player that it needs to move to our new position in the audio file.

The only thing left is the play/pause toggle button.

$(audio).bind('play',function() {
  $("#playtoggle").addClass('playing');		
}).bind('pause ended', function() {
  $("#playtoggle").removeClass('playing');		
});		
		
$("#playtoggle").click(function() {			
  if (audio.paused) { audio.play(); } 
  else { audio.pause(); }			
});

First we set up a couple of event handlers. When we start playing the audio, we add a class of 'playing' to the button so that it switches to the pause state. We then remove that class if we pause the audio playback, or reach the end of the file which fires the 'ended' event.

Our click handler for the play/pause button is very simple; play the audio if we're currently paused, otherwise pause it.

So that's it for a super simple audio player using lovely web standards instead of Flash. By going down this route, Tim's visitors can use his audio player on mobile devices like the iPhone and iPad, and the loading performance of the player is hopefully better than would have been achievable with a plugin based solution. Go and listen to The Box, and if you have any questions or ideas for improving the player, please leave a comment.

UPDATE: Fixed the code for Opera, providing the WAVE source and a more detailed check for support of the buffered property.

UPDATE 2: Fixed a typo binding the play event handler, which should be $(audio).bind not audio.bind. Thanks to @patdryburgh for helping find that.

Useful Resources:

Photo credit: Miikka Skaffari

Single-Line vs Multi-Line CSS, plus TextMate tips

Tue, 23 Mar 2010 00:00:00 +0000

Now that the stormy debate around whether or not designers should be able to code what they produce has died down, the new debate du jour is here! Or rather, it's back again. This one has been around before, and it's about whether laying out your CSS code on single lines (one selector per line), or multiple lines is better.

In the red corner; single-line CSS code formatting:

header h1 { float: left; width: 155px; height: 50px; }
header h1 a { display: block; opacity: 0.8; border-bottom-width: 0; }

In the blue corner; multiple-line CSS code formatting:

header h1 {
	float: left;
	width: 155px;
	height: 50px;
}

header h1 a {
	display: block;
	opacity: 0.8;
	border-bottom-width: 0;
}

The principal argument for coding on single lines is that you end up with a file that has all your selectors stacked up on top of each other, allowing for easier eye scanning when hunting for a specific selector.

The most common argument against is that when you're working in a source controlled environment (which of course we all are because we'd be idiots not to, right?) and a change is made to the CSS, there's no way with the single-line approach to quickly see which property was changed and how. Here's a modification to some multi-line CSS code:

And here's how the same modification would look if this was a single line statement:

It's obvious from the multiple-line example that the background-color property has been changed from transparent to "#fff", but in the single-line example the actual change isn't highlighted because differentiators only work on a per-line basis, so it just reports that the whole line has changed. It will be up to you to work out which property was modified. Now talk to me about "easier to scan".

For the most part, and complexities during source control diffs aside, this is simply a case of personal preference. Opinion is divided right down the middle as to which is better, with no fence sitters because really you just have to pick your preferred option (as a team if there's more than one CSS coder involved on a project) and stick to it for consistency. Saying that it's best practise to use one technique or the other isn't really helpful — just figure out what works for your situation and environment and stick with that.

My preference is for multiple-line CSS, because that's how I've always done it, I use source control on every single project (even solo projects), and my process for designing and front-end coding involves inspecting elements in Firebug, testing modifications to markup and style, then using Find ⌘F to jump immediately to the relevant selector I want to change. This involves no visual scanning for selectors in my code editor, and once you have the required keystrokes wired into your brain I guarantee that this is far quicker than scro

But enough of this petty bickering debate! Because I'm lucky enough to be a TextMate user, this is all completely academic. Here are two quick TextMate tips for multiple-line CSS coding to help with finding selectors, if you want the best of both worlds.

When editing a CSS file, you'll have a "Symbol Navigator" in right side of the status bar, which displays the currently focused selector based on cursor position. If you click the Symbol Navigator, a menu appears which displays all your selectors in a very easily scannable list. Simply click on one to jump straight to it.

You can also use the shortcut ⌘⇧T to pull up a "Go To Symbol" dialog, where you can type part of your selector and it will suggest matches. Use the arrow keys to move up and down the matches, and the Enter key to jump to that selector in your file. Hat tip to Doug Neiner for that one.

There's also a quick way to jump between what is effectively a selector only view and your standard multiple-line format, by making use of Code Folding. While editing normally and laying out code using the multiple-line technique, your code will look something like this:

But if you use Code Folding to collapse your code on all levels (and with vanilla CSS there will only be one level anyway) using the shortcut ⌘⌥0 then you'll reduce your display of your code to this:

This view will help you scan selectors quickly without the attributes getting in the way. When you've found the selector you want, pushing ⌘⌥0 again will return you to the unfolded view.

Notice by the line numbers that I'm not afraid of large CSS files, and why should anyone care about that? It's 2010 and we have smarter text editors these days than the days where a 2000 line file was a big deal because of all the scrolling we had to do. CSS should be minified as part of your deployment process to your production environment anyway, so this is a non-issue for your end users who are served the file.

So, go forth and code in whatever style you prefer. Hopefully this shows you that if you have the appropriate tools for the job, smaller details like code formatting start to matter a lot less which allows us to spend our energies on coding more and better things, instead of arguing about how we code.

Update: Sean Gaffney commented to tell us about another TextMate shortcut: ^⌥Q which properly converts multiple-line CSS to single-line. Thanks, Sean!

Update 2: Another killer TextMate tip, this one from Doug Neiner - Hitting ⌘⇧T while editing a CSS file will bring up a "Go To Symbol" dialog with a list of all your selectors, which is much cleaner than my method for searching using Find. This "easier to scan selectors" argument for single-line CSS is really shot to pieces if you're a TM user now. Thanks Doug!

A simple technique for web app maintenance modes using Apache

Thu, 18 Mar 2010 00:00:00 +0000

Sometimes we need to take our web apps offline temporarily (usually for scheduled major updates or emergency repair work), whereby regular users are shown a simple static page notifying them that the site is unavailable but still giving developers/admins full access to the site to test changes. Of course you could implement this in your application, but wouldn't it be nice if you could get your web server to do it all for you?

Its not as hard as it sounds thanks to some great Apache modules, most notably mod_rewrite.

Here are the basic rules we regularly use at Neutron Creations (I'll go in to more detail in a moment), these go inside our .htaccess file, but with some modification could go in the main httpd.conf file if you'd prefer.

# Part I
RewriteCond APP_ROOT/maintenance.txt -f
RewriteRule SUPER_SECRET_URL / [R,L,CO=AllowMaintenance:1:YOUR-DOMAIN.COM]

# Part II
RewriteCond APP_ROOT/maintenance.txt -f
RewriteCond %{REQUEST_URI} !^/maintenance/
RewriteCond %{HTTP_COOKIE} !AllowMaintenance
RewriteRule .* /maintenance/ [L]

# Part III
RewriteCond APP_ROOT/maintenance.txt -f
RewriteRule ^(.*)$ - [env=MAINTENANCE:1]

Header set cache-control "max-age=0,must-revalidate,post-check=0,pre-check=0" env=MAINTENANCE
Header set Expires -1 env=MAINTENANCE

This technique uses the presence of a file (APP_ROOT/maintenance.txt) to enforce a set of rules. To enter maintenance mode simply create this file with touch APP_ROOT/maintenance.txt, to leave maintenance mode remove this file with rm APP_ROOT/maintenance.txt. You'll need to replace APP_ROOT with whatever makes sense in your application environment.

I tried to set this relative to Apache's DOCUMENT_ROOT but could not get this to work, if anyone knows how to do this please do let me know in the comments. Thanks to ianjs for pointing out the correct syntax for this, you can use %{DOCUMENT_ROOT} in place of an absolute value for APP_ROOT to reference your document root

Part I

This provides developers (or anyone who knows the secret URL) with continued access to the app by setting a cookie that will be remembered for the session, and used in later rules. You will need to change YOUR-DOMAIN.COM to be the correct domain for your app, you could also add an expire time on this cookie if you wish (more info in the mod_rewrite flags docs).

You will also need to ensure the SUPER_SECRET_URL is set to something suitable, complex enough to be unguessable by users but easily read out if case you need to give it out over the phone.

Part II

This is the key set of rules for what we're trying to achieve, and reads like this: IF we are in maintenance mode AND the request is not for the maintenance page AND the AllowMaintenance cookie is not set THEN redirect the request to the maintenance page.

The maintenance page must be completely self contained within this maintenance directory, as any sub-requests outside of this path (for any CSS/JS assets used on the maintenance page for example) will be redirected to the maintenance page themselves.

With this directive, Apache will serve an internal redirect so the user will still see their original URL in their address bar, allowing them to refresh to try again later. If you want an external redirect so that the user sees the '/maintenance' URL instead, then just add the R flag to this RewriteRule.

Part III

This part could be quite important depending on how aggressively you cache HTTP requests in your application. Using an environment variable that's only set if you're in maintenance mode, we override any cache related headers sent from your app, making all requests expire immediately and telling proxies/caches to avoid caching anything going forward. You'll need mod_headers enabled for this part to work.

So there you have it, a very simple method to gracefully shift your web app into maintenance mode, completely independent of your application code itself. I'm sure this could be expanded upon and I'd love to see any ideas you might have for building on this technique, so drop a comment here and let me know.

Photo credit: tweek

Update: Its important to make sure that if you are NOT using an external redirect in Part II that you need to be careful linking to any assets as any relative paths will be relative to the url that user was trying to reach. Try to use absolute links where possible. I wasn't clear about this before, thanks to Dasha for pointing this out.

Update 2: I've been asked if it would be possible to serve a 503 (or similar) response to search engines to prevent them indexing the maintenance page. I have an alternate solution for this, if you serve an external redirect with a status code '307 - Temporary Redirect', by adding the R=307 flag in Part II, this will tell search engines to ignore the response and continue to index the original page. In addition you can add a 'Retry-After' header to inform them when to try again, just add this after the other Header directives Header set Retry-After 1800 env=MAINTENANCE which says to try again after 30 minutes.

Easier print CSS coding using Firebug and Web Developer Toolbar

Mon, 15 Mar 2010 00:00:00 +0000

Print stylesheets are an aspect of front-end engineering that rarely get any love, and they'll often be ignored until the last possible moment before launching a site. Sometimes they might even be forgotten altogether, but you should always make time to write at least a basic stylesheet that formats things neatly, and reveals any elements that only make sense on paper while hiding things like interactive controls that will be useless when printed.

But how to make the process of creating a print stylesheet as painless as possible? The obvious (and painful) way of working goes something like this:

Open/refresh your site in a browser
Pull up a Print Preview
Make changes to your print CSS in your editor
Close the Print Preview
Go to 1

It's only going to take a few laborious cycles through that loop before you're ready to give up and work on something more rewarding.

But wait, there's a better way! By using Firefox with its two close friends; Firebug and Web Developer Toolbar (you're all using these daily for front-end engineering anyway, right?), we can make working on a print stylesheet as simple as one for the screen. Observe.

First, open your website in Firefox, then we'll ask Web Developer Toolbar to render the page using your print rather than screen CSS by choosing CSS → Display CSS By Media Type → Print from the Web Developer Toolbar:

Now what you'll see is your website rendered using your print media type CSS. We could just launch Firebug and start attacking the DOM and our styles at this point, but if you need to reload the page to pull in changes made to your code via your text editor, you'll have to choose to view the print CSS again.

Thankfully there's an option for that; Options → Persist Features, which will retain our CSS media type preference across page reloads:

Now we can start using Firebug to inspect our page and play with styling and markup as normal, and if you need to reload the page, you'll still be viewing the print CSS afterwards.

So now that you have no excuses for not producing sensible print CSS, go and give this a try and patch up your site. We still need to do ours — I'll get around to that some day.

The site you see in the background here is Eric Meyer's 2002 article on print stylesheets, which despite being 8 years old is still relevant today, and even made use of a CSS3 attribute selector for some super progressive enhancement before we even knew what that term was.

Redesigning interfaces: learn from the old before you throw it away

Tue, 09 Mar 2010 00:00:00 +0000

Central heating, as a domestic utility, has not changed much over the decades. We burn fuel, our homes stay warm when its cold outside, and we generally regulate the service in one of two ways — either it's thermostatically controlled to maintain a constant room temperature, or scheduled according to rudimentary on/off time programming.

The interfaces to the latter control system however, have changed considerably over the years. Here's an old control interface, still in use in many homes (but I would guess no longer manufactured for sale in any new systems today), based on a mechanical rotary time switch.

To set the on/off periods, you move the small plastic tappet switches to either an inner (on) or an outer (off) position. The example here is set to run constantly from 10am to 10pm (hour 10 to hour 22). You can set the current hour simply by turning the inner dial, and you can switch between timed, and constantly on or off with the large switch in the lower right.

Compare this to a more modern interface, with an LCD display, and multi-function buttons.

These are just some of the buttons on this system. If you slide down the face plate, a further five are revealed which are used for actually modifying the schedule.

If you compare the manuals for these two systems, the manual for the rotary timeswitch is about as extensive as my description of it above. Just set the time by turning the dial, then put the switches into position corresponding to your desired on and off times, set the thing to timer mode, then go and get on with your life.

The manual for setting up a schedule on the digital system involves ten pages of A4, including (I kid you not) no less than four flow charts. This system supports per-day scheduling, so to set it you start with the current day, then you're forced to set up four discreet active periods of heating operation (if you want fewer than four, you have to set some of them back to back). Times are set (and the clock) using Plus, Minus and Enter keys, and when you're done setting one day you can copy and paste the times (no really) to other days, or set them individually. It's not hard once you've got the hang of it, but even the most basic schedule set up will involve about 20 key presses.

Now let's say that winter is passing into spring, but it's still pretty cold at the start and the end of the day so you want the heating on at those times but off while the sun is radiating you nicely during the day. If you have the timeswitch control, you can reach straight for the day time tappets and nudge them all to the off position with a swipe or two of one finger and then go back to training your cat to make a Reuben sandwich, or whatever it is you enjoy doing when you're not programming central heating systems. If you have the newer digital system, first switch the system to Edit mode, push enter repeatedly until the blinking digits represent the day, and then the time you want to change, then use the Plus and Minus keys to ... well you get the idea.

The timeswitch interface is perfectly simple, both aesthetically and in terms of functionality. When you come back to it months after setting a programme and needing to make an alteration, you can see at a glance the current schedule on the familiar clock face layout, and even complete reconfiguration will take a few touches and mere moments. It does have its downsides of course. You don't get per-day scheduling, and with moving clock parts inside it's neither as silent nor as reliable as its digital replacement, but its certainly a lot easier to actually use.

As far interface design goes, we've taken a big leap backwards with the digital heating control. When you're redesigning an interface for anything, please make sure you look at (and use!) what you're replacing to make sure you're not throwing away something that did the job far better than your proposed solution. You may have newer technology to hand which makes the old design look antiquated, but there will always be lessons to learn from any design you're inheriting and hopefully improving upon. Ignore them, and our lives will be full of endless Edit/Run mode, Plus, Minus and Enter button experiences, supplemented by multi-page manuals stuffed with flow charts.

Why TextMate?

Wed, 17 Feb 2010 00:00:00 +0000

I'm often asked "what text editor do you use?", and I respond TextMate. I'm usually then asked "so, why do you use TextMate?". There's many reasons I use it, and I've heard of developers switching from a PC to a Mac in order to use it. Can a text editor be so good that it can make a developer switch operating systems? Hopefully this article will introduce you to how powerful TextMate is and you can decide for yourself.

File Management

Lets start at the beginning with file management. As with most IDEs you have a list of files and/or folders, and TextMate is no different. This is displayed in the 'Project Drawer' (see right). This in itself is nothing special, anyone who has used or seen OSX knows that many apps have these 'drawers'. What is special about TextMate, at least for me, is that there is a much faster way of finding the files you want called 'Go to file', found under the 'Navigation' menu or on the keyboard shortcut ⌘T. This brings up a small dialog window listing all the files in the current project which is filtered as you type. As you can see from the screenshot below, this not only searches for exact matches but also any filename that contains the letters you enter in that order.

You can scroll through this list with the arrow keys (the first one is selected by default) and select a file to open with the enter key. TextMate will remember which files you have chosen for each entry and weight its list accordingly which allows you to create shortcuts to certain files, for example in nearly all of my Ruby on Rails projects entering 'rou' will select the 'config/routes.rb' file which has gotten me in to the habit of bringing up the routes file with the following keystrokes ⌘T, R, O, U, ↵

Editing

Once you have open the file you want to edit there are numerous ways TextMate can help you get things done quickly. One of my favourite is the ability to edit multiple lines at the same time. For example if you had the following code in your project somewhere and wanted to shorten the name of the variables.

var Button_Next = $('button.next'),
    Button_Prev = $('button.prev'),
    Button_Cancel = $('button.cancel'),
    Button_Finish = $('button.finish');

You could use find/replace to replace 'Button_' with 'btn', or you could use TextMate's column selection, hold ⌥ while selecting with the mouse, to select all those columns and overwrite them with 'btn' by typing normally.

How many times have you found yourself omitting line-termination semicolons in a language that requires them (JavaScript, Java, PHP, C etc) after a long period of coding in a language that doesn't (Ruby, Python etc)? TextMate has a great feature which you'll find very useful called 'Edit Each Line in Selection' found under the 'Text' menu or the shortcut ⌥⌘A. Select the text, press the shortcut and then add a semicolon, TextMate will add that character the end of all lines in your selection. Voila!

Here's a few more quick time savers

Generate a 'lorem ipsum' paragraph by typing 'lorem' and pressing tab
From the command line open a folder with the 'mate' command
Inline/incremental search, activate with ⌃S and type, press the shortcut again to go to the next match
Close the currently open HTML tag with ⌥⌘.
Toggle commenting on the current line/selection with ⌘/
Send a selection of text to pastie or any other application that will accept text with ⌃⌥⇧V

Bundles

Most of the functionality of TextMate is provided by Bundles. These are extensions that add coding snippets, language support or interfaces to command line scripts. TextMate itself comes with over thirty of these bundles supporting a wide variety of programming languages and other features. Most are specific to a particular programming language, but some of them are more general.

The TODO bundle has just one command 'Show TODO List' ⌃⇧T which scans through all your project files and displays all TODO, FIXME and CHANGED notes in your code with links to the lines within those files. These tags are customisable in the bundle configuration through regular expressions

The Math bundle allows you to do quick and simple calculations or base conversions (Dec, Hex & Oct). There's just one shortcut to remember - ⌃⇧C. Select some text and press the shortcut keys, this will then present you with the following menu allowing you to select what you want to do with the selected maths expression. Option 2 (Evaluate and Replace Expression) is extremely useful for replacing inline expressions (ie, 60*60*24) with their evaluated value (86400).

The Blogging bundle allows you to edit blog posts in most blog engines that support the MetaWeblog API, including Wordpress, Movable Type, Drupal and Typo among others. There's a great screencast over on the TextMate blog that covers using this bundle.

Add-ons

As well as these built-in bundles there are a number of third party bundles which can increase your productivity. Just drop any of these .tmbundle packages in to your ~/Library/Application Support/TextMate/Bundles directory.

The Ack in project bundle provides just one feature, with the schortcut ⇧⌘A, a GUI to the ack command. Ack is much like grep but is aware of programming languages and the files associated with them, so it won't waste time searching through log files, core dumps or any other files not related to the project.

The Javascript Tools bundle provides a quick way to run Douglas Crockford's excellent JSLint on your javascript code. By default this runs validation when you save a javascript file with the keyboard shortcut ⌘S and provides error/warning counts in a small tooltip. It also has a more thorough validation summary available on this shortcut, ⌃⇧V.

This Git bundle adds a great simple menu on the ⌃⇧G shortcut for working with git repos. You're all using git right ?

Finally the Zen Coding bundles (Zen CSS & Zen HTML) add loads and loads of snippets to make working with CSS/HTML much quicker. Paul Boag gives a nice review of this over on the boagworld website.

If you have any must-have bundles, please drop a link to them in the comments and I'll check them out.

Is that it?

These are only the features that I use regularly without looking up and just touch the surface of what is possible with TextMate. If you want to find out more about what you can do with TextMate I'd highly recommend "TextMate: Power Editing for the Mac" by James Edward Gray II (buy it from amazon). It has almost 200 pages of great information, including expert features such as creating your own bundles.

As always if you have any thoughts or criticism, either positive or negative, please leave a message in the comments.

Photo credit: batega

The value of remarkable customer experiences

Fri, 12 Feb 2010 00:00:00 +0000

A couple of weeks ago I was out for a friend's birthday, in a bar called The Lexington. It was a Saturday night, so we arrived early so we could order some food before the place got too crowded. After placing our order, 45 minutes passed, and I let it get to a whole hour before I queried the order at the bar. They apologised and said that the kitchen was really busy, and indeed the bar was getting busier by the minute with a few tables placing orders for lots of food.

After about an hour and a half in total since placing the order, I went to the bar, by now intending to cancel the order and ask for a refund. I was promptly told that "due to the unusual circumstances, the kitchen has been closed." That's right, they closed the kitchen, and didn't notify people who had unserved orders. I was refunded, but with barely an apology or any offer of compensation like a free or discounted meal on another occasion. So that's the last time I'll be going back to The Lexington, and I'll be sure to mention this story to anyone who asks about that bar, or for a recommendation for a bar in that area, and tell them to avoid it like the plague.

After leaving The Lexington, by now beyond mere hunger, we stepped into a burrito shop a short walk away called Chilango. The guy who served us looked exhausted (it was only ten minutes before they closed at midnight after what must be one of their peak times for the week), but he greeted us like long lost friends, asked if we'd been before and offered to explain the ordering process when we said it was our first time there. As we ordered he made welcome suggestions about which options would work best with what we'd picked so far, introducing ingredients like they were members of his band, and their origins.

While we were eating, another member of staff asked if we'd mind filling in a feedback card as they were new and wanted to know how they were being received. I gladly obliged, unable to think of anything to criticise, but I suggested that they offer a some varieties of salsa instead of just one (hey it was late, give me a break). When we left, we were thanked by all the staff at once, and the guy who was wiping tables near the door told us to enjoy the rest of our weekend.

Fast forward a week, and I get an email back from someone at Chilango, personally thanking me for my feedback and saying how much it means to them to hear that I enjoyed the atmosphere and the friendliness of their staff. They even said they'd look into finding some other kinds of salsa. As a result of that email and my remarkable experience, I'm writing this blog post which you're now reading, and I'd urge you to go and check them out if you're near one of their locations in the UK (London's Upper Street and Fleet Street, and Sheffield's Meadowhall, at the time of writing).

Do you see the difference there?

If you're in charge of selling a product or service, whether you own it or if you're just the person on the front lines talking to customers, please take a good look at the experience your customers are getting. You might be able to get by offering a mediocre experience if you're hosting live music and serving niche products like The Lexington (they specialise in bourbons and American whiskey), but wouldn't you rather provide an experience that's going to inspire your customers to write blog posts like this one, and tell all their friends about you? Which approach is going to grow you a customer base of fans instead of regular patrons?

If you want to know more about remarkable experiences and why they're so important, you need to read the works of Seth Godin - especially Purple Cow, but really everything he's written, including his blog.

Photo credit: Striatic

Send contact form submissions to Highrise

Tue, 09 Feb 2010 00:00:00 +0000

While adding a few features the back-end of our contact form logic I had an interesting thought; Wouldn't it be nice if these messages not only arrived in our email mailbox, but were also automatically entered into our Highrise account. Highrise is a web-based CRM from 37signals which we use for tracking contacts and project leads.

When the contact form is submitted, we do a little processing (with PHP) and then fire off an email to our contact address as normal. Highrise supports forwarding emails to a 'dropbox' address (more on dropboxes) which will then be imported as a message, creating the original sender as a new contact, or attaching it to an existing one if the email address matches with one of your contacts. All we have to do is add an additional step to reformat the email as a forwarded message, and send it to our dropbox address. Here's the code we use:

$body = "New Contact Form Submission\n\n";

// build message body
/***** <snip> ****/

// sanitise email/name
$name_safe  = mail_header_safe($_POST[&#039;contactName&#039;]);
$email_safe = mail_header_safe($_POST[&#039;email&#039;]);

// send to our contact list
mail($contact_addr, &#039;Contact Form&#039;, $body, "From: $contact_addr\r\nReply-to: \"$name_safe\" < $email_safe>\r\n");

// build highrise body
$new_body  = "\n---------- Forwarded message ----------\n" .
$new_body .= "From: \"$name_safe\" < $email_safe>\n\n";
$new_body .= $body;

// send to highrise
mail($dropbox_addr, &#039;Fwd: Contact Form&#039;, $new_body, "From: $contact_addr");

You will also need to make sure that the from address in these emails ($contact_addr in our code) is registered to a user on your Highrise account, otherwise the message will be discarded by the Highrise importing process. See the Highrise help page for more information on this.

As usual, if you've found this useful or have any improvement please leave a comment!

How to track traffic exiting your site

Wed, 20 Jan 2010 00:00:00 +0000

Thanks to the great work Google have been putting in, we can now gather an enormous amount of information about our site visitors for free using Google Analytics. One of the metrics that I have always been curious about is the 'Exit Page'. Sadly, all visitors do eventually leave our sites and this metric shows what was the last page they viewed before leaving. Even more sadly, that's as far as we can get with a basic Google Analytics deployment. Wouldn't it be great if we could see where our visitors went after leaving our site?

Well, with a little bit of javascript magic we can.

What you'll need on your site

Google Analytics (I'm using the new Asynchronous Tracking code but with a little modification it'll work with the standard tracking code)
jQuery (again with some modification this can be done without, but you're all using jQuery anyway right?)

How do we do it

We're going to be using the Event Tracking functionality of Google Analytics to track whenever someone follows an external link on our site. Firstly we need a way of determining which links are actually external. We could add additional classes to any links you want to track or we can use a little jQuery tickery to determine that automatically.

Haven't used jQuery before? Don't know what on earth the $() function is? Check out the getting started guide, you'll thank me later

$.expr[':'].external = function(obj){
  return !obj.href.match(/^mailto:/) 
    && (obj.hostname != document.location.hostname);
};

jQuery Howto

This adds the :external filter allowing us to use $('a:external') to select external links.

All we need to do now is to use this selector to track events when these links are clicked. The documentation shows that the _trackEvent() method takes four parameters; Category, Action, Label and Value. Of these four, only the Category and Action are mandatory. We'll be using the optional Label parameter to pass the URL of the external site back to Google Analytics.

$('a:external').click(function(){
  _gaq.push(['_trackEvent','Outbound','Link',$(this).attr('href')]);
});

Taking it further

We're using a Category of 'Outbound', as these events are all related to off-site events, and an Action of 'Link' as we're looking at links. We can expand on this using a little more jQuery to change this Action based on some conditions, for example if the link is within another element, if it has a particular class or if the url contains a string.

$('a:external').click(function(){
  var link = $(this), type = 'Link';

  if ( link.closest('ul.comments').length == 1 ) type = 'Comment'; 
  if ( link.hasClass('amazon') ) type = 'Affiliate';
  if ( (/pastrami/i).test(link.attr('href') ) type = 'Tasty';

  _gaq.push(['_trackEvent','Outbound',type,link.attr('href')]);
});

You could also this technique for other similar events, that might not otherwise be tracked by Google Analytics, such as for downloads

// track downloads of Acrobat and ZIP files
$('a:not(:external)').filter(function() {
  return (/\.(pdf|zip)$/i).test($(this).attr('href'));
}).click(function() {
  var href = $(this).attr('href'),
      pos = href.lastIndexOf('.'),
      ext = href.substr(pos+1).toUpperCase();
  _gaq.push(['_trackEvent','Download',ext,href]);
});

All done

Once that is all in place and you've had some events tracked by Google Analytics you'll be able to see the events showing up in the reports. Here's a shot of the events shortly after the launch of the Neutron Creations site on the 19th January 2010.

So that's it. Now you can track where your visitors are going when they eventually leave your site. If you have any improvements or other uses for this sound off about them in the comments.

Photo: lansakit

New year, new site

Thu, 14 Jan 2010 00:00:00 +0000

As the dust settles on 2009, everyone is busy putting their plans for 2010 into action. For us, we're kicking our plans off with the unveiling of something we've been planning and building for a little while now - a new website for Neutron Creations.

Our first site, designed by Tim Van Damme, was built to communicate a small amount of information about who we were and what we did. The resulting one page design turned a lot of heads for its striking appearance, and it fulfilled its duty brilliantly by bringing us some of our first clients. As we found our feet with the business and completed our first projects, we knew it was time to expand the site into something more detailed. Looking back, it's clear that we owe a lot to Tim's design, and it's with mixed feelings that we move it to our little museum where it can be admired for years to come.

For the new site, we approached Elliot Jay Stocks who we'd already worked with, and told him we wanted something unconventional that didn't abandon the feel of the original site completely. It took us some time to get used to the radical ideas he came out with, but we believe he's really outdone himself and we're over the moon with our new home on the web. We'd love to hear what you think too, so please leave us your feedback in the comments, especially if you've spotted any teething problems. The new site is also home to our portfolio (which we'll be adding to soon) and a bit more blurb about what we're all about, as well as the blog you're reading now which we've dubbed The Particle Lab.

Our lab techs will bring you news on what we're up to, and will also share plenty of ideas, techniques and tricks we discover as we continue building web applications for ourselves and for our clients. We'll be talking about anything that pops into our heads that we think someone might find useful, from snippets of code from our weapons of choice such as Ruby (on Rails), HTML, CSS and jQuery, but also less technical topics such as our views on the state of our industry, or ideas for marketing your products and services. One thing we can guarantee is that there will be absolutely no top ten lists of any kind. On that you have our solemn word.

So please subscribe to this channel via our feed or email, follow us on Twitter, or just stop by once in a while for the latest post. We look forward to welcoming you back here soon.