Trackets Blog

Tips for building a Single Page Application

2014-09-29T13:11:00Z

Everyone’s building single page applications (SPA) these days. We’ll take a look at some of the challenges and best practices for building JavaScript heavy applications. Some of the things might not be so obvious at first glance, but it definitely helps to think about this up front. After all, it’s quite a big decision to go JavaScript all the way.

Don’t break the browser

While most of the modern JavaScript frameworks out there can handle URLs pretty well these days, it is still important to sit back and think about this for a moment. Your application might have multistep forms, which aren’t persisted in the URL, but the user might still want to reload the page without losing everything.

There is usually a lot of state on each page of a Single Page Application. It might be pagination, or the amount of scrolling the user has done when using infinite scroll, or the detail of something that appeared in a lightbox when he clicked on it. Such things usually lead the user to another page when using a regular website, but in a Single Page Application, it usually doesn’t. Even though the user would still expect the state to somehow be perserved.

Test on real mobile devices

Everyone has at least one smartphone these days, or a tablet, or a small laptop with a touch screen. The point being, no matter how small your audience is, they will try to use your application on their mobile devices. I’m saying try to use, because if you haven’t thought about mobile in the beginning, there’s a fair chance that the app won’t work very well. The reason why this is a problem more for Single Page Applications and not for the old-fashioned static websites, is that the more JavaScript you have, the more likely you’re going to run into something funky.

The mobile browsers are pretty good at displaying <a href="..."> links, but they might not be so perfect at drawing your fancy charts, or at handling that parallax scrolling you just added using 5 different hacks. In fact, scrolling is probably the most absused thing I’m running into. It just always feels that I’m either using a mouse on what was designed for a touch screen, or the other way around. Just because you’re developing on a MacBook Air with a Trackpad, it doesn’t mean that everyone in the world uses a Trackpad as well.

An important thing to note here is that testing on a real device is not the same as resizing your desktop browser window to 480x360. There is a completely different feel from using your fingers to move around.

SEO

If your application is facing the public internet, it should be indexable by the search engines. Imagine if something like Amazon suddenly decided to rewrite everything using JavaScript. It doesn’t even need to be a Single Page Application, all it takes is that the main content is generated by JavaScript.

A great example of this is Discourse, which while being a Single Page Application written completely in Ember.js, still manages to work without JavaScript at least to some extent. This is not only good for the search engines, who can easily index the whole forum, but also for users on old mobile devices, or just bad browsers in general. In fact, I know quite a few people who have JavaScript disabled by default, and only enable it for the sites they trust.

I’m not really talking about progressive enhancement, since that would take a lot of effort on your side to make the application work completely without JavaScript after you’ve decided to write the whole thing in Angular. What I’m saying is that it is a good idea to have the core functionality working, at least to some extent, without JavaScript. This might mean that the users can read the content, but can’t do anything else on the site.

SPA users have higher expectations Once you start with the whole SPA thing, your users’ expectations will grow massively. Take Discourse for example. If you’re replying on a regular forum, you simply hit the reply button and start writing your reply. If something pops up in your mind and you decide to search the forum some more, you simply open a new tab in your browser.

On the other hand, Discourse implemented this neat feature when you can keep navigating the site, while having your reply still open at the bottom of the page (see this topic). This however, while being an awesome feature, brings up a lot of newborn complexity. For example, they’ve also implemented a feature, that if you finish writing your reply while being on a different topic than you were originally, you will be prompted to reply to that topic instead.

You can also collapse (minimize) the reply form, it saves the text as you type to the backend, etc. Just a bunch of very cool things from a UX perspective.

But there’s a downside to this as always. Think about how much work goes into designing the workflow I just described, vs creating a simple and static HTML form. It isn’t even on the same scale. You can deliver a much better experience to the user, but you’re also going to delay the whole project by a significant amount of time. Ever new feature will yield 10 new opportunities for making the UI better (and more complicated), and in the world of client side applications, that also means it will take more time.

Another simple example here might be file uploads. If your website has a regular file upload, the visitor can simply drag & drop a file to the input and press submit. If it is a JavaScript application, you’re probably going to use the HTML5 File API to get to the file, then maybe add a nice overlay to show that the area responds to the user dragging a file, then maybe display a progress bar of the upload, which will require some backend work, then you’ll decide to add some animations to make it look good. Sure the JavaScript version might be cooler, but it will also take you a week to do properly.

Do you really need a Single Page Application?

Before you actually get into building one, really think about what parts of your application need to be highly interactive. It might be the case that there is only a single page in the whole app that would benefit from being all JavaScript, while the rest can easily be just plain old HTML. If this is the case, you might realize that there is no need for a client side router, since all the logic is on a single page.

By limiting the amount of pages that are pure JavaScript you can focus all of your effort into making those that are really great. There is really no point in wasting half of your development time on making the about/help/docs/pricing pages, when you could be working on your core application instead.

Unit Testing JavaScript with QUnit

2014-09-24T13:11:00Z

There are many testing frameworks available these days, most of which offer some very cool features, such as automated cross browser testing, etc. But today we’ll take a look at something much simpler, QUnit, which is our all time favorite at Trackets.

Why? Having 50 different testing frameworks to choose from actually isn’t so good, since you’ll be constantly arguing with everyone else about which framework is the best one, and what is the right way to test things. There are also many ways to run the unit tests, many different build frameworks, and just a huge number of choices in general when it comes down to creating a new JS project.

The reason why QUnit is our favorite is because you can skip all of the boilerplate around tools like Grunt. All you need is a web browser and a single .html file, which will serve as a test runner. You can even use a CDN for the QUnit source files and use a service like JSBin to get up an running in zero time. Here’s an example

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>QUnit Example</title>
  <link rel="stylesheet" href="//code.jquery.com/qunit/qunit-1.15.0.css">
</head>
<body>
  <div id="qunit"></div>
  <div id="qunit-fixture"></div>
  <script src="//code.jquery.com/qunit/qunit-1.15.0.js"></script>
  <script>
    test("hello test", function(assert) {
      assert.ok(1 == "1", "Passed!");
    });
  </script>
</body>
</html>

To run the tests, all you need to do is just reload the page. Want to debug the tests? Just insert a debugger keyword to trigger a breakpoint and reload the page. There are zero dependencies, zero setup time, and the tests run instantly.

QUnit basics QUnit is a very simple library with an easy to remember API, as there are only a few functions you’ll be using.

module - Defines a new module, which essentially groups a bunch of test cases together.
test - Creates a new unit test.
asyncTest - Creates a new asynchronous unit test.
expect - Sets the number of expected assertions in an asynchronous test.
start - Resumes the execution of an asynchronous test runner, we’ll talk about this later in this article.

Let’s examine our hello world example to see how to write a simple test using the QUnit API.

test("hello test", function(assert) {
  assert.ok(1 == "1", "Passed!");
});

The test function takes two arguments, the name of the test and the actual test itself in the form of an anonymous function. The name can be anything you’d like, and the function should accept a single argument, which is the assert object.

In our example we called the assert.ok function, which simply asserts that something is true. There is also assert.equal for comparing values (more assertions are documented in the API documentation, which means we could’ve written the same example as assert.equal(1, "1", "Passed!");. All assertions take an optional argument, which is a short description of the assertion. If you use one of the provided assert functions, such as assert.equal, QUnit will show a nice comparison if the test fails.

The QUnit runner allows you to re-run just a single spec by clicking the “Rerun” link, which will allow you to iterate more quickly in case something goes wrong, since you will be able to focus just on that one failing test.

Testing asynchronous code

Since JavaScript is by its nature asynchronous, you should be able to test such code. This could be either because of AJAX, some animation running, or just a simple setTimeout call. We’ll use the last one to see how to test asynchronous code.

Here’s a function that will wait 200 milliseconds and then increase a counter and call a callback.

window.bar = 0;

function foo(callback) {
  setTimeout(function() {
    window.bar++;
    callback();
  }, 200);
}

You might be tempted to test it by simply attaching a callback with an assertion.

test("hello test", function(assert) {
  foo(function() {
    assert.equal(window.bar, 1);
  });
});

But this won’t work as expected and will result in an error. Expected at least one assertion, but none were run - call expect(0) to accept zero assertions.

The reason for this error is that the test runner will exit immediately after the function is called, since the 200ms delay is asynchronous. The fact that we’ve attached a callback doesn’t do anything here, since QUnit has no way of knowing that we actually expect the callback to get called.

To combat this issue, QUnit provides a way to stop the test runner, and resume it later. This is done using the obviously named start() and stop() functions.

test("hello test", function(assert) {
  stop();

  foo(function() {
    assert.equal(window.bar, 1);
    start();
  });
});

The call to stop() increases a counter, and the call to start() decreases it. If the counter is more than 0 when the test function returns, the QUnit runner will keep waiting until the counter goes back to 0. The reason for this is that you might have multiple asynchronous operations that you’re waiting for, and multiple assertions. You can even tell QUnit how many assertions are you expecting using the expect() function. Let’s see an example.

test("hello test", function(assert) {
  expect(2);
  stop();
  stop();

  var x = 0;

  setTimeout(function() {
    x++;
    assert.equal(x, 1);
    start();
  }, 100);

  setTimeout(function() {
    x++;
    assert.equal(x, 2);
    start();
  }, 200);
});

We’re setting up two times, one that fires after 100ms, and second one that fires after 200ms. Initially we say that we’re expecting 2 assertions, which means that if we mess up our start/stop calls or the timing is wrong, the test will still fail if only one assertion gets called. We also call stop() twice, because we’re going to wait for two separate asynchronous operations.

The rule of thumb is that there should be the same number of stop() calls as there is start(). The only exception is when you use asyncTest instead of test, which starts out with the counter already set to one. The following two tests are thus equivalent.

test("foo", function(assert) {
  stop();
  assert.ok(true);
  start();
});

asyncTest("bar", function(assert) {
  assert.ok(true);
  start();
});

Conclusion

While QUnit might not be the shiniest of all the testing frameworks, it works perfectly and requires almost no setup. You can simply open up a JSbin and start prototyping your code while writing the tests, without having to install Node.js, configure Grunt, or do any of those other unproductive setup things.

In the next article we’ll take a look at how to run QUnit from the command line using Phantom.js, and how to create a cross-browser testing setup with QUnit and Karma.js.

SSH Tunnel - Local and Remote Port Forwarding Explained With Examples

2014-05-17T17:57:00Z

There are two ways to create an SSH tunnel, local and remote port forwarding (there’s also dynamic forwarding, but we won’t cover that here). The best way to understand these is by an example, let’s start with local port forwarding.

Imagine you’re on a private network which doesn’t allow connections to a specific server. Let’s say you’re at work and imgur.com is being blocked. To get around this we can create a tunnel through a server which isn’t on our network and thus can access Imgur.

$ ssh -L 9000:imgur.com:80 user@example.com

The key here is -L which says we’re doing local port forwarding. Then it says we’re forwarding our local port 9000 to imgur.com:80, which is the default port for HTTP. Now open your browser and go to http://localhost:9000.

The awesome thing about SSH tunnels is that they are encrypted. Nobody is going to see what sites you’re visiting, they’ll only see an SSH connection to your server.

Connecting to a database behind a firewall

Another good example is if you need to access a port on your server which can only be accessed from localhost and not remotely.

An example here is when you need to connect to a database console, which only allows local connection for security reasons. Let’s say you’re running PostgreSQL on your server, which by default listens on the port 5432.

$ ssh -L 9000:localhost:5432 user@example.com

The part that changed here is the localhost:5432, which says to forward connections from your local port 9000 to localhost:5432 on your server. Now we can simply connect to our database.

$ psql -h localhost -p 9000

Now let’s stop here for a little bit an explain what is actually going on. In the first example the 9000:imgur.com:80 is actually saying forward my local port 9000 to imgur.com at port 80. You can imagine SSH on your server actually making a connection (a tunnel) between those two ports, one on your local machine, and one on the target destination.

If we however say something like 9000:localhost:5432, it means localhost from the server’s perspective, not localhost on your machine. This means forward my local port 9000 to port 5432 on the server, because when you’re on the server, localhost means the server itself.

This might be a bit confusing, but it is important to understand what the syntax actually means here.

Remote port forwarding

Now comes the second part of this tutorial, which is remote port forwarding. This is again best to explain with an example.

Say that you’re developing a Rails application on your local machine, and you’d like to show it to a friend. Unfortunately your ISP didn’t provide you with a public IP address, so it’s not possible to connect to your machine directly via the internet.

Sometimes this can be solved by configuring NAT (Network Address Translation) on your router, but this doesn’t always work, and it requires you to change the configuration on your router, which isn’t always desirable. This solution also doesn’t work when you don’t have admin access on your network.

To fix this problem you need to have another computer, which is publicly accessible and have SSH access to it. It can be any server on the internet, as long as you can connect to it. We’ll tell SSH to make a tunnel that opens up a new port on the server, and connects it to a local port on your machine.

$ ssh -R 9000:localhost:3000 user@example.com

The syntax here is very similar to local port forwarding, with a single change of -L for -R. But as with local port forwarding, the syntax remains the same.

First you need to specify the port on which th remote server will listen, which in this case is 9000, and next follows localhost for your local machine, and the local port, which in this case is 3000.

There is one more thing you need to do to enable this. SSH doesn’t by default allow remote hosts to forwarded ports. To enable this open /etc/ssh/sshd_config and add the following line somewhere in that config file.

GatewayPorts yes

Make sure you add it only once!

$ sudo vim /etc/ssh/sshd_config

And restart SSH

$ sudo service ssh restart

After this you should be able to connect to the server remotely, even from your local machine. The way this would work is that you would first create an SSH tunnel that forwards traffic from the server on port 9000 to your local machine on port 3000. This means that if you connect to the server on port 9000 from your local machine, you’ll actually make a request to your machine through the SSH tunnel.

A few closing tips

You might have noticed that every time we create a tunnel you also SSH into the server and get a shell. This isn’t usually necessary, as you’re just trying to create a tunnel. To avoid this we can run SSH with the -nNT flags, such as the following, which will cause SSH to not allocate a tty and only do the port forwarding.

$ ssh -nNT -L 9000:imgur.com:80 user@example.com

SSH has a huge number of features, so I’d recommend you to checkout the manual page at man ssh, which contains even more tips.

There’s also an amazing talk called The Black Magic of SSH / SSH Can Do That?, which I really recommend you to watch.

Why should you care about JavaScript errors?

2014-05-04T14:33:00Z

Most of the websites on the internet aren’t just static pages anymore. Half of the internet is using jQuery, and with the growing popularity of single page applications we have even more JavaScript in our apps.

This however leads to completely different problems which aren’t present in standard server-only architecture. When something goes wrong on your backend, it’s usually just a single request that failed and you have all the context available.

The problem with JavaScript is that the applications usually live for more than just a single request. One thing might silently fail and cause an error a few minutes later in a completely different part of the UI, as the user continues on using your application.

Problems unique to JavaScript applications

Errors on the backend can break the frontend in unexpected ways.
Some users might click on everything twice, causing race conditions.
Internet connections are sometimes flaky.
Requests which usually takes 150ms might suddenly take 15 seconds.
Users will have your application open for hours without a page-reload.
Client side data might get corrupted and break seemingly unrelated parts of your application.

This screenshot is from a top100 site on the internet.

It just took a few page reloads and oops there’s an error. It doesn’t seem to impact the page at first sight, but who knows. Maybe it’s causing some backend service to not function properly, maybe some analytical data isn’t being collected, or maybe it will cause another error after using the site for a while. The interesting bit here is that the error doesn’t happen all the time, which means it might go overlooked when the application is being tested, but then it starts happening to actual customers.

Your application has these problems too

Now if a huge site like this has these problems, your application probably has them as well, you’re just not aware of it. Here’s where Trackets will help you.

You’ll see all runtime errors with detailed information about the context in which they occur. If a user clicked on a button which caused the error to happen, you’ll see it in the error message. Without any overhead or impact on your application.

You might be thinking that there is already a lot of exception trackers that are able to handle these kind of problems. The problem with a lot of them is that they weren’t designed to solve JavaScript errors in particular. Most of the existing solutions just support JavaScript as yet another platform among many. This approach works for backend languages, where there is no user interaction, but the frontend needs more.

Every client session is different and every user interacts with your application in a different way. Some users might double-click on a button where they should click just once. This will work for regular links, but not single page applications full of AJAX calls, where it might result in a race condition that breaks the app’s functionality.

All of these problems are just a small fraction of what can go wrong in your application.

Giving a meaning to stacktraces

2013-11-25T15:33:00Z

We’ve all been there, something goes wrong, you look at a stacktrace and have absolutely no idea what the hell is going on. If only there was something that would give you more context, for example a list of all the actions a user had taken before the error occurred.

In order to make the whole bug-hunting process less painful we’ve decided to record all events that lead up to unhandled exceptions. When a new error pops up, you can just look at the event log and instantly see what happened. Maybe the user clicked a button 4 times in a row instead of just once. That sort of thing would never appear in a stacktrace, but it might as well cause a race condition in your app.

Or maybe you’re doing AJAX and forgot to handle the error case in some obscure use case. Then the request fails and your application fails as well, but in a different place which depends on the request being successful. With Trackets we’ll not only show you the user events (such as mouse click events), but network requests as well.

But this isn’t the end of our story. We still have more features to uncover, logging events in the browser is just the beginning.

4 Tips for Working with Dates in PostgreSQL

2013-08-26T11:47:00Z

Those of us who come from Rails aren’t surprised when we see something like 5.weeks.from_now or 3.days.ago + 2.hours, which makes working with dates much easier. But PostgreSQL got your back on this as well, you can just use the builtin functions and get most of the same functionality.

Current Time/Date/Timestamp

There are many ways of getting a current time, but first we need to distinguish between two types

always returns current value (clock_timestamp())
always returns current value, unless in a transaction, in which case it returns the value from the beginning of the transaction (now())

Let’s take a look at an example

postgres=# BEGIN;
postgres=# SELECT now();
              now
-------------------------------
 2013-08-26 12:17:43.182331+02

postgres=# SELECT now();
              now
-------------------------------
 2013-08-26 12:17:43.182331+02

postgres=# SELECT clock_timestamp();
        clock_timestamp
-------------------------------
 2013-08-26 12:17:50.698413+02

postgres=# SELECT clock_timestamp();
        clock_timestamp
-------------------------------
 2013-08-26 12:17:51.123905+02

As you can see, clock_timestamp() changes every time the statement is executed, but now() always returns the same value. It’s also worth noting that both of these functions take timezone into account.

Time interval, aka `3.days.ago`

You can easily create time intervals using the interval operator, for example

interval '1 day'
interval '5 days'
interval '5 days' + interval '3 hours'
interval '5 days 3 hours'

As you can see, we can do simple math using the interval operator, which makes it very easy to construct things like 3.days.ago just by doing the following

postgres=# SELECT now() - interval '3 days';
           ?column?
-------------------------------
 2013-08-23 12:23:40.069717+02

Extracting the day of the week and more

Sometimes you just want to know the day of the week for a given date, or the century, or just the day. PostgreSQL has an extract() function which does just this.

Just to put this into context the examples were executed on Monday, August 26.

postgres=# SELECT extract(DAY FROM now());
 date_part
-----------
        26

postgres=# SELECT extract(DOW FROM now());
 date_part
-----------
         1

You can do much more with extract(), for a complete list of examples take a look at the official documentation. Here’s just a few

day
century
dow (day of week)
doy (day of year)
minute
month
year

Converting between timezones

Sometimes it is useful to show a specific date in a different timezone, which is exactly what the AT TIME ZONE construct is for. Let’s take a look at how it works. We’ll do this in a transaction so that the now() function always returns a same value and we can easily see the difference in hours.

postgres=# BEGIN;
BEGIN
postgres=# SELECT now();
              now
-------------------------------
 2013-08-26 12:39:39.122218+02

postgres=# SELECT now() AT TIME ZONE 'GMT';
          timezone
----------------------------
 2013-08-26 10:39:39.122218

postgres=# SELECT now() AT TIME ZONE 'GMT+1';
          timezone
----------------------------
 2013-08-26 09:39:39.122218

postgres=# SELECT now() AT TIME ZONE 'PST';
          timezone
----------------------------
 2013-08-26 02:39:39.122218