Marcus Christie's Blog

From the Notebook: An Ember Bootstrap Modal Dialog and How to Deal with state in Ember controllers

2015-02-15T17:31:00.000-05:00

Bootstrap Modal Dialog for Ember

To create a Bootstrap styled modal dialog for an Ember app at work, I mostly followed the Ember cookbook entry on modal dialogs. One difference is using Bootstrap for the modal dialog, of course. Here are the steps I took.

Added a modal outlet to the application template
```
{{outlet}}
{{outlet modal}}
```

On my ApplicationRoute.js I have the following:

actions: {
    openModal: function(modalName, model) {

        return this.render(modalName, {

            into: 'application',
            outlet: 'modal',
            model: model
        });
    },

    closeModal: function() {

        return this.disconnectOutlet({

            outlet: 'modal',
            parentView: 'application'
        });
    }
}

This allows me to pass a model to the modal. One implication of this is that the modal view needs to have a corresponding Controller so that Ember can set the model on that Controller. It appears that by default Ember Routes will supply an ArrayController or ObjectController for routes that don't have one defined, but the same doesn't hold for these non-route views.

I then defined a modal-dialog component, but also split out modal-body and modal-footer components since those are the ones I'm expecting to customize from modal dialog to modal dialog.

<script type="text/x-handlebars" data-template-name="components/modal-dialog">
    <div class="modal fade" tabindex="-1" role="dialog" aria-labelledby="dialogTitle" aria-hidden="true">
        <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal"
                    aria-label="Close"> <span
                    aria-hidden="true">&times;</span></button>
                <h4 class="modal-title" id="dialogTitle">{{title}}</h4>
            </div>
            {{yield}}
        </div>
        </div>
    </div>
</script>

<script type="text/x-handlebars" data-template-name="components/modal-body">
    <div class="modal-body">
        {{yield}}
    </div>
</script>

<script type="text/x-handlebars" data-template-name="components/modal-footer">
    <div class="modal-footer">
        {{yield}}
    </div>
</script>

For the component code I need to call .modal() on the modal dialog to pop it up. I also wanted to handle the Bootstrap modal closed event and then remove the modal from the DOM (i.e., disconnect the outlet). Removing the modal from the DOM is not strictly necessary I guess, but I think it is nice to remove it from the DOM when it is no longer needed. If it is rendering a model, there's no point for the hidden modal to re-render when that model changes.
```
App.ModalDialogComponent = Ember.Component.extend({
    sendCloseAction: function(){
        this.sendAction('close');
    },
    didInsertElement: function() {
        this.$('.modal').modal();
        this.$('.modal').on('hidden.bs.modal', this.sendCloseAction.bind(this));
    },
    willDestroyElement: function() {
        this.$('.modal').off('hidden.bs.modal');
    }
});
```
To use it, just need to create a view that uses the modal-dialog component.
```
<script type="text/x-handlebars" data-template-name="myModal">
    {{#modal-dialog close="closeModal" title=title}}
        {{#modal-body}}
            {{message}}
        {{/modal-body}}
        {{#modal-footer}}
            <button type="button" class="btn btn-default" {{action 'save'}}>Save</button>
            <button type="button" class="btn btn-primary" data-dismiss="modal">Close</button>
        {{/modal-footer}}
    {{/modal-dialog}}
</script>
```
One problem I ran into was that Components can only send actions based on names that they are given. My ModalDialogComponent can't call this.sendAction('closeModal') and have that be handled by the ApplicationRoute. Instead ModalDialogComponent calls this.sendAction('close') where the actual named action to send is specified in the view using the component. Here in the myModal template I'm specifying that for close the component should send the closeModal action. See Sending Actions from Components to Your Application for more details.

Ember Controllers Are Singletons

One surprising thing about Ember for me as I've been learning over the past couple months is that Controllers are (kind of, sort of) singletons. Ember instantiates a controller for a route once. So any state in a Controller is sticky. But often times you'll want to reset the state in your Controller when switching from one model to another. So what to do?

Found a couple of interesting blogs regarding this problem:

Both suggest resetting the controller in Route's setupController as one way to address this problem. (Note: Ember.Route also has a resetController hook; haven't used it but seems to cover exactly this need.) Balint Erdi's post has an interesting idea about having the reset logic in the Controller itself and having it observe some property that can be used to trigger a reset.

When thinking about Controller state and Routes, and where to put this state, it occurs to me that there are 3 kinds of view state. A view might want to take advantage of all 3 types of view state.

Transient view state

This is view state that you don't want to be sticky at all. Maybe expanding/collapsing an accordion type view, or form validation error display.

Basically, if the model changes, you want to reset this the transient state. For this you can define a resetState function that is called whenever the model changes.
```
resetState: function(){
    // reset transient stuff here
}.observes("model")
```
Sticky state, but not serialized to the URL

This would be view state that you want to be sticky so that when the user moves from view to view this state remains. However, for whatever reason, you don't want to serialize this state to a Route URL. This is the default way that Ember works.

Can't actually think of a good example here. Maybe a sub-view that you expand or show and as you move through different models you want to keep showing that sub-view?
Sticky state that should be serialized to the URL

If you have some view state that you want to be persistent, then you should really think about moving that to the Route and serializing to the URL. If that works for your use case, then you can do that and move that view state out of the Controller entirely.

To me, #1 is a more common type of view state than #2, so it seems weird that the default for Ember Controllers is #2. However, the fact that Ember Controllers are singletons makes #2 possible and then one just needs to reset state to make #1 work. If Ember Controllers weren't singletons, its hard to see where #2 style view state would be stored.

Odds and Ends

Console2: a better Windows console. I played around with setting up Console2 to get a better console window than cmd.exe. The following were helpful resources
- http://www.hanselman.com/blog/Console2ABetterWindowsCommandPrompt.aspx
- http://www.kevwebdev.com/blog/in-search-of-a-better-windows-console-using-ansicon-console2-and-git-bash.html
Here's what I like about Console2:
- You can configure it to copy on select and paste with a right click.
- You can resize the window (but you have to configure it to have more columns first, which is kind of weird). I sometimes like to have the console take up a full screen.
- It is tabbed.
- You can configure it to start a cmd shell or Git bash. I have Git bash as a default and hitting Ctrl+Shift+T opens a new Git bash tab.
Ember dot notation. Learned that in Ember instead of doing
```
this.get('foo').get('bar').get('baz');
```
You can do
```
this.get('foo.bar.baz');
```
If bar is not defined, then the first one would fail but the second would return undefined.
Git: counting words in a specific revision of a file. I wanted to be able to count how many words are in a previous version of a blog post. There might be a better way to do this, but here's how I did it.
1. Get the file's blob hash. You can do
```
git log --raw -- path/to/file
```
  Seems the easiest way. This prints the before and after blob hash for each revision
```
...
:100644 100644 c5d00fe... 2403611... M  path/to/file
...
```
  Where 2403611 is the blob hash for this revision and c5d00fe is the blob hash for the previous revision.
2. cat the blob and count the words. Getting the blob hash was the hard part, now we can simply do
```
git cat-file -p 2403611 | wc -w
```

Responsive Webapp Conclusions

2015-02-08T09:08:00.001-05:00

I've spent a few weeks now reading and thinking about whether it makes sense to use responsive web design techniques to build a single page web application (SPA) that works well on mobile and desktop computers. I started with my initial thoughts and reviewed arguments for responsive webapps and against responsive webapps. I haven't done as much reading as I would like and there is still a lot of good stuff out there to read and learn from. But I think I have learned enough to come to some conclusions.

Recommendation

The first step in deciding whether to go responsive or not with a single page web application is to first design the ideal mobile UI and the ideal desktop UI for your app. Obviously phones and desktop computers have different real estate to work with, but when you are designing an ideal UI for your app think also about the different use cases that users on mobile versus desktop computers will have. Don't just think "how do I make this work on small and large screens". For example, consider an email campaign management app. On desktop the UI would likely be optimized for creating new email messages or templates and bulk loading and editing of email lists. On a mobile device the UI would be more geared to checking the status of email campaigns: open rates, bounceback rates, unsubscribes. Design a UI that makes the most sense for your users on both platforms.

Now, if the UI is basically the same except for layout, then Responsive Web Design techniques could be a good fit. You can use media queries to adapt the layout of the app on different devices.

However, you might still not choose to go responsive. Why?

You might want to optimize what is downloaded on mobile devices. Not only to achieve a smaller download size but also to exclude running JavaScript code that would be a performance burden on mobile devices.
You want the flexibility to diverge the UIs in the future. Sure, today, maybe before you even have any users, you think that the ideal mobile and desktop UIs only differ in layout. But apps should evolve based on feedback from users and as they grow new capabilities. (This point might actually be the nail in the coffin for me regarding responsive SPAs. It seems far more pragmatic to start by having separate mobile and desktop UIs.)

Other recommendations

Only two device classes: phone and desktop (or small and large)

There used to be such a clear cut divide between phones and tablets, but any more I don't see much point in developing separate UIs for them. They share a lot of the same considerations:

modest computational resources
on mobile networks
access to sensors like GPS

I think it is sufficient to just have two device classes.

One thing that does seem reasonable is to use responsive web design techniques to have your mobile UI adapt to larger screen area. For example, you could implement the kind of UI like in the iPad Mail app where in portrait you see only the email message but in landscape you see a list of emails in that folder on the left and the email message on the right.

Also, allow the user to switch between the phone and desktop UIs if they desire. A theme running throughout these blog posts is to try to not make any hard assumptions and this is, to me, one of the big advantages of the device class approach. You might think that the user will best be served by the mobile UI but that user may want the desktop UI. (This also dovetails nicely with thinking about different use cases on mobile and desktop: the user may be on a desktop computer but want to use the mobile UI because it is optimized for the kind of task the user currently has in mind.)

Make everything optimized for touch

Whether you go responsive or take the device classes approach, make everything optimized for touch. Size controls so that they can be tapped on and respond to touch events.

An alternative to responsive webapps: Device Classes

2015-02-08T08:49:00.000-05:00

This week I spent some time with Boris Smus' article, A non-responsive approach to building cross-device webapps. As the title suggests, Boris presents an alternative to using media queries and responsive design for building webapps that work on a range of devices. It's a good article and I recommend reading it. In this blog post I'll review his arguments and give my thoughts on the matter.

To start with, Boris sees a few problems with Media Queries (or at least, with using just media queries to adapt layout for different screen sizes):

All devices get the same assets: the same JavaScript, CSS, images etc. So there is a good chance that devices are downloading a lot more than they would absolutely need to.
All devices start with the same DOM. To get the DOM to look one way on one device and look another way on a different device could lead to overly complicated CSS.
Not much flexibility to customize the UI for different types of devices. You can do it with a media query approach but if you have a mobile view that is just completely different from a desktop view, you will have duplicate views and the application code has to be careful to handle both views at once, depending on screen size. That is, while creating a custom view for a certain type of device, you have to think about how it will work for all other types of devices.

Smus recommends developing separate UIs for three different device classes:

mobile phones (small screen width + touch)
tablets (large screen width + touch)
desktops (no touch)

He suggests using device width and whether the device is touch enabled to distinguish between these device classes. How reasonable are these criteria?

As one of the commenters mentions, hindsight is 20/20. We live in an era of touchscreen desktop Windows 8 computers, and they don't appear to be going anywhere. We can no longer assume that lack of touch support equals desktop or vice versa. One of my big takeaways from this whole investigation is that all controls should be designed to be touch friendly.

What about the small screen/large screen divide? As I wrote in my previous post, we now have many large phones and small tablets such that the height of a large phone can easily exceed the width of a tablet. I still think a line can be drawn somewhere and I do think that it is useful to design a mobile friendly version of a webapp. But that line is continually moving and blurring.

Okay, now that we have 3 device classes (personally I only see two: mobile and desktop), what does Smus recommend for detecting and serving up these different experiences? Smus compares doing server side and client side detection and comes down on client side detection, mostly because it is feature detection based (more future proof) instead of user agent based. I agree there.

Smus suggests using Device.js (apparently one of his open source projects) to do this client side detection.

He also suggests using a MVC framework and only making separate View classes for the difference device classes. This allows you to get a lot of reuse while also being able to fully tailor the UI for a particular device class.

Overall, I'm impressed with this approach. If your application is best implemented with a different UI on mobile versus desktop, I think this is probably the best approach. Responsive Web Design seems to be a good fit only when the UI is basically the same on mobile and desktop with only the layout needing to be a little different. For example, at Walker Information, we have a survey application. On mobile and on desktop, the essential UI is the same, with only layout differing. Each page has a list of questions and controls for providing answers, with Back and Next buttons to navigate through the survey. This is a good candidate for being designed responsively. As a counter example, consider something like a webapp for MailChimp. On desktop it might be optimized for creating emails and setting up campaigns whereas on mobile the UI might be quite different and be focused on monitoring open rates, bounceback rates, etc. In this case, having two completely different apps would be a better fit.

There are some downsides with this separate app for device classes approach:

If the device class is part of the URL then bookmarks, shared links would include it as part of the URL. It would be nice to have canonical URLs.
Separate views for the device classes is extra work and has its own maintenance overhead
Doesn't respond to orientation changes or browser resizing
- However, it would be possible to combine both approaches. You might create a separate view for the mobile device class that itself uses media queries to adjust the UI between phone-like sizes and tablet-like sizes.

On a closing note, there is one other thing I like about Smus' approach. He recommends having links in the app to the different device classes. This way if you are on a mobile phone and really want the desktop view, you can get to it. I think this is in line with the thinking from the last blog post that challenges the consensual hallucination that we as web developers tend to participate in. Our assumption about what is mobile, what is a desktop computer are being challenged all the time. It would be good to make fewer assumptions. Letting a user switch to a non-default device class, to me, fits in with that line of thinking. We only have a limited understanding of the kinds of devices that exist today. Hopefully the devices that arrive in the future will surprise us and challenge our assumptions. And hopefully our webapps will be ready.

Additional Resources:

Really liked this post by Brad Frost that Smus links to. He makes the point that while media queries are great, the most important thing to optimize on mobile is performance.

Researching Responsive Webapps

2015-01-18T20:35:00.000-05:00

In a previous post I wrote about my initial thoughts regarding responsive Single Page Applications (SPAs). I've now done a bit of digging to find out what other folks think about this topic.

Among the blog posts I read I found Jason Grigsby's series of blog posts Responsive Design for Apps especially interesting.

Consensual Hallucination

In the first blog post in this series, Jason makes the case that web developers and web UI framework authors have been participating in a consensual hallucination regarding what phones and tablets and desktop computers are limited to, just as we once assumed desktop browsers were 960 pixels wide. Web UI frameworks tend to have a library of mobile widgets (e.g, jQuery Mobile) and a separate library of desktop widgets (e.g. jQuery UI). The reasoning given by framework authors is that phones and tablets and desktops are fundamentally different platforms. But what are these fundamental differences? A cellular radio? The answer isn't clear and Jason is dubious that a good answer exists.

Jason looks at the size of phones and tablets and points out that the height of the larger phones out there easily exceeds the width of the smaller tablets available. His article was published in early 2013 and since then the gap has only narrowed. In fact Jason at one point says

The small gaps that exist are either things that seem inevitable (high-dpi on large screens) or are so small to be inconsequential (does it matter that we don't have six inch displays?).

And of course, we now have 6-inch phones and 6-inch tablets.

There's no clear line between phones and tablets, but what about desktops? We used to be able to assume that touch was a fundamentally distinct mode of interaction on mobile devices. However, Windows 8 and all of the touch screen desktop and laptop products that are built for it obliterates that assumption. He points to research to suggest that touchscreen desktops are not a fad. I've yet to have a chance to play with a Windows 8 touchscreen device myself but I agree. I have to believe that eventually Apple will have to catch up too.

One of the key takeaways for me from this article is that every application should be designed for touch interaction. Primarily this means making targets big enough to be easily tapped on with fingers. Because of Fitts's Law, desktop users using a mouse will also benefit because these larger targets are easier to hit.

Making desktop app responsive

In Jason's second post he looks at a typical desktop app and tries to reimagine it as a responsive web app.

One of the problems he ran into is that if you take a desktop app design and try to make it responsive, you kind of run into a brick wall. He starts making progress when he takes a mobile first strategy. He designs a version of the web app that is optimized for mobile.

Once he has an optimized mobile design, he then looks at how it maps to the desktop app and finds that it maps pretty well. That's important for a responsive web app; each screen in the mobile design needs to be able to map to a corresponding screen in the desktop design. If there isn't a mapping, that is, if the mobile design is not just a different layout compared to the desktop design, then responsive web design probably won't work.

Finally, he takes another look at the desktop design and rethinks it in terms of the mobile design. This is also an important step in evaluating if responsive web design is feasible. For the mobile design he had to compromise in some places and display less information than on the desktop design. So its important to step back and look at if these mobile design components can be used in the desktop design.

Desktop and mobile design patterns

In the third part of the Jason's series Jason looks at how desktop operating systems have been incorporating mobile design ideas. In particular he looks at Apple's Mail app on iPhone, iPad and Mac OS X.

The iPhone Mail app uses a nested doll design pattern: moving froma list of items to greater detail or sub-lists of that item. On the iPad, we see a slightly different pattern, what has been called the bento box pattern: the list of email messages is displayed on the same screen as the detail. The iPhone and iPad app actually share views (for example, mail accounts and folders listing screens).

On Mac OS X, the Mail app there shares a lot of similar design elements although it does have a different look. One could definitely imagine there being a single Mail app that runs across all Apple devices and that adapts to the available screen real estate.

To me it is a little bit of stacking the deck to use the Mail app. Because information in the Mail app is arranged hierarchically (mail accounts list, folders list, messages list), it is not too hard to design a responsive Mail app. But not all apps are so simple. Word processing apps tend to have a main content area and several controls for affecting layout and formatting. A mobile word processing app design would be quite a different design, not likely to share much with its desktop counterpart.

Also, Jason only looks at views that display lists of accounts and emails and the views that display the email itself. That is, he only considers the views related to reading email. The desktop Mail app includes formatting options and stationary options when composing email, which would take up too much real estate on mobile. This is because on mobile users are typically more interested in reading and filing and flagging and deleting email. On mobile users only need to be able to write short responses, typically. On desktop the email composing needs are very different.

Nevertheless, I think his conclusion that

responsiveness for apps is inevitable

is mostly true. Responsive web design can be a good fit for some apps and even apps that are better served by different UI designs on mobile and desktop will benefit from responsive design techniques on mobile (for example a mobile UI that responds to more real estate on a tablet versus a phone).

Conclusions

I find Jason's arguments compelling. The idea that phones are fundamentally different from tablets and desktops and so require different UI frameworks and separate apps is undermined by the evidence that not much actually separates these different devices in terms of technical capability.

However, one thing that I think is missing a little from the discussion is how these different devices are used and what they are used for. Yes, technically, there isn't much difference between phones and tablets and desktops except screen size. On the other hand, users on mobile devices may have different tasks in mind that they want to accomplish versus users on desktop devices. As I mentioned above regarding the Mail app example, mobile users mostly want to read and deal with email by flagging, filing, deleting etc. Composing longer or more format heavy emails are saved for when the user is at a desktop computer. Now, this isn't a big difference in goals for mobile and desktop users for this particular app, but for certain apps mobile users may have very different goals from desktop users. This needs to be kept in mind when designing optimal desktop and mobile UIs. I'll expand on this a bit in future posts, but to me this is one of the most important reasons why you might want separate mobile and desktop apps.

Initial thoughts on Responsive Single Page Applications

2014-12-20T14:24:00.000-05:00

Is it feasible to build a responsive, mobile-first Single Page Application (SPA)? Here are my initial thoughts on the feasibility and challenges of building a responsive SPA. I plan to do more research in the coming weeks to hopefully answer this question more completely.

I was recently working on a mobile version of FuelMyRoute. I started by using jQuery Mobile and Backbone, but I found trying to use jQuery Mobile as a UI framework frustrating so I decided to give the Bootstrap CSS framework a try. I was able to convert my code over to Bootstrap fairly easily, but I started reading about and thinking about the responsive features of Bootstrap. This got me to thinking maybe I could make a responsive Single Page Application, one website that would work well on mobile devices and on desktop computers.

The benefits are pretty obvious I think. I don't relish the idea of maintaining two separate web applications. Especially when a lot of the non-UI code would be very similar. I could get a mobile site for my application while at the same time updating and modernizing the existing desktop site. That's a huge win!

I should probably define what I mean by responsive SPA. First of all, a Single Page Application is a web application where there is only an initial full page load. From that point forward AJAX is used to interact with the server to fetch data (e.g. get new mail) or to perform server side actions (e.g. send an email). The DOM is manipulated as appropriate in response to user actions and requested information. A responsive SPA is one where the UI of the SPA changes based on the size of the viewport, so that it is more appropriate/usable on smaller viewports but also can adapt and take advantage of more screen space on larger viewports. Responsive to me means also taking a mobile-first approach to web application development, where the mobile phone/small tablet use case is given primary (or at least equal) consideration.

But, I don't really see or hear much about responsive SPAs. I'm talking strictly about web applications, not web sites. If you are building, for example, a blog, then there is a lot of advice and support for making it responsive. However, for applications, it's different. The received wisdom is that it is better to have two different sites, one for mobile and one for desktop. Why? This is a question I want to answer along with the following:

What are the problems/tradeoffs that are encountered when making a responsive SPA?
Is it possible to use only CSS, only media queries to switch between different layouts for mobile and desktop usage? Or would it be necessary to have the JavaScript code be aware of whether the application is in mobile or desktop mode? (Ideally the responsiveness would be implemented in CSS only)

In this blog post I cover my initial thoughts about how a responsive SPA could work and what the challenges are likely to be.

Responsive Mobile UI Patterns

How would this work in practice? In this section I'll go over a couple of common mobile UI patterns and how they would adapt to a larger viewport.

Separate "pages" (mobile) vs in-page controls (desktop)

Sometimes the ideal view on mobile is very different from the ideal view on desktop. A common pattern here is that on desktop you have enough room to display all controls on the same screen, but on mobile you might want a separate full page view for certain actions. For example, imagine an airplane flight search application. On desktop you could have the fields for departing city and arriving city and dates on one page and display the results under those controls. On mobile, there isn't enough room for this so you would rather have a separate full page view for specifying search criteria.

In some ways, this is the least ideal situation. It is always better to be able to reuse the same controls and just style them differently using media queries. However, we must anticipate that this might not always be possible and think about what we could do in that situation.

To accomplish this, we could simply include the mobile full page alternate view in the page, hidden unless the width of the page is wide enough. By default, the mobile view is hidden.

#mobile {
    display:none;
    background-color: #fff;
    z-index:1000;
    position: absolute;
    top: 0;
    bottom: 0;
    left: 0;
    right: 0;
}
@media only screen and (max-width: 480px) {
    .desktop-only {
        display: none;
    }
    #mobile {
        display: block;
    }
}

I created a very simple demo of this concept using the airplane ticket search example. In practice, you would want to have your application code add and remove CSS classes from a top level element to drive hiding and showing different views, but I've left that sort of thing out.

This "separate page" view could possible have a use on the desktop layout. You might have a situation where not all controls fit on the desktop layout so the same view to show all controls can be used on mobile and desktop. On mobile it might be styled as a full page view, whereas on desktop it could be styled as a modal popup.

Data binding is a little complicated in such a situation. Ideally, if the user changes the size of the browser window then switching from "mobile" to "desktop" or vice versa should be seamless from a user input perspective. Using the airplane ticket search example, if I am in the "mobile" view and I type in a Departing from city and then decide to expand my browser and get the "desktop" view, then ideally the Departing from control in the "desktop" layout should be populated with what I had typed on the "mobile" view. This means that I need to bind to the keypress event and update my model as each key is typed in Departing from and keep the "mobile" and "desktop" Departing from fields in sync.

Another challenge with this approach is that you, obviously, have two different views that have to be maintained. Arguably, this is one of the benefits of adopting MVC in the first place: your models are independent of views and models can have more than one view. However, it is still something extra that has to be maintained. It is probably better than having two separate sites though.

List and detail views on separate pages (mobile) vs both on the same page (desktop)

A common pattern with mobile apps is that you have a view(s) that display lists of data and tapping on a list item takes you to a view that displays details for that item. Examples include inbox listing/email detail and contact listing/contact details.

On desktop however there is enough space to show both the list and the detail, typically with the list on the left hand side and the detail view on the right. For example, an email client.

Media queries can be used to achieve both of these layouts. One nice thing here is that the same views are used on mobile and on desktop. Its just on mobile they are separate "pages" and on desktop they are all on one page.

How would you achieve this with media queries? I won't flesh out an entire example here, but I will outline how it would be done. The key I think is to have your SPA router add/remove CSS classes to a root element of the DOM. When the "list" class is added to the root element, the mobile media query will make just the list view visible, hiding the detail view. For desktop, there is no additional work needed. Likewise, when transitioning to the detail route, the "list" class is removed from the root element and a "detail" class is added. The mobile media query would then hide the list view and make the detail view visible. On desktop, the presence of the "detail" class on the root element might cause the currently selected item to be highlighted.

One challenge that this approach highlights (and this was true of the "separate view" UI pattern above) is that although on mobile the user is seeing only one view at a time, those other views are still there. For example, in an email client app, only the detail view may be visible, but the list view is still there and still responding to model updates. So for example, if you have a periodic check for new email, then the list view is updating to display new email received. This is more of a problem for mobile where off screen updates may cause performance to drag. On desktop the presence of alternate views that aren't on screen is unlikely to cause much of a problem.

Challenges with doing responsive SPA

Some of these challenges were mentioned above. Here I'll summarize them and also discuss how to address some of them. Not having experience developing a responsive SPA, this is mostly speculation about what I anticipate would be challenges building one.

Sizing of controls

It's possible to use media queries to size controls differently. You could for example make buttons large, more "tap friendly" on mobile screens and smaller on desktop screens.

However, one would have to assume that small screens are tapped on and large screens are clicked on. And that assumption isn't valid in a lot of cases. For example, a mobile phone might have a stylus that is able to make very precise touches. As another example, there are now several Windows 8 devices, some that are tablet/laptop hybrids, that are basically desktop devices but allow for touch interaction.

So I think a reasonable approach is to just size all controls for tapping. The tradeoff is that on desktop the controls are going to be "fatter" than necessary, meaning you won't be able to fit as many controls on the same page, but I don't think there is any reasonable alternative unless you want to aggravate uses with large touch screens.

Also, the fact that you can't have as many controls on a desktop view is not necessarily a bad thing. It will lead to a simplification of the UI, which will probably end up being easier to use.

Off screen view updates on mobile

I mentioned this one above. What can be done? For one, I think some testing and validation that this causes an issue is necessary first. Are DOM updates that are off screen as intensive as on screen ones for the browser to handle? Maybe, hopefully, not. I think it can very much depend on the application and might only affect certain views but not others.

If it becomes a problem I think one thing that could be done is to delay re-rendering the view if the view is off screen. Whenever it is ready to be brought back on screen the view could first be fully re-rendered. The problem here is that JS code now needs to know if the app is in "mobile" mode or "desktop" mode and so far I've been trying to keep the differences purely in CSS media queries.

Duplicate UIs

This one is mentioned above too. This is most applicable when the "mobile" version of the app needs a completely different view from the "desktop" version.

To mitigate this, first, obviously, try to use the same views for "mobile" and "desktop" and simply have them laid out differently.

Also it should be said that the duplication of effort and maintenance is probably not nearly so much as having two separate sites.

Also as mentioned above, there is also the data binding consideration: you'll want to keep the "mobile" and "desktop" views in sync at all times because the user could at any time transition from one to the other. In practice I think this requires only a little extra effort. See the discussion on listening for keypress events above.

Conclusion

Well that's it for my initial thoughts. I hope to investigate this further and try some of these techniques out.

A Backbone-JQuery Mobile skeleton project -

2014-06-24T23:04:00.000-04:00

I've been playing around with integrating Backbone and jQuery Mobile. I'm planning on using them as the framework for implementing a mobile version of FuelMyRoute.

I started with Christophe Coenraets' backbone-jquerymobile sample app and made changes to bring it up to date with the most recent versions of jQuery Mobile and jQuery. I also made a couple different design choices. In this post I'll go over the changes I made.

jQuery.on

A couple of jQuery's event listener methods were removed in 1.9: live and bind. I updated several event listeners, like the mobileinit event listener, to use jQuery.on instead.

mobileinit

To configure jQuery Mobile, you set up a listener for the mobileinit event and set properties on the $.mobile object. Here's what I have so far.

$(document).on("mobileinit", function () {
    $.mobile.ajaxEnabled = false;
    $.mobile.linkBindingEnabled = false;
    $.mobile.hashListeningEnabled = false;
    $.mobile.pushStateEnabled = false;
    $.mobile.autoInitializePage = false;
});

This is identical to Coenraets' config except that I also added setting autoInitializePage to false. We'll get to that in a bit. The other settings are there to turn off the routing and link hijacking behaviour in jQuery Mobile so we can use Backbone for routing instead. Coenraets explains in his blog post on the topic and the jQuery Mobile project also has notes on integrating with Backbone.

autoInitializePage

By default jQuery Mobile will call initializePage() when it starts up. initializePage() is important because it initializes the pagecontainer and sets up navigation events. It will try to find the first div with data-role="page" and change to that page. If there isn't a page in the DOM, it will create an initial dummy page. This generally works out fine if you are using jQuery Mobile in the more typical way where you have multiple pages defined in the one page. However, with our Backbone integration, there isn't any page until the router runs and injects the first page into the DOM so it doesn't make sense to automatically call initializePage().

So what I did was set autoInitializePage to false. The Router will call initializePage() after it adds the first page to the DOM.

var AppRouter = Backbone.Router.extend({

    ...
    changePage:function (page) {
        // Render and add page to DOM once
        if ($('#'+page.id).length === 0) {
            $('body').append(page.render().$el);
        }
        if (this.firstPage) {
            // We turned off $.mobile.autoInitializePage, but now that we've
            // added our first page to the DOM, we can now call initializePage.
            $.mobile.initializePage();
            this.firstPage = false;
        }
        $( ":mobile-pagecontainer" ).pagecontainer( "change", page.$el,
                { changeHash: false });
    }
    ...
});

Managing Pages as Views

There are a couple different ways to go when managing page Views. You could remove them and recreate them each time or you could not remove them and just let jQuery Mobile hide and show them. Coenraets went with the "recreate each time" approach. I went with the approach of letting jQuery Mobile hide and show pages. My page Views are rendered and then added to the DOM once.

I did this because it seems a better fit with jQuery Mobile. Also I think there is a performance benefit on mobile to keeping DOM manipulations to a minimum.

However, I am still concerned about my page Views being bound to models even when they aren't being shown. Offscreen pages might re-render unnecessarily due to model/collection updates.

I might add to my router the ability to let pages know when they are being hidden or shown and that would allow a page to deal with offscreen rendering performance issues. One thing a page View might do is unbind its listeners when being hidden and rebind them when being shown again, which might be appropriate if intermediate events can be safely ignored. Another thing a page View might do when not being shown is continue to listen for events but defer any re-rendering until actually shown. I'll explore this more as needed, but I need a real world example to guide the design.

Enhancing pages

I did a little exploration into how you would handle jQuery Mobile enhancement if you re-rendered page. Basically, whenever render() is called, the page needs to be re-enhanced. jQuery Mobile will automatically enhance a page the first time it is changed to, but after that you need to call it yourself. I implemented a View base class I call PageView that has an enhance method. It allows you to implement render like so:

render: function () {
    // do some rendering
    // ...
    this.enhance(); // See PageView.enhance for details
    return this;
}

Keep in mind, though, re-rendering and re-enhancing the entire page is discouraged for performance reasons.

Minor stuff

$.mobile.changePage is deprecated. I switched to the change method on the pagecontainer. See the changePage method on the AppRouter above.
Instead of <div data-role="content">, use <div class="ui-content" role="main">
Contrary to Coenraets, I didn't find I needed to disable the first page transition, so I removed that code.
I also switched to project to use Bower and RequireJS to manage dependencies.
I never got around to dealing with transitions. Delegating routing to Backbone means you miss out on the declarative transition stuff in jQuery Mobile. I'm thinking that eventually I might add a transitions hash to the Router that would allow you to define page to page transitions, something like
```
transitions: {
    'page1:page2':  'slide',
    // etc...
}
```

Git client setup

2014-06-01T09:37:00.000-04:00

These are some settings and configuration I've found useful so far while working with Git.

Git global configuration

git config --global user.name "Marcus Christie"
git config --global user.email marc.christie@gmail.com

Can also set an editor to use for commit messages

git config --global core.editor gvim

Or with MacVim on OS X

git config --global core.editor 'mvim -f'

However, I think I prefer to edit commit messages in the terminal.

You can also use gvimdiff as a merge tool, but I haven't tried this yet.

Excludes file

Set up a global excludes file in ~/.config/git/ignore. My entries so far:

*.swp
.DS_Store
Session.vim

Whitespace

On Windows you want

git config --global core.autoclrf true

I think this is the default on Windows also, so this may be unnecessary.

Credential helper

This tip is mainly for when you are working with a repo over HTTPS, for example, with GitHub, and you authenticate with a username and password. You don't want to have to type passwords over and over. For this you can specify a credential helper that will securely store your password. On OS X:

git config --global credential.helper osxkeychain

On Windows, download git-credential-store. Then start up Git Bash, go to the directory where you downloaded the executable and then run it from the command line

$ git-credential-winstore.exe

Aliases

Shortcuts so you can run git ci -m "fixed bug" instead of typing out commit

git config --global alias.ci commit
git config --global alias.st status
git config --global alias.co checkout

Bash completions

On Windows, Git Bash comes with these already configured. On OS X, I downloaded git-completion.bash, dropped it in ~/bin and in .bash_profile I have

## Git completions
source ~/bin/git-completion.bash

Web viewer

On OS X:

git config --global instaweb.httpd webrick

Now you can start up a web viewer with

git instaweb

As a Mercurial refugee, I got used to hg serve so I like to have a web view.

Haven't tried doing this on Windows yet.

push.default

Set push.default to simple:

git config --global push.default simple

This setting affects what happens when you do a git push without specifing a remote or branch to push. With simple git will push the current branch to the upstream tracked branch. This mode also is the new default in Git 2.0.

Make sure that when you first push a branch to a remote server that you also set it as the upstream tracked branch. You can do that with the -u option:

git push -u origin mybranch

From then on every push can be done simply with

git push

merge.defaultToUpstream

Set merge.defaultToUpstream to true

git config --global merge.defaultToUpstream true

This setting affects what happens when you do a git merge without specifying a branch to merge from. With this set to true, git will merge in changes from the upstream remote tracking branch, which is generally what you want.

Anything else?

Are there any other things you do to configure Git on a new machine? Let me know in the comments or on Twitter.

Backbone Overview

2014-05-26T13:13:00.000-04:00

Backbone is a JavaScript Model-View-Controller (MVC) library that can be used to create single page applications (SPAs). This article introduces the most important concepts in Backbone (Models, Collections, Views, Events, Router and Sync) and how they relate to building a client side JavaScript application.

What is Model-View-Controller (MVC)?

Model-View-Controller might be one of the most misunderstood software patterns ever. I'm not even sure I really understand what the original idea was (at least, what it meant to Smalltalk developers when first developed at Xerox PARC), and of course it has evolved over time into several different closely related ideas.

So this is far from authoritative, and I'll try to keep it simple. To me, MVC is a way to organize the implementation of a user interface in a way that separates concerns. Here, at a high level, are the various parts of a MVC framework:

Model - this is the representation of data that models the domain of interest. For example, for a TODO application, a model might be a TODO item. But Models aren't just data structures, they also contain the domain logic. A TODO item might expose a complete method that knows how to mark a TODO item as completed and properly manage any additional details related to task completion.
View - views are visual representations of models. A view reacts to changes in a model by updating the view to reflect that change.
Controller - controllers handle user input, both displaying views that the user requests and handling keyboard and mouse events. Controllers typically translate user input into updates on Model instances.

The goal is separation of concerns. Models know nothing of views; in a web application, models would have nothing in them relating to HTML or CSS, for example. Views know only how to represent a model, but they contain no business logic. Views respond to changes in a model, but know nothing of what the user is doing. Controllers are the only place in the application to handle things like navigation through the application, display of multiple views at once, transitions between views and translating user actions into model updates. But controllers don't contain business logic.

How does Backbone relate to traditional MVC?

The Backbone API has the following types:

Events
Model
Collection
View
Router
Sync

Where do each of these concepts fit into the traditional MVC pattern?

Backbone.Events are the primary mechanism for loose coupling between the models and views. Backbone Views bind to changes on the Models or Collections.

Backbone.Model and Backbone.Collection are the M of MVC: these types can be extended to provide the data and the implementation of domain logic for the application.

Backbone.View classes are a little V and a little C when compare to classical MVC. Backbone.View contains a render method that is responsible for generating/updating the DOM that is the view of the model, and for doing so it is typical to have a template. The template is more the V of MVC than the View class. Backbone.View also acts as a Controller in that it binds user events to methods on the View class that will update Models.

Backbone.Router is also fairly controller-ish in the traditional MVC understanding. The Router responds to user requests for specific URLs and can handle them by showing the right type of Views and by making sure that Model instances are available.

Backbone.sync is the RESTful persistence mechanism for saving/updating models. In Backbone, the models (Model and Collection instances) know how to persist themselves (which endpoint to call, how to serialize/deserialize, etc.). In that sense, sync is more in the M of MVC than anything else, but I'm not sure that persistence is in the scope of traditional MVC. (Another way to think of it is that sync is a translation layer between a client side model and a server side model, which are just two representations of the same domain object.)

Events

Backbone.Events provides standard event listening and triggering behavior.

Events.on(event, listener) adds a listener
Events.off(event, listener) removes listener
Events.trigger(event)

Backbone.Events can also be mixed in to other objects or classes via underscore's _.extend mechanism, and it is mixed in to Backbone.View, Backbone.Model etc. So these methods are available from most Backbone types.

By convention, Backbone Events are often namespaced. For example, you can listen to all changes on a model with model.on("change", listener), but you can also listen to just a change of the property "name" with model.on("change:name", listener).

But keep in mind there is no extra support in the implementation of Backbone.Events for namespaced events really, not like jQuery namespaced events. "change:name" works because Backbone.Model dispatches an event for each property that changes and also a "change" event. As another example, if you listen for "foo" and a "foo:bar" event is triggered, your event listener will not be called. You would have to trigger both "foo" and "foo:bar" in your code if you wanted to support namespacing.

One problem with setting up event listeners, especially with a View listening to changes on a Model, is that the object being listened to has a reference to the listener. For example, let's say you have a ContactView that is listening for changes to a Contact Model instance. If you dispose of the ContactView but forget to remove all of the event listeners, then the Contact Model still has a reference to your ContactView. This leads to a couple problems. First, your ContactView instance won't get garbage collected, so your app is now leaking memory. Second, whenever the Contact Model updates it will continue to call the event listener on the zombie ContactView and update it, so you have a lot of unnecessary code execution (and debugging this can get really confusing when you see code executed several times instead of just once as expected).

To solve this, Backbone.Events has two helpful methods, listenTo and stopListening. listenTo has this method signature

object.listenTo(other, event, callback)

Whereas you call on on the object you want to listen to, listenTo is called on the listening object. The advantage here is that the listening object can keep track of all of the listeners and can remove them all at once, which is what stopListening does.

One other note about events. In a Backbone app, you typically have two types of events: Backbone events and DOM events. DOM events are typically set up for a View in the events hash, which we'll get to later. When using the events hash, this refers to the View, pretty much what you expect. However, keep in mind, if you programmatically use the jQuery API to bind to DOM events then this refers to the DOM element.

Model

To create a Backbone.Model, extend the Backbone.Model class. You can specify default values for various properties.

app.Todo = Backbone.Model.extend({

    // Default attributes ensure that each todo created has `title` and `completed` keys.
    defaults: {
        title: '',
        completed: false
    }
});

To instantiate a Model instance, call the constructor and pass in the attributes for the instance. Any defaulted attributes that aren't specified will receive their default values.

Models have get and set functions for reading and writing attribute values. As mentioned above, calling set("myattr", newvalue) causes two events to be dispatched: "change:myattr" and "change".

Models also have a special property called id which uniquely identifies a Model instance. This can be set to an integer or UUID string. You pass it in the attributes hash when creating a Model instance. You can also set the idAttribute property on the Model class if you have a property on your Models that can be used to uniquely identify instances.

Collection

Create a new Collection by extending Backbone.Collection. You typically set the model property to the Model class of this collection.

var TodoList = Backbone.Collection.extend({

    // Reference to this collection's model
    model: app.Todo,

});

Collections redispatch Model events, so you can simply listen, for example, to "change" events on the Collection and you'll be notified whenever a Model instance changes.

You can add and remove Models to and from a Collection. These methods will dispatch "add" and "remove" events. Removing a model occurs when you call remove and pass in a Model instance that has the same id as a Model instance already in the Collection. Collections also have a reset method which updates the Collection all at once and dispatches just a single "reset" event, which is more efficient for example when initially loading a Collection.

Collections have several Underscore methods, like _.each, that you can call directly.

Collections are typically where you will set up the RESTful URL by setting the url property. You can then call fetch to retrieve all of the model instances in the collection and add them to the collection instance. We'll look at this more in the Sync section below.

View

Backbone View's always have a DOM element that they can render into. By default Backbone.View will create the DOM element for you, but if the DOM element you want to attach this View instance to is already in the page you can set el to a selector for that DOM element

var MyView = Backbone.View.extend({
    el: '#myview',
    //...
});

If you let Backbone create your DOM element, you can specify tagName, className, id and attributes to be set on that DOM element and Backbone will apply them. That is, if you specify a tagName of li and a className of todo-item, Backbone will create a <li class="todo-item" /> element in the DOM for you.

As a convenience, View's also have a $el property which is the jQuery wrapped reference to the View's DOM element.

A typical thing to do when you initialize a View is to pass it the model or collection instance you want it to bind to. In the View's initialize method, you can then bind to changes to that Model or Collection:

var TodoView = Backbone.View.extend({
    tagName: "li",
    className: "todo-item",
    initialize: function(){
        this.listenTo( this.model, "change", this.render );
        //...
    }
});

var todo = new TodoView({model: aTodo});

Besides binding to events on the Model, a View typically binds to DOM events. This is one of the controller-ish things a Backbone View does. To bind to DOM events, specify the events hash when creating the view. The keys in the events hash are in the form of 'eventName selector' and the value of each is the name of a function (or a function reference instead if you want).

var TodoView = Backbone.View.extend({
    events: {
        'click .toggle': 'toggleCompleted',
        // ...
    }
});

Inside of a DOM event handler, this refers to the View.

To actually render a view to the page, you provide an implementation of render. The job of render is to update this.el however necessary. The typical way to do this is to have a String based template, by default, an Underscore template. You'll set template in a view to a template function that takes an object with the properties of your model and returns a String of HTML with the model properties applied.

There are several approaches to how to organize your templates, but the simplest way is to put them in the web page inside a <script> tag with type set to text/template.

<script type="text/template" id="template-id">
    <input type="checkbox" <%= completed ? 'checked' : '' %> />
    <label><%- description></label>
</script>

In your View class, you can read in the template once with

//... inside View class
    template: _.template( this.$('#template-id').html() );

Then you can implement render like so:

//... inside View class
    render: function() {
        this.$el.html( this.template( this.model.toJSON() ) );

        // Anything else you might want to do...

        return this;
    }

Note that this.$ is a reference to the jQuery object. Also, render returns this so that parent View components can render child View components and then include them in themselves. For example, a container of these TodoView instances might do something like:

    render: function() {

        todos.each( function(todo) {
            var todoView = new TodoView({model: todo});
            this.$el.append( todoView.render().el );
        }
    }

When you are done with a View, you can call remove on it. This removes this.el from the DOM and also calls stopListening to remove all of its event listeners.

Router

Backbone.Router allows mapping URLs to actions and events. You create a router instance by extending Backbone.Router. You can specify a routes hash that maps url patterns to function names (or function references). This is somewhat similar to the events hash in a View.

Route url patterns can use the :param syntax of the *param splat syntax. :param is used to match a part of a URL. A splat matches the rest of the URL.

var Router = Backbone.Router.extend({

    routes: {
        '/search/:query': 'search',
        //....
    },

    search: function(query){
    }
});

As an example of how you would use a Router, consider an email application. When the user navigates to an email folder, the app will display a list of the email messages in that folder. You would set up a route for an email folder, maybe like so:

routes: {
    '/folder/:folderId': 'goToFolder'
}

Then when a user clicks on the email folder, you can call Router.navigate('/folder/123', {trigger: true}). If you want to handle updating the view to show the folder and just have the router update the URL, you would not pass {trigger: true}.

So now you need to kick things off for your app and have your Router handle whatever the current URL is (for example, if the user bookmarked that email folder link and navigated to it directly). To do that you call start on Backbone.history.

var appRouter = new Router();
Backbone.history.start({pushState: true});

Backbone.history is a kind of global router. It can make use of the History API, calling pushState if available, falling back to updating the URL fragment if not available. You have to pass {pushState: true} to start to make use of pushState; it is something you opt into in Backbone.

Sync

Backbone.sync handles persistence. By default, it supports RESTfully retrieving and saving models to a server, assuming a JSON API. In the simplest cases, you just define the base url on your Collections.

app.Library = Backbone.Collection.extend({
    model: app.Book,
    url: '/api/books'
});

When you call the following methods, the following URLs are invoked via AJAX:

Collection.create maps to a POST to the URL /api/books
- Collection.create is a convenience function that saves the new model to the server and adds it to the Collection.
Collection.fetch maps to a GET to the URL /api/books
Collection.update maps to a PUT to the URL /api/books/{id}
Collection.delete maps to a DELETE to the URL /api/books/{id}

There's a lot you can customize however. Models can implement Model.parse to have custom response parsing logic. You can override Backbone.ajax to customize the AJAX logic. And you can go whole hog and override Backbone.sync to completely customize how to load/persist data, for example, using LocalStorage as a backing store for your app.

Additional Resources

Backbone Fundamentals
- A lot of the code examples in this blog post come from Backbone Fundamentals. Highly recommended.
History of MVC
C2's MVC page
Namespacing events is just a convention @ StackOverflow
Caniuse.com pushState

Using Google's Places Autocomplete API to find directions

2014-05-06T22:11:00.000-04:00

I'm currently integrating Google's Places Autocomplete API into the FuelMyRoute Android app. This way as soon as a user starts typing a destination, the location will autocomplete.

The Places Autocomplete API response is something like this:

{
"predictions" : [
    {
        "description" : "Barnes & Noble, East 3rd Street, Bloomington, IN, United States",
        "id" : "5c94b4b6d6ffdc0402451f0ccacd65d04c92b1be",
        "matched_substrings" : [
            {
            "length" : 6,
            "offset" : 0
            }
        ],
        "reference" : "CoQBeAAAAIcYT-uv-ryTSOBQ8Cl3W313c9fuh-J5KCY8N0k-QDVPWGD65lIgs9ZpXar6eIMJ3ey5HL-3d1yMChPIwcO9uDSFdyl_NeHcOgpSFVfqsbBh-E_F0QfVviuZHGPicPRLsGvEXP5jC6NuBZ2-0jQnxVzRNN-6W9XaXxFURgW115mLEhD3vouWuAImM-yWSat1opedGhROZAG_tNmuisZo82H0DOvw-yqj5Q",
        "terms" : [
            {
            "offset" : 0,
            "value" : "Barnes & Noble"
            },
            {
            "offset" : 16,
            "value" : "East 3rd Street"
            },
            {
            "offset" : 33,
            "value" : "Bloomington"
            },
            {
            "offset" : 46,
            "value" : "IN"
            },
            {
            "offset" : 50,
            "value" : "United States"
            }
        ],
        "types" : [ "establishment", "geocode" ]
    },
    ...

I was then feeding the description (in the case above, Barnes & Noble, East 3rd Street, Bloomington, IN, United States) as the destination to Google's Directions API.

However, this turns out to only work sometimes. The description returned by the Autocomplete API is not necessarily detailed enough to resolve to a geocoded address.

What you need to do instead is take the reference field for a location and pass it to yet another API, the Place Details API. These request URLs look like

https://maps.googleapis.com/maps/api/place/details/json?\
    reference=CoQBeAAAAIcYT...&sensor=true&key=API_KEY_HERE

The result of which looks like this

{
"html_attributions" : [],
"result" : {
    "address_components" : [
        {
            "long_name" : "2813",
            "short_name" : "2813",
            "types" : [ "street_number" ]
        },
        {
            "long_name" : "E 3rd St",
            "short_name" : "E 3rd St",
            "types" : [ "route" ]
        },
        {
            "long_name" : "Bloomington",
            "short_name" : "Bloomington",
            "types" : [ "locality", "political" ]
        },
        {
            "long_name" : "IN",
            "short_name" : "IN",
            "types" : [ "administrative_area_level_1", "political" ]
        },
        {
            "long_name" : "United States",
            "short_name" : "US",
            "types" : [ "country", "political" ]
        },
        {
            "long_name" : "47408",
            "short_name" : "47408",
            "types" : [ "postal_code" ]
        }
    ],
    "adr_address" : "\u003cspan class=\"street-address\"\u003e2813 E 3rd St\u003c/span\u003e, \u003cspan class=\"locality\"\u003eBloomington\u003c/span\u003e, \u003cspan class=\"region\"\u003eIN\u003c/span\u003e \u003cspan class=\"postal-code\"\u003e47408\u003c/span\u003e, \u003cspan class=\"country-name\"\u003eUnited States\u003c/span\u003e",
    "formatted_address" : "2813 E 3rd St, Bloomington, IN, United States",
    "formatted_phone_number" : "(812) 331-0669",
    "geometry" : {
        "location" : {
            "lat" : 39.165632,
            "lng" : -86.49625899999999
        }
    },
    ...

You can get the latitude/longitude from geometry.location (also the formatted_address would likely work as well as a destination in a Directions API request). Now you can make a Directions API request with an exact destination.

Disjunctive Normal Form: Figuring out what part of a WHERE claused matched

2014-05-05T19:47:00.000-04:00

At work we have a way for filters to be defined by users and for these filters to trigger other actions (at a very high level, the details aren't so important for the purpose of this blog post). These filters translate to SQL WHERE clauses. I'm currently working on a project to figure out, when a filter matches, what was it in the filter that actually matched.

The problem is this. You can have a filter with arbitrary boolean logic in it. To take a very simple example, consider the following filter as WHERE clause:

WHERE
    COLUMN1 = 1
    AND (COLUMN2 = 3 OR COLUMN3 = "foo")

When you have a match, you might wonder: Was it COLUMN1 and COLUMN2 that caused the match, or was it COLUMN1 and COLUMN3? (or maybe all three matched the conditions).

So we can break this down into two problems.

What are all the possible sets of conditions that could satisfy the filter?
Which of these sets of conditions are matched?

For the first problem, we can transform the filter expression into Disjunctive Normal Form (DNF). Disjunctive Normal Form is an OR-ing of ANDs, where negation is pushed down to the "leaves" of the boolean expression tree (in other words, negation applies only to literals).

Our example above rewritten in DNF becomes:

WHERE
    (COLUMN1 = 1 AND COLUMN2 = 3)
    OR
    (COLUMN1 = 1 AND COLUMN3 = "foo")

For the second part of the problem, I can split apart this filter and apply each part separately. If (COLUMN1 = 1 AND COLUMN2 = 3) matches, then I know that those conditions are true for that match. Likewise for (COLUMN1 = 1 and COLUMN3 = "foo"). Now I know what conditions were actually matched for a given match.

How to get to Disjunctive Normal Form?

Based on what I've been reading, there are two main ways to convert a boolean expression to DNF.

Algebraic - Use the laws of Boolean Algebra, like De Morgan's law, to rewrite the boolean expression into DNF.
Algorithmic - Generate a truth table, or use an algorithm like Quine-McCluskey.

Algebraic approach

The approach is pretty simple and is a two step process:

Convert first to Negation Normal Form. This uses double negation elimination and De Morgan's Laws to push negation down to the leaves of the boolean expression tree.
Pull the ORs to the top of the expression tree using the Distributive Law.

(Credit for this approach goes to this StackExchange answer.)

Algorithmic approach

I'll give an example of this approach using a truth table. Let's stick with the current example:

COLUMN1 = 1	COLUMN2 = 3	COLUMN3 = "foo"	COLUMN1 = 1 AND (COLUMN2 = 3 OR COLUMN3 = "foo")
T	T	T	T
T	T	F	T
T	F	T	T
T	F	F	F
F	T	T	F
F	T	F	F
F	F	T	F
F	F	F	F

You can see that the first three rows of this table evalute to true, so we can convert each row to a clause in our DNF:

WHERE
    (COLUMN1 = 1 AND COLUMN2 = 3 AND COLUMN3 = "foo")
    OR
    (COLUMN1 = 1 AND COLUMN2 = 3 AND COLUMN3 != "foo")
    OR
    (COLUMN1 = 1 AND COLUMN2 != 3 AND COLUMN3 = "foo")

As you can see, this naive approach results in a rather large DNF, and this is a very simple example. To reduce this DNF to a simpler equivalent expression, you can use something like the Quine-McCluskey algorithm.

Which approach to take?

I think in general the algebraic approach is preferred if you have a boolean expession tree already for your boolean function. You can fairly simply rewrite this tree into DNF. This is the case with these SQL filters I'm working with.

If however the inputs to your boolean function are well defined (whether they are true or false) but you don't know the implementation details of your boolean function, then an algorithmic approach is going to be more appropriate.

For me, I'm going with the algebraic approach. I have the boolean expression tree for these filters I'm working with, but the "inputs" to the filter aren't so easy to get at without a lot of work. By that I mean that our system generally doesn't know that a row in a table has COLUMN1 = 1, etc., and rather the filter is just evaluated directly against a table. It would take a fair bit of work to translate criteria like COLUMN1 = 1 into boolean inputs, and to represent the criteria as boolean literals in the filter expression.

Git: How to delete a branch

2014-05-04T22:10:00.000-04:00

How do you create a temporary branch to do some work in (e.g, a feature branch), and then when you have merged it to master and are done with it, how do you delete it, both locally and remotely?

Let's create a simple repo to experiment with. We'll add just one file to it.

mkdir myprj
cd myprj
git init
vim README.md
git add README.md
git commit -m "adding a README"

Okay, this will be our "central repo". Let's clone it, create a branch and do some work on it.

git clone myprj myprj2
cd myprj2
git branch install_notes
git checkout install_notes
vim README.md
git commit -a -m "Adding some installation notes"
git push origin install_notes
# Oops, forgot to set upstream
git push --set-upstream origin install_notes

The branch install_notes now exists locally and in the "central repo". Let's merge it and then delete it locally and also remotely. Before we get started though, here are all of our local and remote branches:

marcus$ git branch -avv
    * install_notes                6a5ed4c [origin/install_notes] Adding some installation notes
    master                       27c8a05 [origin/master] adding a README
    remotes/origin/HEAD          -> origin/master
    remotes/origin/install_notes 6a5ed4c Adding some installation notes
    remotes/origin/master        27c8a05 adding a README

First, let's switch back to master and try to delete install_notes:

marcus$ git checkout master
    Switched to branch 'master'
    Your branch is up-to-date with 'origin/master'.
marcus$ git branch -d install_notes
    warning: deleting branch 'install_notes' that has been merged to
            'refs/remotes/origin/install_notes', but not yet merged to HEAD.
    Deleted branch install_notes (was 6a5ed4c).

Hmm. It gave a warning, but proceeded to delete the branch anyways. Well, let's try to check it back out.

marcus$ git checkout -b install_notes origin/install_notes
    Branch install_notes set up to track remote branch install_notes from origin.
    Switched to a new branch 'install_notes'
marcus$ git checkout master
    Switched to branch 'master'
    Your branch is up-to-date with 'origin/master'.
marcus$ git merge install_notes
    Updating 27c8a05..6a5ed4c
    Fast-forward
    README.md | 4 ++++
    1 file changed, 4 insertions(+)

Okay, now we can delete the branch.

marcus$ git branch -d -r origin/install_notes
Deleted remote branch origin/install_notes (was 6a5ed4c).
marcus$ git branch -d install_notes
Deleted branch install_notes (was 6a5ed4c).

And now my branches look like this

marcus$ git branch -avv
    * master                6a5ed4c [origin/master: ahead 1] Adding some installation notes
    remotes/origin/HEAD   -> origin/master
    remotes/origin/master 27c8a05 adding a README

CSS :empty - hiding a border when an element is empty

2014-05-03T22:29:00.000-04:00

I recently had a situation where I have an element in the DOM that draws a border around some content, but the element is initially empty and isn't populated until the user does some action. The problem is, even though the element is empty, the border (or at least, part of it) gets drawn on the page.

Let's say this is my element:

<span class="count"></span>

Well, what I can do to remove the border when the element is empty is to use the :empty pseudo-class selector:

.count:empty {
    border: none;
}

That's it. One caveat though, :empty only works if the element is completely empty, including whitespace. Firefox does have a -moz-only-whitespace pseudo-class selector, but its not standard and I'm not sure if any other browser has anything similar.

Bootstrap's Alert.js Plugin, line by line

2014-04-09T19:32:00.000-04:00

At work I recently needed to write a jQuery plugin that uses Bootstrap styling, so I looked at how alert.js is implemented, since it is a fairly small plugin. In this post I'll go over alert.js line by line, and do my best to explain what is going on. You should have a decent understanding of JavaScript and some familiarity with jQuery, but I'll assume no knowledge of how to write a jQuery plugin or anything specific to Bootstrap.

Overview

Let's start with an overview of how the Alert plugin can be used. You can find the Bootstrap Alert plugin documentation here. Essentially there are two ways to use Alerts, and this applies to other Bootstrap plugins as well

Use the jQuery plugin function directly. For Alerts this looks like this

$(".alert").alert()

// To close the alert:
$(".alert").alert("close")

Data API: use data-* attributes to configure in a more declarative style. For Alerts, the primary data attribute is data-dismiss
```
<button type="button" class="close" data-dismiss="alert"
    aria-hidden="true">&times;</button>
```

We'll see how the code in alert.js supports both of these styles.

What's this `+function` business?

Okay, let's start at the top. The first line of code is this

+function ($) {

We have an unnamed (anonymous) function, and a + in front of it. What's going on there? For the moment let's ignore the body of this JavaScript function definition and look at how this function gets invoked:

+function ($) {

    // ...

}(jQuery);

This is an example of the Immediately Invoked Function Expression (IIFE) pattern. The intent of an IIFE is to introduce stronger lexical scoping in JavaScript and to allow for some functions defined within the IIFE to remain private. There are several variations of this pattern. One way to do it is to have the IIFE return an object with references to public functions while leaving some functions private. In this case, nothing is returned. Instead, the plugin is added to the jQuery object. Because nothing is returned by the IIFE, we can use a trick to get the JavaScript interpreter to call our anonymous function immediately, and that trick is to put an unary operator in front of the function definition.

The sole argument passed to the function is jQuery for the $ parameter. Why passing jQuery as the $ parameter, why not just use $ from the global scope like so?

+function () {

    $('#foo').hide(); // etc...
}();

We could do that, but that would only work as long as $ refers to the jQuery function. There are other libraries that define the $ reference, so in order to interoperate with them we'll assume only that there is a jQuery reference in the global scope. But it's nice that we can essentially alias jQuery to $ within our plugin definition in a lexically scoped and tidy way.

`use strict`

The next line of alert.js is a String, 'use strict':

+function ($) {
    'use strict';

According to the Strict mode article on the Mozilla Developer Network

ECMAScript 5's strict mode is a way to opt in to a restricted variant of JavaScript. Strict mode isn't just a subset: it intentionally has different semantics from normal code.

Perl has something similar. 'use strict' is a way of running your JavaScript code through the interpreter in a less loosy-goosy manner. Here are some benefits of running in strict mode:

Impossible to accidentally create global variables (for example, mistyped variable names)
Severals classes of silent errors become thrown exceptions
Simplifies variable naming which allows JavaScript interpreters to better optimize code (for example, eval doesn't introduce new variables into the surrounding scope)
Several security enhancing restrictions are added

See the linked article for more information.

Alert class definition

Now for the Alert class definition. Our Alert class has a constructor and one method, close. First, the dismiss variable is defined. This is a jQuery selector that is used here in the constructor to bind to the click event from a DOM element that matches this selector. The way this works is that any DOM element that is el or a descendant of el that has a data-dismiss attribute with value alert that fires a click event will be handled by this.close:

var dismiss = '[data-dismiss="alert"]'
var Alert   = function (el) {
    $(el).on('click', dismiss, this.close)
}

Alert `close` function

The close method is defined for the Alert class by adding it to Alert's prototype. This method does the following:

Figure out the $parent element (i.e., the alert div) that should be closed. There are a few different ways to determine the $parent and we'll look at those shortly.
Trigger a custom event before closing the $parent and one after it is closed.
Use a CSS3 transition to fade the $parent and then remove it.

Finding the `$parent` to close

First, figure out the $parent element. Here's the first part of close:

Alert.prototype.close = function (e) {
    var $this    = $(this)
    var selector = $this.attr('data-target')

    if (!selector) {
        selector = $this.attr('href')
        selector = selector && selector.replace(/.*(?=#[^\s]*$)/, '') // strip for ie7
    }

    var $parent = $(selector)

    if (e) e.preventDefault()

    if (!$parent.length) {
        $parent = $this.hasClass('alert') ? $this : $this.parent()
    }
// ...

In the first line of close, this refers to the element that is the target of click event. So in the standard case where you have a close <button> inside a <div class="alert"> element, this is the <button>. However, close could be called through the plugin function, as we'll see later, so this might refer to the alert itself (<div class="alert">). For now, we'll consider the case that this refers to the close button.

The first option to check is a data-target attribute on the close button. The value is expected to be a selector. You would use it like this:

<div id="myalert">
    <button class="close" aria-hidden="true"
        data-target="#myalert"
        data-dismiss="alert" type="button">×</button>
    <strong>Holy guacamole!</strong>
    Best check yo self, you're not looking too good.
</div>

Click on the button should cause <div id="myalert"> to be closed.

The second option to check is the href attribute. This can be used likewise.

This line then checks to see if anything matches those options:

var $parent = $(selector)

If we haven't set data-target or href on our close button, or if we have but they don't match anything, then $parent will have a length of 0. That's what is checked for next. If we still haven't found $parent there are a couple more things to try.

So the third option is to check to see if $this has class alert. If it does then we assume that this is the element that should be faded and removed.

The fourth option, the default if none of the other checks matched anything, is to set $parent to the parent of $this.

Like I said earlier, it's possible for the close method to be called directly in which case $this is the alert itself. In that case, it is the third option that would typically be used for figuring out the $parent.

Custom events for before and after closing

Before actually closing the alert, close dispatches a close.bs.alert event on the $parent element.

$parent.trigger(e = $.Event('close.bs.alert'))

if (e.isDefaultPrevented()) return

The first line creates the custom event, using jQuery's $.Event and also sets it to the variable e. The name of the event, "close.bs.alert", utilizes jQuery event namespaces. This just makes it possible to listen for the close event just from Bootstrap's Alert plugin by binding to the close.bs.alert event. It also makes it easier in Bootstrap to remove event handlers. For example, all of the following would work to remove an event handler bound to close.bs.alert:

$(el).off('close.bs.alert');
$(el).off('close.alert');
$(el).off('close.bs');
$(el).off('.bs.alert');
$(el).off('.alert');
$(el).off('.bs');

For removing, only one of the namespaces need match. I put together a JSFiddle to demonstrate jQuery event namespaces that I think helps demonstrate how they work:

$(document).on('close.bs.alert', function() {
    console.log("close.bs.alert handler");
});

$(document).on('close.alert', function() {
    console.log("close.alert handler");
});

$(document).on('close.bs', function() {
    console.log("close.bs handler");
});

$(document).on('close', function() {
    console.log("close handler");
});

console.log("triggering close...");
$(document).trigger('close'); // triggers 'close.bs.alert', 'close.alert',
                              // 'close.bs' and 'close'

console.log("triggering close.bs...");
$(document).trigger('close.bs'); // triggers 'close.bs.alert' and 'close.bs'

console.log("triggering close.alert...");
$(document).trigger('close.alert'); // triggers 'close.bs.alert' and 
                                    // 'close.alert'

console.log("triggering close.bs.alert...");
$(document).trigger('close.bs.alert'); // triggers 'close.bs.alert'

console.log("Remove close.alert handlers and triggering close...");
$(document).off('close.alert'); // removes close.bs.alert and close.alert
//$(document).off('.alert'); // removes close.bs.alert and close.alert as well
$(document).trigger('close');   // triggers 'close.bs' and 'close'

So that's event namespacing and triggering the close event. The next line is to return if the close event had preventDefault called on it. The idea is that a listener for the close event could call e.preventDefault() to prevent the alert from actually closing.

The other custom event that the Alert plugin dispatches is the closed event which is named closed.bs.alert. It is dispatched when the Alert is actually removed from the DOM. We'll see the code to trigger this event in the next section where we'll look at how the Alert is faded out and removed from the DOM.

Removing and fading out the Alert

Now we'll look at how the Alert is faded out and removed from the DOM.

$parent.removeClass('in')

function removeElement() {
  $parent.trigger('closed.bs.alert').remove()
}

$.support.transition && $parent.hasClass('fade') ?
  $parent
    .one($.support.transition.end, removeElement)
    .emulateTransitionEnd(150) :
  removeElement()

Fading out the Alert is accomplished by using a CSS3 transition. To understand how it works, let's look at the CSS:

.fade {
    opacity: 0;
    transition: opacity 0.15s linear 0s;
}
.fade.in {
    opacity: 1;
}

When an element has the fade and in classes, its opacity is 1 and when it only has the fade class its opacity is 0. The transition CSS property defines how quickly and in what way the opacity property changes from 0 to 1 when in is added to an element that already has fade. In this case however, the close method is removing the in class which causes the opacity to transition, linearly, from 1 to 0, causing it to fade out of view and become invisible.

Making the Alert invisible is not enough however. We want to actually remove it from the DOM. If we don't then it will still take up space on the web page, it just won't be visible. To accomplish this we need to know when the transition finishes. Once the transition finishes we can then remove the Alert from the DOM.

The removeElement function is defined so as to trigger the closed.bs.alert and then remove the Alert from the DOM. In an ideal world, we'd just bind the transitionend event to the removeElement handler. However there are a few complications:

It's possible that the Alert doesn't have the fade class, in other words, it is not desired that it actually fade out. That's fine, the transition is optional. That's what is checked for with $parent.hasClass('fade').
It's possible that this browser doesn't support CSS transitions. That's what $.support.transition is checking for. More on this later.
It's possible that even if the browser supports CSS transitions that it doesn't call the transition end event transitionend. The $.support.transition.end property holds the name of the transition end event for that browser.
Finally, it's possible that the transition end event won't be called. So we need to programmatically dispatch the event if it isn't called. That's what emulateTransitionEnd(150) is doing.

You can see the tests Bootstrap does to determine the transition end event name in transition.js. Also defined in transition.js is the emulateTransitionEnd function.

So let's go line by line. First, we'll remove the in class which will start the transition from opacity 1 to 0 over the course of 0.15 seconds. Next, define a function, removeElement, that will be called when the transition finishes. We'll bind removeElement to the transition end event.

removeElement will trigger the closed.bs.alert event, the second custom event, and it will remove the Alert from the DOM.

So next we have a ternary expression. If the browser supports transitions and the alert (the $parent) has class fade, then bind removeElement to the transition end event exactly once ($parent.one(...)). The call to emulateTransitionEnd(150) will set a 150 millisecond timeout and dispatch the transition end event if it hasn't already been dispatched (again, see transition.js for details). If the browser doesn't support Transitions or $parent doesn't have the fade class, then just call removeElement.

Alert jQuery Plugin Definition

Ok, a brief recap. We've defined the Alert class and it's single close method, which does almost all of the heavy lifting for this plugin. Now it's time to actually define the Alert class as a jQuery plugin. Here's the code:

var old = $.fn.alert

$.fn.alert = function (option) {
    return this.each(function () {
        var $this = $(this)
        var data  = $this.data('bs.alert')

        if (!data) $this.data('bs.alert', (data = new Alert(this)))
        if (typeof option == 'string') data[option].call($this)
    })
}

$.fn.alert.Constructor = Alert

First thing here is to capture the current value of $.fn.alert into the old variable. This is used later in noConflict, and it just a way to prevent this alert plugin from interfering with another alert plugin with the same name.

The $.fn.alert function is defined next. The way this function will be used is like so

$('.alert').alert();

So this refers to the result of a jQuery selector, which means it is an Array of DOM elements. So for each matching DOM element we'll run this function:

function() {
    var $this = $(this)
    var data  = $this.data('bs.alert')

    if (!data) $this.data('bs.alert', (data = new Alert(this)))
    if (typeof option == 'string') data[option].call($this)
}

Within the scope of this function, this refers to the current DOM element. $this is a jQuery wrapped reference to the DOM element.

When this function creates an Alert instance for this DOM element it will store it as a reference associated with the DOM element. var data = $this.data('bs.alert') is checking if we've already created an Alert instance for this DOM element. The third line of the function creates the Alert instance (data = new Alert(this)) if it hasn't already been created and it will be saved to the bs.alert key:

if (!data) $this.data('bs.alert', (data = new Alert(this)))

Finally, you may have noticed that the plugin function accepts an options argument. This is a common jQuery plugin pattern. There aren't any actual options for the Alert class, but options can also be a string with the name of a method that you want to invoke on the Alert instance. That's what is being done here. data, remember, is a reference to the Alert instance. data[option] therefore refers to a function on the Alert instance. It is called with $this as the context (that is, within the method invoked by call, this will refer to $this).

Also, as a jQuery plugin best practice, the result of calling this.each is returned to enable chaining of jQuery function calls.

The other thing we haven't talked about yet is this line:

$.fn.alert.Constructor = Alert

See this StackOverflow answer for a long explanation. but, basically, if we don't do this then the Alert constructor remains private to the closure in which we defined it. By creating the Constructor reference, other code can directly instantiate an Alert instance without needing to invoke it indirectly through the jQuery API.

Alert `noConflict`

Now we're at the noConflict function:

$.fn.alert.noConflict = function () {
    $.fn.alert = old
    return this
}

This is a simple convention for handling the situation that there is another jQuery plugin also called alert. This function sets $.fn.alert to its old value and returns this which refers to the $.fn.alert function defined above.

Alert Data API

Finally we get to the Data API. This allows for purely declarative use of the Alert plugin, no JavaScript calls necessary.

$(document).on('click.bs.alert.data-api', dismiss, Alert.prototype.close)

This binds the 'click' event for any DOM element in the page matching the dismiss selector to Alert's close method. Recall that the dismiss selector was defined as [data-dismiss="alert"]. So any clickable element in the page that has the attribute data-dismiss with value alert will have its click event handled by Alert's close method.

The difference with the Data API is that there is no actual Alert instance created. Instead Alert.prototype.close method is used directly, as a pure function. The way close will be invoked in this case is basically identical to how it will be invoked via the binding we see in the Alert constructor:

$(el).on('click', dismiss, this.close)

Additional Resources

Using CSS Transitions - at Mozilla Developer Network
transitionend

Scala: Object equality and the canEqual method

2014-03-22T13:13:00.001-04:00

This week I'm in chapter 30 of Programming in Scala, 2nd ed., the chapter titled Object Equality.

Getting Object Equality Right

This chapter is about how hard it is to properly implement a class' equals method. There is good advice here on the pitfalls to avoid and recipes to write good equals and hashCode methods. Most of this chapter is present in the article How to Write an Equality Method in Java except that the examples in the article use Java instead of Scala.

What is the `canEqual` method?

One of the strategies in this chapter is to introduce a canEqual method for non-final classes. This allows subclasses to override canEqual if they want to not allow being equal to the parent class or sibling classes.

The example in the chapter is this. You start with a Point class, which has x and y coordinate members. Then you have a ColoredPoint class that subclasses Point and overrides equals to make it so that ColoredPoints aren't equal to Points.

Here's the definition of Point:

class Point(val x: Int, val y: Int) {
    override def equals(other: Any) = other match {
        case that: Point => this.x == that.x && this.y == that.y
        case _ => false
    }
}

And the naive implementation of ColoredPoint:

class ColoredPoint(x: Int, y: Int, val color: Color.Value) 
    extends Point(x, y) {

    override def equals(other: Any) = other match {
        case that: ColoredPoint => 
            this.color == that.color && super.equals(that)
        case _ => false
    }
}

where Color is:

object Color extends Enumeration {
    val Red, Orange, Yellow, Green, Blue, Indigo, Violet = Value
}

The problem with this is that equals is not symmetric. It is possible for a Point to be equal to a ColoredPoint, but the ColoredPoint wouldn't be equal to the Point.

This is a little better, but still not transitive:

class ColoredPoint(x: Int, y: Int, val color: Color.Value) 
    extends Point(x, y) {

    override def equals(other: Any) = other match {
        case that: ColoredPoint =>
            (this.color == that.color) && super.equals(that)
        case that: Point => that equals this
        case _ => false
    }
}

To see how this doesn't work, consider a red ColoredPoint with x and y coordinates of 1,2 and a blue ColoredPoint with the same coordinates. The red ColoredPoint is equal to a Point(1, 2) and the Point(1, 2) is equal to the blue ColoredPoint, but the red and blue ColoredPoint are not equal to each other.

The solution proposed in the chapter is to introduce a new method, canEqual:

def canEqual(other: Any): Boolean

Point would then be defined as such (including hashCode):

class Point(val x: Int, val y: Int) {

    override def hashCode = 41 * (41 + x) + y
    override def equals(other: Any) = other match {
        case that: Point =>
            (that canEqual this) && 
            (this.x == that.x) && (this.y == that.y)
        case _ => false
    }

    def canEqual(other: Any): Boolean = other.isInstanceOf[Point]
}

And ColoredPoint is defined like so

class ColoredPoint(x: Int, y: Int, val color: Color.Value) extends Point(x, y) {

    override def hashCode = 41 * super.hashCode + color.hashCode
    override def equals(other: Any) = other match {
        case that: ColoredPoint =>
            (that canEqual this) && super.equals(that) && this.color == that.color
        case _ => false
    }

    override def canEqual(other: Any): Boolean = other.isInstanceOf[ColoredPoint]
}

Now Point instances cannot be equal to ColoredPoint instances since the first check that Point.equals will make is to call ColoredPoint.canEqual(Point) which will return false. It's vitally important that the canEqual method be call on that with this as the argument. canEqual is a way for classes to define what they can be equal to. In Point and ColoredPoint the match expression has been used to make sure that that is the right type, so now we can call canEqual on that to make sure that equality is possible in the reverse direction: that that canEqual this.

Does `canEqual` violate the Liskov Substitution Principle?

One criticism of the canEqual approach is that it violates the Liskov Substitution Principle which, according to Wikipedia, states:

if S is a subtype of T, then objects of type T may be replaced with objects of type S (i.e., objects of type S may substitute objects of type T) without altering any of the desirable properties of that program (correctness, task performed, etc.)

The authors of the book make the argument that Liskov Substitution Principle is not violated because, although the behavior of subclasses is different than the parent class, the contract itself, that equals return a boolean value, is not changed.

My intuition though is that this is a violation. From the perspective of the Point class, any two Point instances at the same x and y coordinates are equal. A subclass changing that definition has violated the contract in a way that makes a subclass not substitutable with a parent class. Let's look at an example of where substitution is violated.

Consider a distance method in Point that calculates the distance between two Points.

def distance(point:Point):Double =
    if (this == point)
        0
    else
        Math.sqrt(Math.pow(this.x - point.x, 2) + Math.pow(this.y - point.y, 2))

This method is taking a shortcut: if the two points are equal, then just return 0. This shortcut won't work if applied to a ColoredPoint even though it could be if ColoredPoint hadn't overridden the equals method. To me this is an example of a case where substitutability is violated because this method is expecting that it can take this shortcut for any Point instance.

`canEqual` is a code smell

In general I think that canEqual is a code smell. When you look at just the problem of defining equals it might seem reasonable to introduce canEqual. But think about the impact on other methods. For example, consider if we had extended Point with a new 3DPoint class. Then we would have to completely change the distance method. So not only can 3DPoint instances not equal Point instances, but we can't calculate the distance between 3DPoints and Points. This is clearly a Liskov Substitution Principle violation.

So if you are thinking of using canEqual because you want subclasses to not be equal to parent classes, it seems likely to me that if your subclasses can't equal the parent class then that probably affects other methods too.

As an alternative, consider using composition instead of inheritance. For example, we could define the ColoredPoint like so:

class ColoredPoint2(x: Int, y: Int, val color: Color.Value) {

    val point = new Point(x, y)

    override def hashCode = 41 * point.hashCode + color.hashCode
    override def equals(other: Any) = other match {
        case that: ColoredPoint2 =>
            point.equals(that.point) && this.color == that.color
        case _ => false
    }
}

Additional Resources

Scala: Understanding the self type annotation and how it relates to the Cake Pattern

2014-03-09T09:23:00.003-04:00

I'm currently working through the book Programming in Scala, 2nd ed.. I'm in chapter 29 which is on Modular Programming Using Objects. What is covered in the chapter has also been referred to as the Cake Pattern. The chapter takes the approach of building up to the Cake Pattern through an example that helps illustrate the kind of problems that the Cake Pattern solves. To understand the Cake Pattern you have to understand how the self type annotation works. So I'm going to take a slightly different approach and start with how the self type annotation works since it is so crucial.

What is the self type annotation?

In brief, the self type annotation allows you to split a trait in two but still refer to things on the second trait as though they are defined in the first trait, basically assuming (well, requiring) that they are mixed in together. For example, the following trait simply prints a greeting at a prompt:

trait Prompter1 {

    val prompt = "> "
    val greeting = "Hello world"

    def printGreeting() {
        println(prompt + greeting)
    }
}

val prompter1 = new Object with Prompter1
prompter1.printGreeting

Now suppose you want to split out the greeting part, maybe so that you can provide greetings for different languages. You could do this:

trait Prompter2 {
    // the self type annotation
    this: GreetingProvider =>

    val prompt = "> "

    def printGreeting() {
        println(prompt + greeting)
        // Next line would work too. 'this' can refer to things within this trait or
        // the declared self type trait
        //println(this.prompt + this.greeting)
    }
}

trait GreetingProvider {

    val greeting = "Hello world"
}

val prompter2 = new Prompter2 with GreetingProvider
prompter2.printGreeting

The code in Prompter2 is exactly the same as in Prompter1 except that there is now a self type annotation which says that this can also refer to GreetingProvider. Also the greeting has moved to a separate trait, GreetingProvider.

Do you need the self type annotation if you take care to always mix in the two traits together? No, because Prompter2 won't even compile and you get this error:

<console>:37: error: not found: value greeting
                println(prompt + greeting)

What happens if you tried to create a new Object and only mixed in Prompter2?

scala> new Object with Prompter2
new Object with Prompter2
<console>:19: error: illegal inheritance;
self-type Prompter2 does not conform to Prompter2's selftype Prompter2 with GreetingProvider
            new Object with Prompter2
                            ^

Does order matter? It doesn't appear to. The following works just fine:

val prompter2backwards = new GreetingProvider with Prompter2
prompter2backwards.printGreeting

If you have a self type annotation, does this only refer to that type? Apparently not. We could just as well have defined Prompter2.printGreeting like so:

def printGreeting() {
    // 'this' can refer to things within this trait or the declared self type trait
    println(this.prompt + this.greeting)
}

So the self type annotation appears to extend what this can refer to.

You can also have multiple traits mixed in for your self type annotation:

this: Foo with Bar with Baz =>

So what does this have to do with the Cake Pattern? We'll get there but for now hopefully you can see that the self type annotation allows you to express a dependency within a trait, a dependency that when satisfied allows one trait to make use of code defined in a separate trait. The Cake Pattern is a Dependency Injection technique that uses self type annotations to express and ultimately fulfill the dependencies between traits.

Applying the Cake Pattern to the examples in chapter 29

Chapter 29 doesn't mention the Cake Pattern and doesn't really apply it. It goes as far as introducing the self type annotation and showing how you can use to refactor a large trait and split it up into several smaller traits.

The chapter presents a Database class that abstracts getting Food and Recipe instances from some sort of backing store. The Database is then split up into three traits: one for FoodCategory methods, one for Food methods and one for Recipe methods. It's not all spelled out in the chapter but you would end up with something that looks like the following:

abstract class Food(val name: String) {
    override def toString = name
}

object Apple extends Food("Apple")
object Orange extends Food("Orange")
object Cream extends Food("Cream")
object Sugar extends Food("Sugar")

class Recipe(
    val name: String,
    val ingredients: List[Food],
    val instructions: String
) {
    override def toString = name
}

trait FoodCategories {
    case class FoodCategory(name: String, foods: List[Food])
    def allCategories: List[FoodCategory]
}

trait Foods {
    def allFoods: List[Food]
    def foodNamed(name: String) =
        allFoods.find(f => f.name == name)
}

trait Recipes {
    def allRecipes: List[Recipe]
}

abstract class Database extends FoodCategories with Foods with Recipes {
}

The book then proceeds to implement Foods and Recipes like so:

trait SimpleFoods extends Foods {
    object Pear extends Food("Pear")
    def allFoods = List(Apple, Pear)
    def allCategories = Nil
}

trait SimpleRecipes extends Recipes { // Does not compile
    object FruitSalad extends Recipe(
        "fruit salad",
        List(Apple, Pear),  // Uh oh
        "Mix it all together."
        )
    def allRecipes = List(FruitSalad)
}

The problem is that SimpleRecipes has a dependency on SimpleFoods. As such Pear is no longer in scope. Self type annotation to the rescue!

trait SimpleRecipes extends Recipes {
    this: SimpleFoods =>

    object FruitSalad extends Recipe(
        "fruit salad",
        List(Apple, Pear),
        "Mix it all together."
        )
    def allRecipes = List(FruitSalad)
}

This all works well enough for such a short example, but in the real world, when you have a database abstraction that has hundreds (or thousands?) of methods for retrieving objects from the database, would this suffice? Because the problem becomes that you will end up mixing all of those methods into the local namespace of your Database class. For example, instead of having a Foods.getAll method even this simple example compels us to having the method called Foods.allFoods.

This is where the Cake Pattern comes in. With the Cake Pattern you wrap your trait in a "component" trait. For example, the FoodCategories trait gets wrapped like so:

trait FoodCategoriesComponent {
    val foodCategories: FoodCategories
    trait FoodCategories {
        case class FoodCategory(name: String, foods: List[Food])
        def allCategories: List[FoodCategory]
    }
}

Likewise for Foods and Recipes:

trait FoodsComponent {
    val foods: Foods
    trait Foods {
        def allFoods: List[Food]
        def foodNamed(name: String) =
        allFoods.find(f => f.name == name)
    }
}

trait RecipesComponent {
    val recipes: Recipes
    trait Recipes {
        def allRecipes: List[Recipe]
    }
}

Now I'll create a SimpleFoodsComponent that implements Foods and FoodCategories (the book implements them together too):

// Implement Foods and FoodCategories at once
trait SimpleFoodsComponent extends FoodsComponent with FoodCategoriesComponent {

    val foods = new Object with SimpleFoods
    val foodCategories = foods
    trait SimpleFoods extends Foods with FoodCategories {
        object Pear extends Food("Pear")
        def allFoods = List(Apple, Pear)
        def allCategories = Nil
    }
}

And now time for the SimpleRecipesComponent. This one will depend on SimpleFoodsComponent:

trait SimpleRecipesComponent extends RecipesComponent {
    this: SimpleFoodsComponent =>

    val recipes = new Object with SimpleRecipes
    trait SimpleRecipes extends Recipes {
        object FruitSalad extends Recipe(
            "fruit salad",
            List(Apple, foods.Pear),
            "Mix it all together."
        )
        def allRecipes = List(FruitSalad)
    }
}

But this time the self type annotation brings foods into scope. So instead of bringing the Foods methods into scope we're just bringing the foods reference (which implements Foods) into scope. I like this since it keeps type members in separate namespaces.

Does it make sense to have a Database abstraction any longer? I'm not sure, but, for completeness, here's how I implemented it.

trait DatabaseComponent extends FoodCategoriesComponent
        with FoodsComponent with RecipesComponent {
    val database: Database

    trait Database extends FoodCategories with Foods with Recipes
}

trait SimpleDatabaseComponent extends DatabaseComponent
        with SimpleFoodsComponent with SimpleRecipesComponent {

    val database = new Database with SimpleFoods with SimpleRecipes
}

I haven't yet talked about the other main piece of the chapter's example, the Browser. As a component it would be defined like so:

trait BrowserComponent {
    this: DatabaseComponent =>

    val browser: Browser

    trait Browser {
        def recipesUsing(food: Food)
        def displayCategory(category: database.FoodCategory)
    }
}

And then it could be implemented with a dependency on the SimpleDatabaseComponent:

trait SimpleBrowserComponent extends BrowserComponent {
    this: SimpleDatabaseComponent =>

    val browser = new Object with SimpleBrowser
    trait SimpleBrowser extends Browser {

        def recipesUsing(food: Food) =
            database.allRecipes.filter(recipe =>
                recipe.ingredients.contains(food))

        def displayCategory(category: database.FoodCategory) {
            println(category)
        }
    }
}

If the Browser is the top level component then you could define it more simply, kind of like how the book does it.

For more information:

http://jonasboner.com/2008/10/06/real-world-scala-dependency-injection-di/
- Explains the cake pattern along with alternative approaches, very nice.
http://www.cakesolutions.net/teamblogs/2011/12/19/cake-pattern-in-depth/
- A more real world example of the cake pattern

Scala: Extractors

2014-03-02T13:22:00.002-05:00

I'm currently working through the book Programming in Scala, 2nd ed.. I'm in chapter 26 which is on Extractors.

What are Extractors?

Earlier in the book case classes were introduced. One of the things you can do with case classes is use them in pattern matching expressions. For example, you might have an Email case class to describe an email address:

case class Email(username:String, domain:String)

def isEmail(e: Any):Boolean = e match {
    case Email(_,_) => true
    case _ => false
}

But what if you are dealing with values that aren't case classes? Extractors allow you to basically define arbitrary match expressions without needing to set up case classes.

To understand extractors I find it helpful to understand their inverse, injections, first. Injections take inputs and produce an output of some type, not unlike a case class constructor. Injections have an apply method. So instead of our Email case class above, we could define a somewhat similar injection like so:

object Email {
    def apply(username: String, domain: String) = user + "@" + domain
}

(This is basically the example given in the book.)

An extractor on the other hand works in the reverse direction. In this case it defines an unapply method that would take a candidate string and, if it is an email address, will return the parts which would correspond to the arguments to the apply method:

object Email {
    def apply(username: String, domain: String) = user + "@" + domain
    def unapply(s: String): Option[(String, String)] = {
        val parts = s aplit "@"
        if (parts.length == 2) Some(parts(0), parts(1)) else None
    }
}

An extractor requires the unapply method, the apply method is optional. Also note that the unapply method returns an Option and will return None if the string is not an email address.

For more details see Extractor Objects. For example, you can have an unapply method that returns a Boolean, and there is the unapplySeq method for handling variable number of arguments to an extractor.

When to use extractors vs case classes?

So extractors let you define match expression patterns in much the same way as can be achieved with case classes. When do you use extractors instead of case classes?

The advantage that extractors have over case classes is that case classes expose the implementation type of an API's data model. Using an extractor allows you to hide the implementation type(s) of the API's data model and change it without requiring client code to change as well.

For example, we can use our Email extractor with a non-case class email class like so:

class EmailImpl(val username:String, val domain:String) {

    override def toString: String = username + "@" + domain
}

object Email {

    def unapply(s: String): Option[(String, String)] = {
        val parts = s split "@"
        if (parts.length == 2) Some(parts(0), parts(1)) else None
    }
}

Case classes do have advantages though. They are simpler, can be optimized better by the Scala compiler and with sealed case class hierarchies the compiler can also catch missed cases.

You can always start with case classes and then switch to extractors once there is a need to change the data model's concrete representation type.

An example: Date

Extractors seem like a great way of working with unstructured data and APIs where you don't have control over the source code. As an example consider the following extractor for getting the individual time values out of a java.util.Date instance:

import java.util.{Calendar => JCal, Date => JDate}

object Date {

    def unapply(d: JDate):Option[(Int,Int,Int,Int,Int,Int,Int)] = {
        val cal = JCal.getInstance
        cal.setTime(d)

        Some(cal get JCal.YEAR,
            cal get JCal.MONTH,
            cal get JCal.DAY_OF_MONTH,
            cal get JCal.HOUR_OF_DAY,
            cal get JCal.MINUTE,
            cal get JCal.SECOND,
            cal get JCal.MILLISECOND)
    }
}

This allows you write match expression against java.util.Date instances, like so:

def isFebruary(d: JDate): Boolean = d match {
    case Date(_, 1, _, _, _, _, _) => true
    case _ => false
}

You can also just use them to unpack values:

val Date(year, month, day, hour, minutes, seconds, milliseconds) = new JDate

Now you have a much simpler way to work with Java date instances.

Final thoughts

Extractors are kind of hard to think about because you have to think in terms of turning output backwards into inputs. Also, it's not always obvious what would be useful for unapply to return. When working through the examples and making up some of my own I found it useful to think of how I would implement the injection (i.e., the apply method) first.

Scala: Encoded Polyline, an Example in Implementing a Custom Collection Type

2014-02-23T10:01:00.000-05:00

This week I'm in chapter 25 of Programming in Scala, 2nd ed., the chapter titled The Architecture of Scala Collections.

As an exercise, I decided I'd implement a custom collection for encoded latitude/longitude points using Google's encoding method described here if you're interested. I've written some encoding/decoding code for this format for the FuelMyRoute Android app I've been working on, so I'm fairly familiar with it. The example the authors implement in the book is a RNA collection where the bases are stored as bits in an Array of Ints. In trying to come up with a different data structure to implement I likewise thought of one where the data is stored in a different and more compact format.

So I started by creating a case class to represent a latitude/longitude point, LatLng:

case class LatLng(lat:Double, lng:Double)

Then I created a Polyline class that extends LinearSeq:

class Polyline private (val encoding: String, val initLatLng:LatLng)
  extends LinearSeq[LatLng] {
  ...
}

Why a LinearSeq? Well, the polyline encoding format works like this. You encode the value of the first latitude and longitude point as a character string. For the second point, you encode the difference from the first point. For the third point, you encode the difference from the second point, and so on. So there is no efficient random access possible. Getting the first point (head) is fine, but in general getting a point at some index will take time proportional to the length of polyline. This all strongly suggests LinearSeq as the right abstraction for an encoded polyline. Scala's List has the same performance characteristics, for example, and is also a LinearSeq.

There are two abstract methods that must be implemented by subclasses of LinearSeq: apply and length. Unfortunately, again, these will take time proportional to the length of the polyline. I'm implementing them here based on the iterator:

def apply(idx: Int): LatLng = {
    val it = iterator
    var i = 0
    while (it.hasNext && i <= idx) {

        val latlng = it.next
        if (idx == i)
            return latlng
        else
            i += 1
    }
    throw new IndexOutOfBoundsException("No LatLng at index " + idx)
}

def length: Int = {
    val it = iterator
    var i = 0
    while (it.hasNext) {

        it.next
        i += 1
    }
    i
}

But for a LinearSeq, what you want to do is provide efficient implementations of isEmpty, head and tail. The private constructor for Polyline is given the encoding as a String, as well as the initial values for latitude and longitude, which are 0 for starting from an encoded polyline string. So for isEmpty we can simply check the length of the encoding string:

override def isEmpty: Boolean = encoding.length == 0

head will lazily convert the first latitude/longitude point and return it.

override def head(): LatLng = {

    if (isEmpty) {
        throw new NoSuchElementException("Collection is empty.")
    }

    computeFirstLatLng()
    firstLatLng.get
}

computeFirstLatLng sets firstLatLng, which is of type Option[LatLng].

The way tail will work is this: it will get the first latitude/longitude point and the remainder of the encoded string and then create a new Polyline instance from those values. Recall that when a Polyline is created it is given an initial value for the first latitude/longitude point. We can pass the first LatLng as the initial value to use for the Polyline that includes the substring of the encoded polyline from the second point on.

override def tail(): Polyline = {

    if (isEmpty) {
        throw new UnsupportedOperationException("Collection is empty.")
    }

    computeFirstLatLng()
    new Polyline(encoding.substring(index), firstLatLng.get)
}

Where did index come from? That's a private var in class Polyline that keeps track of the position within the Polyline. It really only ever points to first point (index=0) or the second point, since traversing this Polyline will consist of calling head then tail then head and so on until the returned tail isEmpty. Here's how index is used and how computeFirstLatLng is implemented:

private def computeFirstLatLng() {

    if (firstLatLng.isEmpty && encoding.length > 0) {

        val lat = initLatLng.lat + getNextNumber
        val lng = initLatLng.lng + getNextNumber

        firstLatLng = Some(LatLng(lat, lng))
    }
}

private def getNextNumber():Double = {
    var b = 0
    var shift = 0
    var result = 0

    do {
        b = encoding.charAt(index) - 63
        index += 1
        result |= (b & 0x1f) << shift
        shift += 5
    } while (b >= 0x20)
    return (if ((result & 1) != 0) ~(result >> 1) else (result >> 1)) / 1e5
}

Now to create a companion object that can construct a Polyline instance:

object Polyline {

    def empty: Polyline = new Polyline("", LatLng(0,0))
    def fromEncoding(encoding:String) = new Polyline(encoding, LatLng(0,0))
    def fromSeq(latlngs:Seq[LatLng]):Polyline = {
        // TODO: implement encoding LatLngs into a polyline string
    }
}

Now we can create and iterate over a Polyline instance:

scala> val pl = Polyline.fromEncoding("_p~iF~ps|U_ulLnnqC_mqNvxq`@")
pl: Polyline = (LatLng(38.5,-120.2), LatLng(40.7,-120.95), LatLng(43.252,-126.453))

Builders

This all works well enough, but what happens if you apply methods like take or filter?

scala> pl.take(2)
res0: scala.collection.LinearSeq[LatLng] = List(LatLng(38.5,-120.2), LatLng(40.7,-120.95))

The type of the result is List, not Polyline as we would like. To have your custom Collection type return results in the same type you need to provide a Builder that can construct instances of your custom collection type.

What's a Builder? A Builder can add elements to a particular kind of collection type. Also useful is that a Builder provides a mapResult method that allows you to map from the output of one Builder to a different collection type. Here's a simplified interface:

trait Builder[-Elem, +To] {

    def +=(elem: Elem): this.type
    def result(): To
    def clear()
    def mapResult(f: To => NewTo): Builder[Elem, NewTo]
}

The power of mapResult is we can use an existing Builder to create a collection of one type and then map it to the Polyline collection type. In our case we'll use ArrayBuffer.

So what do you need to do to supply a custom Builder?

Extend the "Like" trait and supply the result type of your custom collection as the second type parameter of the trait. Every Seq type has a corresponding "Like" type that contains all of the implementation. For example, LinearSeq's Like type is LinearSeqLike.
Override newBuilder to return a Builder that can construct instances of your custom collection type.

For Polyline it would work like this:

class Polyline private (val encoding: String, val initLatLng:LatLng)
    extends LinearSeq[LatLng] with LinearSeqLike[LatLng, Polyline] {

    override def newBuilder: Builder[LatLng, Polyline] =
        new ArrayBuffer[LatLng] mapResult Polyline.fromSeq
    ...
}

Note: I'd need to actually implement Polyline.fromSeq for this to work. I ran out of time, but hopefully you can see how the Builder would work and actually implementing fromSeq is just a detail at this point.

CanBuildFrom

Overriding newBuilder isn't quite enough for our custom collection type to always return the same collection type (at least when it is possible to return the same collection type). For example, the collection concatenation operator, ++, needs to be able to return a sequence where the element type of the sequence is the most specific superclass of the right hand side and left hand side collections. It does this via an implicit parameter of type CanBuildFrom. The signature of ++ is:

def  ++[B >: A, That](that: GenTraversableOnce[B])
    (implicit bf: CanBuildFrom[LinearSeq[A], B, That]): That

CanBuildFrom is a trait defined as such:

trait CanBuildFrom[-From, -Elem, +To] {

    def apply(from: From): Builder[Elem, To]
    def apply(): Builder[Elem, To]
}

So basically the Scala compiler will try to bind the most specific implicit CanBuildFrom that it can match the types of the arguments. LinearSeq defines a very general CanBuildFrom that can be used for any types. To have ++ concatenate two Polylines and return a Polyline instance we have to define a specific CanBuildFrom, which can be done in the companion object:

object Polyline {

    //...

    // We'll move the newBuilder method to the companion object and the
    // Polyline class will reference this one
    def newBuilder: Builder[LatLng, Polyline] =
        new ArrayBuffer[LatLng] mapResult Polyline.fromSeq

    def implicit def canBuildFrom[Polyline, LatLng, Polyline] =
        new CanBuildFrom[Polyline, LatLng, Polyline] {

            def apply(): Builder[LatLng, Polyline] = newBuilder
            def apply(from: Polyline): Builder[LatLng, Polyline] = newBuilder
        }
}

Resources

The polyline decoding code was largely inspired by http://jeffreysambells.com/2010/05/27/decoding-polylines-from-google-maps-direction-api-with-java
Looks like most of chapter 25 of Programming in Scala is online: http://docs.scala-lang.org/overviews/core/architecture-of-scala-collections.html

Scala: What's the difference between Traversable and Iterable?

2014-02-17T12:49:00.000-05:00

I'm currently working through the book Programming in Scala, 2nd ed.. I'm in chapter 24 and reading about the Traversable and Iterable traits and the difference between them.

Traversable is a trait with one abstract method, foreach. It's signature is

def foreach[U](f: Elem => U)

Defining this one method for a Traversable allows your collection class to gain several useful methods like

map
flatMap
take
drop
filter
foldLeft, foldRight
etc.

Iterable is a trait that extends Traversable and also has one abstract method, iterator. It's signature is

def iterator: Iterator[A]

Iterable defines foreach in terms of this iterator method:

def foreach[U](f: Elem => U): Unit = {
    val it = iterator
    while (it.hasNext) f(it.next())
}

If we can implement foreach in terms of iterator, why have Traversable as a separate trait?

The book provides one reason: that for some collections, implementing iterator may not be easy or may not be efficient. To illustrate this the book uses a Tree data structure as an example.

The Tree data structure is defined as a case class hierarchy:

sealed abstract class Tree
case class Branch(left: Tree, right: Tree) extends Tree
case class Node(elem: Int) extends Tree

I'm a Scala newbie so I couldn't get their Traversable Tree code example to work. Instead I came up with this:

sealed abstract class Tree extends Traversable[Int]
case class Branch(left: Tree, right: Tree) extends Tree {
  def foreach[U](f: Int => U) = left foreach f; right foreach f
}
case class Node(elem: Int) extends Tree {
  def foreach[U](f: Int => U) = f(elem)
}

For the Iterable version I came up with this:

sealed abstract class Tree extends Iterable[Int]
case class Branch(left: Tree, right: Tree) extends Tree {
  def iterator: Iterator[Int] = left.iterator ++ right.iterator
}
case class Node(elem: Int) extends Tree {
  def iterator: Iterator[Int] = Iterator.single(elem)
}

Both fairly straightforward. The problem with the Iterable version is with the efficiency of visiting nodes in the tree. In particular, the implementation of ++ is such that it has to do an extra indirection at every call to next to determine whether to pull from the left or the right iterator.

I think it helps to see what a naive implementation of ++ would look like:

def ++[A](left:Iterator[A], right:Iterator[A]):Iterator[A] =
    return new Iterator[A] {

        def hasNext: Boolean = left.hasNext || right.hasNext

        def next: A =
            if (left.hasNext)
                left.next
            else
                right.next
    }

Every call to next has to first check left.hasNext before returning a value. In a balanced binary tree with N leaf nodes, the depth of the tree is approximately log(N). So to reach a leaf via this added iterator would require an extra log(N) calls to left.hasNext. Therefore, visiting all of the leaf nodes using the iterator would take O(N*log(N)).

But, that's with the naive implementation of ++. The actual implementation, shown below, optimizes by keeping a reference, cur, to the current Iterator. This allows it to avoid needing to check hasNext on the first Iterator on each call to next.

def ++[B >: A](that: => GenTraversableOnce[B]): Iterator[B] = new AbstractIterator[B] {
    // optimize a little bit to prevent n log n behavior.
    private var cur : Iterator[B] = self
    private var selfExhausted : Boolean = false
    // since that is by-name, make sure it's only referenced once -
    // if "val it = that" is inside the block, then hasNext on an empty
    // iterator will continually reevaluate it. (ticket #3269)
    lazy val it = that.toIterator
    // the eq check is to avoid an infinite loop on "x ++ x"
    def hasNext = cur.hasNext || (!selfExhausted && {
        it.hasNext && {
            cur = it
            selfExhausted = true
            true
        }
    })
    def next() = { hasNext; cur.next() }
}

So, to a certain degree, this example with the Tree is a little artificial. It's just as easy to implement Tree as an Iterable as it is to implement it as a Traversable and there is no fundamental reason why the performance of visiting all of the leaf nodes needs to be worse than a Traversable implementation.

I think it is reasonable to assume that there might be data structures where implementing an Iterator over their elements could be challenging (either fundamentally so or with regards to efficiency). I just wish I could think of a more compelling example.

Further resources:

Learning Design: An Initial Curriculum

2013-03-29T21:32:00.000-04:00

I'm a programmer, not a designer. And in the past, I've been fine with that. I'll do the programming, let the designers do the designing. But now I want to learn how to design. And by design I mean just about everything that design can mean, both things like visual, graphic design and things like usability and information architecture.

Why? What's changed? I would say two things really. First, I think I can learn design (I think anyone can learn just about anything if motivated). I used to think that it just wasn't my talent. I would tell myself that "I can make things work, I just can't make them pretty." Second, I'm curious. I want to learn design now. I have come to appreciate that design isn't just "making things pretty". I think that design is about solving the human side of a problem. Being a programmer means I can solve the technological side of a problem, but that is only half of it. The best code in the world that actually solves a real problem won't do anyone good if it isn't usable. And the more that the user interface to a system delights users the more impact that solution will have in the real world.

I also think that learning design is a better career move than, for example, learning functional programming or how to write event-driven, non-blocking web server code, or whatever the new hotness is. I don't expect to become a great designer, only a decent one. I expect I will still need to work with a "real" designer on at least some of my projects, maybe all. But being able to put together good looking prototypes, being able to communicate better with web/graphic designers, being able to produce decent initial working versions of software, being able to layout and organize displays of information in ways that are helpful and appealing, all of that makes me better able to deliver software solutions and hence make me more valuable to potential employers. Perhaps most importantly to me, as an wannabe bootstrapped entrepreneur, it means I can create more compelling applications and that I can more fully realize the applications that I see in my imagination.

So here's what I'm looking at now as resources for learning design.

Treehouse: Become a Web Designer Adventure

I like the idea of an online course. I think it will be easier to consume and stay on track. I also like that Treehouse covers theory (although maybe a little light on it by the looks of the curriculum) and also practice, how to use the tools of the trade. (But man is Photoshop expensive!)

Non-Designer's Design Book by Robin Williams

I've seen this book recommended on Hacker News and elsewhere more times than I can count. I'm including it with the hopes it will give me a good foundation in the basics of design theory (and practice).

Don't Make Me Think by Steve Krug

Another book that comes highly recommended. I realize this list is a little light on HCI type topics and perhaps I can add some more useability/user experience resources to this list, but I think Don't Make Me Think is a good place to start.

Drawing on the Right Side of the Brain by Betty Edwards

I don't think drawing will directly help me with web design, but I do think it will get the artistic juices flowing. One of the things I've read about this book is that it doesn't so much teach you how to draw as much as it teaches you how to really see. That ability to see clearly will help me to see what is good in other's design and perhaps also help me see how to make my designs better.

Design of Everyday Things by Donald Norman

Another highly recommended book, but I haven't read much about it. Looking forward to reading it.

Copying good designs

What's the saying, good artists create, great artists steal?. As part of my curriculum I'll study and copy design that I find appealing. Why do they work so well? How do they implement those designs?

I've done something like this before when I was working on learning CSS. I took a screenshot of csszengarden.com, copied the HTML and images and wrote the CSS from scratch to match the screenshot. It was a good learning exercise, not just in that I exercised applying what I had learned about CSS but after I was done I also compared what I had done to the csszengarden.com's CSS code and learned from the approaches they had taken.

Notable Mention

In my research, these resources looked interesting and I might use them, but I don't have enough time to do everything.

Design for Hackers
Designing for the Web - This is a free resource
HACKDESIGN - free course by email. Actually I think I will sign up for this one. Looks interesting and I've never done a course by email.
Step by Step UI Design - Step by Step UI Design. Looks really good as a resource for learning more about the actual practice of web design.
HCI course on Coursera

Using Codea and Khan Academy to teach computer programming to my daughter

2013-03-17T10:33:00.000-04:00

I've been teaching computer programming to my oldest daughter (who is turning 11 soon) for the past couple of years or so. We started out with Scratch and she had a blast with that. After completing a simple game that she designed and developed herself, I asked her what she wanted to do next. She said, "I want to do what you do". She knew from watching me work that the visual programming environment in Scratch is not how "real" programmers work.

So our next step was to give Python programming a try. We got the book Invent Your Own Computer Games with Python and started working through it. Unfortunately, jumping into Python from Scratch was probably a little too tough and the fact that the programs she was creating in Python were completely textual meant that it was less engaging. So I started thinking about what we could do next.

Getting nostalgic for my Atari 800XL

I thought about what computing meant for me when I was her age. Growing up I had an Atari 800XL. What a marvelously simple device compared to what we have available to us today. There were two things that made the Atari 800XL a great first computer for a kid:

No internet.
Simple programming environments (BASIC and Turtle graphics).

That first one is a big deal. We don't let our children use computers unattended because of the inherent dangers of the world wide web. I'm sure my parents never had any such concerns because my Atari 800XL was never networked at all. Because of that I spent a lot of time just playing around on my computer. I remember hours upon hours spent meticulously typing in computer programs from magazines such as Compute! into my 800XL.

The second one, simple programming environments, is important too, but there are plenty of those to be had. Turtle graphics was particularly good because I could get the gratification of generating a visual effect of some sort. Probably the most advanced turtle graphics program I wrote (which wasn't very advanced, but I was proud of it at the time) was one where I animated a simple line drawing of a bird flapping its wings. I could control the bird's position on the screen by using a joystick. That was a lot of fun.

So this got me to thinking. Could I set up a computing environment for my daughter that would be easy for us to monitor, allow her to just waste time playing around with different ideas and approaches, and allow her to create graphical programs?

Enter Codea

I thought, what if she could have a turtle graphics like program on our iPad? She (like everyone in the family) just adores our iPad. If she could create graphical programs on the iPad, especially if they could respond to touch and what not, I thought she would get a big kick out of that.

The iPad still suffers from the problem of having unfettered access to the internet, but an app that serves as a self-contained environment would minimize the chance that she would ever even end up in Safari. Also, it's not too hard to keep an eye on her using the iPad while in the same room with her.

While Codea is a great programming environment, it's not the the best learning environment. I tried coming up with my own lessons, and I also found some Codea tutorials online, but nothing was really clicking. She did spend some time just exploring and playing with Codea, but that only goes so far.

And then we found Khan Academy

Khan Academy has video lessons and an integrated code editor. Like Codea, it offers a Processing like API. There are a few nice things about Khan Academy.

First, they have a series of tutorials that my daughter is able to watch and progress through at her own pace. The tutorials are in sync with actions in the code editor, so she can pause the tutorial and experiment with the code at any point. Also nice, the video tutorials are narrated by a woman. It might seem like a minor thing but I've noticed that my daughter has picked up on the fact that the computer programmer profession is male-dominated, so any reinforcements that, yes, girls program too, is always nice.

Second, the code editor and the graphical display are side by side. You can see the effect of your code changes as you type them. Codea requires you flip between code editing and running your code.

Third, Khan Academy has gamification! You can earn achievements and badges. You can create a "spin-off" of one of the example programs, make it cooler, and then other Khan Academy users can vote on them. Turns out this is very cool for an 11 year old!

So far, Khan Academy seems to be the most perfect environment to learn computer programming that we've found yet.

Since Khan Academy and Codea both use the Processing API, we've experimented with moving code between the two environments. There are some slight syntactic differences between JavaScript (Khan Academy) and Lua (Codea) of course. Codea also has the vertical axis flipped compared to Khan Academy. Khan Academy names some things differently and has some different API methods like:

strokeWeight instead of strokeWidth
point(x ,y)
triangle(x1, y1, x2, y2, x3, y3)

Here's an example of how I translated the Intro to Animation lesson into Codea (point and triangle aren't used below, but they are used in some Khan Academy programs so I'm including them here just for illustrative purposes):

-- KA-Intro to Animation

-- vim: set ts=4 sw=4 et ai filetype=lua:

function setup()
    print("Hello World!")
end

function strokeWeight(weight)
    strokeWidth(weight)
end

function point(x, y)
    line(x, y, x, y)
end

function triangle(x1, y1, x2, y2, x3, y3)
    myMesh = mesh()
    myMesh.vertices = {vec2(x1,y1),vec2(x2,y2),vec2(x3,y3)}
    myMesh:draw()
end

function initKhan()
    -- Khan Academy setup
    -- set a default stroke "weight" (codea calls this width) and color
    stroke(0, 0, 0, 255)
    strokeWeight(1)

    -- translate and scale into Khan Academy coordinate system
    translate(0, 400)
    scale(1, -1)
end

function draw()

    initKhan()
    -- this is the draw loop! everything inside this
    -- function will be run over and over again.
    background(252, 255, 214)
    noStroke()

    -- position of the car
    x = 10

    -- draw the car body
    fill(255, 0, 115)
    rect(x, 200, 100, 20)
    rect(x + 15, 178, 70, 40)

    -- draw the wheels
    fill(77, 66, 66)
    ellipse(x + 25, 221, 24, 24)
    ellipse(x + 75, 221, 24, 24)

end

So that's where we are so far. I'm hoping we can work toward a project this year, like making a mobile app game or something.

How do you set up for multi package Python development?

2013-03-09T21:37:00.001-05:00

Or, how do I use my models outside of a Pyramid application?

I've developed a little Pyramid app as a mobile backend version of FuelMyRoute.com. As natural, I've defined the database models inside the application. But, now I want to develop a new gas price data importer piece of code that will live outside of the Pyramid web application. This importer will need to make use of the same models as defined in the Pyramid app. So what to do?

Well, ideally I would have the models defined outside of the Pyramid app in its own package. So I would end up with three packages: the Pyramid app is a package, the models are a package, making the importer code a third package. The importer package would depend on the models package, just like the Pyramid app.

Now, in Python there are lots of mechanisms to pull this off. First we could just manipulate the sys.path in each package to pull in the needed dependencies. Second we could set a PYTHONPATH to pull in the other packages. But the way I decided to do it was to install the packages into a virtual environment. I got this idea from the Pyramid tutorial/documentation where it has you do a python setup.py develop into the virtual environment for the app. python setup.py develop is basically a way to symlink in your package into the system path of the virtual environment.

Here are the three packages. Each package name is prefixed with gptp-, which is just an codename for an earlier version of FuelMyRoute.com.

gptp-models - Defines the SQLAlchemy models
gptp-pyramid - The Pyramid application, depends on gptp-models
gptp-importer - Gas price data importer code, depends on gptp-models

Here's the setup.py file for the gptp-models package:

from setuptools import setup, find_packages

# http://pythonhosted.org/distribute/setuptools.html#basic-use
setup(
    name='gptp-models',
    version='0.1dev',
    packages=find_packages(),
    install_requires=[
        # <0.8 includes stupid stuff like 0.8b2, so have to defensively prevent
        # alphas, betas etc. http://stackoverflow.com/a/14405269/1419499
        'SQLAlchemy<0.7.99',
        #... additional dependecies
        ]
)

This is just about as barebones as it can get for a setup.py. I believe that only name, version and packages are required. This package depends on SQLAlchmey, amongst other things, so I've included that to illustrate how to declare dependencies.

Here's the setup.py for gptp-pyramid:

import os

from setuptools import setup, find_packages

here = os.path.abspath(os.path.dirname(__file__))
README = open(os.path.join(here, 'README.txt')).read()
CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()

requires = [
    'pyramid<=1.3.99',
    'SQLAlchemy<=0.7.99',
    'transaction',
    'pyramid_tm',
    'pyramid_debugtoolbar',
    'zope.sqlalchemy',
    'waitress',
    'gptp-models',
    # .. more dependencies ..
    ]

setup(name='gptp',
      version='0.0',
      description='gptp',
      long_description=README + '\n\n' +  CHANGES,
      classifiers=[
        "Programming Language :: Python",
        "Framework :: Pylons",
        "Topic :: Internet :: WWW/HTTP",
        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
        ],
      author='',
      author_email='',
      url='',
      keywords='web wsgi bfg pylons pyramid',
      packages=find_packages(),
      include_package_data=True,
      zip_safe=False,
      test_suite='gptp',
      install_requires=requires,
      entry_points="""\
      [paste.app_factory]
      main = gptp:main
      [console_scripts]
      initialize_gptp_db = gptp.scripts.initializedb:main
      """
      )

There's more going on here, but most of the extra stuff is stuff that was auto-generated by Pyramid. The important thing is that on about line 18 the package gptp-models is listed as a required dependency.

Finally we have gptp-importer's setup.py:

from setuptools import setup, find_packages

# http://pythonhosted.org/distribute/setuptools.html#basic-use
setup(
    name='gptp-importer',
    version='0.1dev',
    packages=find_packages(),
    install_requires=[
        'gptp-models'
        ]
)

About what you might expect at this point.

So now with my three packages set up, I can proceed with setting up a virtual environment. I'm using Python 3.3 so I set up the virtual environment with the built in pyvenv command and install distribute and pip into it, using this script, named bootstrap-pyvenv:

#!/bin/sh

# Create Python virtual environment
pyvenv $1

# install distribute and pip
curl -O http://python-distribute.org/distribute_setup.py
$1/bin/python distribute_setup.py
$1/bin/easy_install pip

# Clean up
rm distribute*

So I run:

bootstrap-pyvenv gptpenv

Then, activate the environment and run python setup.py develop in each package, starting with gptp-models of course:

source gptpenv/bin/activate
cd gptp-models
python setup.py develop
cd ../gptp-importer
python setup.py develop
cd ../gptp-pyramid
python setup.py develop

Okay, so that's set up. But how do I get Pyramid to use my models that are defined in a separate package? Here's what my models.py looked like before I made my changes:

from sqlalchemy import (
    Column,
    DateTime,
    Float,
    ForeignKey,
    Integer,
    String,
    types,
    )

from sqlalchemy.ext.declarative import declarative_base

from sqlalchemy.orm import (
    relationship,
    scoped_session,
    sessionmaker,
    )

from zope.sqlalchemy import ZopeTransactionExtension

from datetime import datetime
from shapely.wkb import loads
from struct import pack, unpack

from geo.proj import ProjectedPoint, utm_projector

DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
Base = declarative_base()

# ... start defining my models here ...

I moved my models into gptp-models/models.py and updated the pyramid models.py to be:

import models
from sqlalchemy.orm import (
    scoped_session,
    sessionmaker,
    )

from zope.sqlalchemy import ZopeTransactionExtension

DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
Base = models.Base

The import models imports my models from the gptp-models package (could probably be namespaced better, but this suffices for now). The line

1	Base = models.Base

is just a convenience so that I can continue to import Base from the Pyramid models.py.

That's basically it. I just need to update the imports elsewhere in the app. For example, in my views.py I had

# ...
from .models import (
    DBSession,
    GasStation,
    GasPrice,
)
# ...

which becomes:

# ...
from .models import (
    DBSession,
)
from models import (
    GasStation,
    GasPrice,
)
# ...

Other Approaches to the Multiple Python Packages Problem

I asked about what people do in this situation on Twitter:

Developing on multiple python projects that depend on each other? Make a virtual env and 'python setup.py develop' in each project
— marcus_christie (@marcus_christie) March 4, 2013

Pradeep Gowda replied with

@marcus_christie package each project & push to a local python package index (pypi). Use pip --index-url to install in virtualenv
— btbytes (@btbytes) March 4, 2013

I think that would probably be the better way to go for a larger project and multiple developers. For what I'm doing, since it's just me and a side project, the setup described above is sufficient.

Pradeep shared the following benefit of going the local pypi approach:

@marcus_christie having packages versioned and on a repo opens up new workflow opportunities (eg: vagrant/chef automation). Many +ves.
— btbytes (@btbytes) March 4, 2013

He also shared this link on how to set up a local PyPI.

So that's another option that is worth considering too.

CodeMash 2013 Part II: Sessions

2013-02-10T21:13:00.001-05:00

In my previous post, CodeMash 2013 Part I, I covered the "precompilers" (that's CodeMash-ese for "tutorial" or "workshop") that I attended. The last two days of CodeMash, Thursday and Friday, are devoted to technical talks and presentations (although there's a lot more going on than just technical talks like open spaces, KidzMash (for the younger geeks), the bacon bar, etc.).

Continuing with my plan from the first two days I decided to mostly focus on

Mobile web development/PhoneGap
Javascript MVC Frameworks/Single page applications

Thursday 9:45 AM: Performance, Productivity. Pick Two with Dart

Seth Ladd gave a talk on Dart. It's an ambitious project to create a new way of building web applications. At the heart of it is Dart, a optionally statically typed language that is reminiscent of Java and that can compile down to JavaScript.

My overall impression is that Dart is a lot to chew off. Seth showed what the JavaScript code looks like that Dart can compile to. I found it rather bizarre looking, not at all like the nice output you get with CoffeeScript. One question I had going in is if you can call third party JavaScript libraries. You can but you have to use some sort of bridge to do so (which he didn't have time to show). With CoffeeScript, it's trivial to call third party libraries.

So it's interesting and the tooling is pretty cool, it just feels like you'd end up cutting yourself off from a big chunk of the web community going with Dart.

Thursday 11:00 AM: Machine Learning - Understanding the Past

This was a fantastic talk by Seth Juarez on using machine learning techniques to help make sense of your data. He went over unsupervised learning methods like K-means clustering and principal component analysis. He's put his slides up here in case you're interested.

Thursday 1:45 PM: HTML 5 and the Great Mobile Debate

This was a great talk about the current state of developing cross platform mobile applications and whether it makes sense to develop those apps using HTML 5. Andy Glover gave this talk; he wrote up a blog post covering his main points.

In summary, Andy suggests not using HTML 5 and if you want to target multiple mobile platforms with a single codebase, he suggests you look at one of the cross platform frameworks such as Appcelerator, Xamarin, Corona or Unity. The main points of his argument are

mobile browsers are even more fragmented than native APIs. Here he pointed out how even the most advanced mobile browsers don't support all of HTML 5 (he used conformance testing tools like rng.io and fmbip.com). I'm not sure I agree on this point; there's an awful lot in HTML 5 and a browser doesn't need to support all of it to be perfectly fine to target with a mobile web app. But he does have a point that simply making a mobile web app doesn't mean you don't have to deal with fragmentation issues.
HTML rules on the desktop because it's easier to distribute an app as a web application than as a native blob of bits. The web's strength on the desktop doesn't matter on mobile because on mobile the software distribution problem is a solved problem.
Consumer apps with a great user experience (examples he used were Flipboard and Angry Birds) have set the bar really high for the UI quality of a mobile app.

The talk was very thought provoking, although I think HTML 5 and PhoneGap are perfectly fine for an app in the enterprise or B2B space. I don't think I would use HTML 5 to make a game or a consumer app (well, maybe as a kind of prototype of a consumer app), but I do think it has a place in the enterprise.

Thursday 3:35 PM: Lessons from Two Years of Backbone.js

Chris Nelson presented on lessons learned using Backbone.js. This was a packed talk that I was unfortunately late to so I didn't take the greatest notes. I also can't find his slides online. Wish I could find them because he had some interesting material on stuff like how to do composite views in Backbone.js. Lesson learned: show up early to get a good seat :)

Thursday 4:50 PM: Client/Server Apps with HTML5, Play, CoffeeScript, and More

James Ward gave a whirlwind tour of a very modern web application development stack using Play, CoffeeScript, Bootstrap and more. He tore through the slides but 1 hour just wasn't enough time to complete the whole thing.

Friday 10:45 AM: The Native/Mobile Web: Beyond the Basics with PhoneGap

JC Grubbs gave a talk on some of the real world concerns with building a PhoneGap app, like how to deal with performance issues or how to create a build process to target multiple mobile platforms. His slides are here.

My notes:

Structuring a project
- src - source code
- www - js and css get concatenated to this directory
- ios
  - www -> ../www/ - symlink in the www folder to the respective container app
- android
  - www symlinked likewise
Typical stack
- Zepto/JQuery
- backbone/underscore
  - template rendering performance
- moment.js / gui tools / data libs / JQuery Mobile
- jasmine / rake-pipeline / sass / ejs
GUI Toolkits
- JQuery Mobile
- iUI
- Sencha Touch
- Ratchet
  - this is actually a prototyping toolkit but JC pulled out the UI stuff from it to create mobile web UIs
- Media queries
- Icon Fonts
  - scales automatically
  - icomoon - Chrome app for browsing icon fonts
- Flex box / fluid layout
- scrolling
  - webkit-overflow-scroll: touch
  - avoid scrolling libraries
- iOS Bounce
  - you can turn this off with a PhoneGap setting
Local vs Remote data
- use Backbone sync plugins that handle saving dirty records and flush when online
Debugging
- test in browser - there are PhoneGap shims
- iOS remote debugger
- debug.phonegap.com - weinre
- JSlint
Testing
- Jasmine / QUnit
- Capybara / Cucumber
Performance
- Tap vs click
  - use touch events
- JS vs CSS animations
  - use CSS animations
- clean the DOM
- Page everything - no infinite scroll
- Web workers (iOS 5.1+)
- Plugins
  - can use them to get native performance
Deployment
- TestFlightApp
- PhoneGap Build
Backbone/JQuery Mobile
- use JQuery Mobile for styling/UI, but disable ajax based navigation
- backbone router is flaky on iOS

Friday 1:45 PM: Building Rich User Experiences Without JavaScript Spaghetti

This was a talk on using some design patterns to make more maintainable JavaScript code. The speaker Jared Faris and if you're interested, I believe the same talk is available to view online at InfoQ. Here are my notes from the talk:

Decouple code that has multiple concerns
Write small, discrete bits of code
Think of UI components as separate JS objects
put DOM stuff in separate layer
Mediator pattern
Observer pattern
Pub/sub - Postal.js (Event routing)
Chrome has a de-minifier
EJS templates
JQuery doTimeout plugin - a better setTimeout
Signature Pad - capture a signature in a HTML5 canvas
SimpleDialog2 - better modal dialog for JQuery Mobile

Friday 3:35 PM: AngularJS: The HTML of the Future

This was a very interesting talk for me because I really hadn't seen any AngularJS before. John Lindquist demonstrated how to create your own directives which basically is a way to create your own HTML elements.

What else?

Well there's the waterpark, right? You can't go to CodeMash and not spend some time in the waterpark. The family and I had a good time there on Thursday night.

Also, there's KidzMash, a parallel conference with cool computer programming activities for kids. I took my youngest daughter (7 years old) to one session where she learned how to "program" me by creating a list of simple instructions (step, left, right) that I would then follow on a grid that had been taped into the floor. My oldest daughter (10 years old) has been programming in Scratch, Python and a little Lua and JavaScript recently, so I took her to a talk on using a Windows Kinect device to create programs that respond to gestures. That was a lot of fun too (now she wants a Kinect!).

All in all, it was a great conference. I learned a lot, and I expect I'll be digging deeper into some of things I was exposed to over the next couple of months. I hope I get to go back to it next year.

CodeMash 2013 Part I: Precompilers

2013-01-27T20:25:00.001-05:00

This year I went to CodeMash, a fun, eclectic software development conference held at the Kalahari Resort in Sandusky, OH. I learned quite a bit and had a great time. There were so many good sessions that it was hard to decide which ones to go to. To help me decide I decided to focus in on two areas I'm currently interested in:

Mobile web development/PhoneGap
Javascript MVC Frameworks/Single page applications

The first two days of the conference, Tuesday and Wednesday, were devoted to half and full day workshops/tutorials that CodeMash calls Precompilers.

Tuesday AM: PhoneGap tutorial

My first precompiler on Tuesday was Developing Mobile applications with PhoneGap by Ray Camden. You can find the presentation and the labs on GitHub.

The highlight of this presentation was the discussion on how to test mobile web applications and the various tools that are available.

Probably the coolest one I saw was Ripple. Ripple is a mobile web application emulator that can run as a Chrome extension. You can simulate different devices and different frameworks (I believe it can emulate the PhoneGap API so you can test your code to some extent). You can change network settings and geolocation data. You can also fire off mobile specific events like deviceready. The user documentation is hosted on Blackberry's website Ripple is currently an Apache Incubator project.

There were some other tools that looked interesting and were demoed but I haven't yet played around with them. First, you can connect the desktop Safari browser to the mobile Safari browser running in the iOS Simulator. You can use all of the normal Safari developer tools but they work with the web page in mobile Safari. Very cool. The second tool I'll mention is Edge Inspect which takes that same idea and extends it so you can remotely inspect mobile web code running on an actual device. Edge Inspect is a freemium service so you can try before you buy and perhaps get a lot of use out of it without spending a dime.

Finally I'll mention weinre which wasn't mentioned (and to be honest I've not used it but have heard of it) but is in the same vein and is a free and open source project.

Tuesday PM: Choose Your Own Application

From the guys at SRT Solutions comes the very fun Choose Your Own Application!. You should seriously check this out. Remember those Choose Your Own Adventure books from when you were a kid? This is the same idea except you choose your software stack. You can choose to use JavaScript or CoffeeScript, Backbone or Knockout, ASP.NET or Rails or Node.js, and finally you can choose to deploy to Heroku or Azure.

I chose to use JavaScript with Backbone with a Node.js backend, deployed to Heroku. The app they have you create is a StackOverflow like web site where users can submit questions and vote on them (very simplistic implementation). One cool part of the design is that it uses Socket.IO to push updates via WebSockets (which ended up falling back to long polling on Heroku as I recall). You can open up two browser windows, create a question in one window and see it update in the other window. It's a good way to see the power of a Javascript MVC framework like Backbone; the model is updated in the background and the view immediately reflects it.

If you want to see what the code looks like, I've pushed my code to GitHub: https://github.com/machristie/chooseyourownapplication-bbjsnodeheroku. I found Heroku ridiculously easy to get set up with and a really simple and powerful way to deploy out a website. The combination of GitHub and the free usage tier of Heroku is especially nice for an exercise like this because you can easily publish the code and the working implementation for something you are learning or some new approach you are trying and would like feedback on.

You can see my running implemenation here http://cyoa-mchristie.herokuapp.com/.

Wednesday AM: Atomic Scala

This session was presented by Dianne Marsh and Bruce Eckel. The idea was to present concepts in Scala one at a time (or one "atom" at a time). I think they're intended audience is first time programmers or at least programmers who don't have a Java background. In any case the pacing of the tutorial was way too slow, especially for a session with an advertised level of intermediate. They were kind enough to give us a pre-publish version of their book, Atomic Scala, and going at my own pace I would probably find it useful for learning Scala. We'll see.

Wednesday PM: Real-world JavaScript Testing

The Atomic Scala session was actually full day but I skipped out on the second half and went to Justin Searls' session on real world JavaScript testing. This was a great session that combined presenting on lessons learned in the wild with a fun hands on lab. His slides and the code for the lab are up on GitHub. The talk started with how to use Jasmine, a JavaScript unit testing framework. They then added to this by featuring various jasmine addons and other techniques for making writing unit tests easier:

jasmine-fixture for easily adding elements to the DOM that are expected by the tests
Using Coffeescript which allows for a cleaner syntax making the tests more readable
jasmine-given for "Given", "When", "Then" style testing.
lineman is used to automatically compile CoffeeScript with lineman run and automatically run your tests (or specs) with lineman spec. The nice thing here is that the testing framework was also remote driving a Chrome browser window (or headlessly) to re-run the tests and display the test results. This gave immediate feedback: write a test, save, test is run and status displayed; update production code, save, test is re-run. You can see what working with lineman is like by watching this screencast:

This was an extremely nice and productive setup. We paired up and worked on creating a test for a fibonacci calculator web application. It was tough since I didn't know CoffeeScript or Jasmine, but very rewarding as it helped me see how I would actually use this to test real code. I've posted my solution on GitHub.

TODO: I want to dive more into this setup and see how it is actually working. There are a lot of moving parts here and I'm not familiar with most of them. But I'm hoping I can use this setup or one like it for my JavaScript code.

Conclusion

Well, the first two days were kind of mentally exhausting! But it was fun to be thrown into the deep end and have to figure out a bunch of stuff using frameworks and languages that I'm not familiar with. Definitely worth it to do the Precompilers if you are going to CodeMash.

Next week I'll blog about the other two days of CodeMash.

Pyramid, MySQL, and Python 3

2012-11-11T18:32:00.000-05:00

For the impatient

Assuming you have Python 3 installed with distribute and virtualenv and also MySQL, create a virtualenv

virtualenv --no-site-packages --distribute myenv

Then activate your environment

source myenv/bin/activate

Create the following requirements file (save to requirements.txt):

#oursql==0.9.3 but need special Python 3 build https://bugs.launchpad.net/oursql/+bug/1051512
https://launchpad.net/oursql/py3k/py3k-0.9.3/+download/oursql-0.9.3.zip
pyramid==1.3.4

Then run:

pip install -r requirements.txt

The longer version

I'm currently working on an Android app version of FuelMyRoute.com. The website currently uses TurboGears (version 1.0.something I'm afraid). I thought about using the website as the backend for the mobile app but wanted the freedom to experiment and potentially do things much differently in a separate mobile backend. I also wanted to work on a more modern stack. The TurboGears team has essentially joined forces with the Pyramid team, so I took a look at Pyramid. I liked what I saw, and with version 1.3 it can run on Python 3.

So let's see if we can get a Pyramid/SQLAlchemy/MySQL site working on Python 3. The first thing I ran into is that it was hard to find a good Python MySQL driver that works on Python 3. For years I've been using the trusty if somewhat antiquated MySQLdb Python module. It looks like development has slowed to a halt on MySQLdb so I took a look at alternatives.

First alternative I explored was MySQL Connector/Python. I like that Oracle is sponsoring the development and it is a pure Python library. However, I hit upon a major bug that made it a deal breaker. I've subsequently learned that this bug has been fixed so I'll probably give it another try in the future.

Second alternative I looked at was OurSQL. I'm not sure if it is a fork of MySQLdb, but it seems fairly similar. It does have some benefits over MySQLdb , not the least of which is Python 3 support. One catch is that you can't just "pip install oursql" under Python 3. There is a distinct branch of code for the Python 3 support. To install the Python 3 branch of OurSQL you can use the requirements.txt file above, or for just OurSQL you can do

pip install https://launchpad.net/oursql/py3k/py3k-0.9.3/+download/oursql-0.9.3.zip

I also ran into an issue with Python 3 and one of Pyramid's dependencies, zope.interface. That's why zope.interface is listed in the requirements.txt file with version 3.8.0. But this is fixed now https://github.com/Pylons/pyramid/issues/604. Just make sure you get the latest 1.3 bugfix release. At the time of this writing, that is 1.3.4.

To get started with SQLAlchemy, just run the following to create a Pyramid scaffold project using SQLAlchemy:

pcreate -s alchemy MyProject

More info here: http://docs.pylonsproject.org/projects/pyramid/en/1.3-branch/narr/project.html

How to dynamically change the Tweet Button's tweet text

2011-07-09T13:20:00.006-04:00

Looked around on the internet for a way to dynamically change the tweet text of the Tweet Button, but didn't find a good solution. Most of what I found involved setting the text when the page is being rendered server side or client side. But what I need for FuelMyRoute.com is a way to dynamically update the tweet text based on the user's activity in the page after it has rendered. (Specifically, based on the route provided by the user, I want to update the tweet text to say something specific about how much the user has saved per gallon of gas.)

The solution I went with uses the iframe Tweet Button, and basically you just need a bit of javascript to manipulate the URL that configures the iframe Tweet Button. I went with the iframe Tweet Button over the javascript Tweet Button because the javascript one manipulates the DOM and replaces your anchor tag with an iframe, etc. You could theoretically dynamically change the tweet text for the javascript Tweet Button but it would be a little brittle, being dependent on how the javascript Tweet Button renders itself.

Enough jibber jabber, on to the code! You start by adding an iframe Tweet Button to the page:

Then you need this function which updates the text parameter of the iframe Tweet Button's query string (which of course will cause the button to reload):

You can try it out right here. Click on the Tweet Button below and preview the message, which should be "Replace Me":

Now click on the button below which will call updateTweetButtonText('I just dynamically updated the text of a Tweet Button!'); and then click on the Tweet Button again to see that the preview tweet has been updated:

Marcus Christie's Blog

From the Notebook: An Ember Bootstrap Modal Dialog and How to Deal with state in Ember controllers

Bootstrap Modal Dialog for Ember

Ember Controllers Are Singletons

Odds and Ends

Responsive Webapp Conclusions

Recommendation

Other recommendations

Only two device classes: phone and desktop (or small and large)

Make everything optimized for touch

An alternative to responsive webapps: Device Classes

Researching Responsive Webapps

Consensual Hallucination

Making desktop app responsive

Desktop and mobile design patterns

Conclusions

Initial thoughts on Responsive Single Page Applications

Responsive Mobile UI Patterns

Separate "pages" (mobile) vs in-page controls (desktop)

List and detail views on separate pages (mobile) vs both on the same page (desktop)

Challenges with doing responsive SPA

Sizing of controls

Off screen view updates on mobile

Duplicate UIs

Conclusion

A Backbone-JQuery Mobile skeleton project -

jQuery.on

mobileinit

autoInitializePage

Managing Pages as Views

Enhancing pages

Minor stuff

Git client setup

Git global configuration

Excludes file

Whitespace

Credential helper

Aliases

Bash completions

Web viewer

push.default

merge.defaultToUpstream

Anything else?

Backbone Overview

What is Model-View-Controller (MVC)?

How does Backbone relate to traditional MVC?

Events

Model

Collection

View

Router

Sync

Additional Resources

Using Google's Places Autocomplete API to find directions

Disjunctive Normal Form: Figuring out what part of a WHERE claused matched

How to get to Disjunctive Normal Form?

Algebraic approach

Algorithmic approach

Which approach to take?

Git: How to delete a branch

CSS :empty - hiding a border when an element is empty

Bootstrap's Alert.js Plugin, line by line

Overview

What's this +function business?

use strict

Alert class definition

Alert close function

Finding the $parent to close

Custom events for before and after closing

Removing and fading out the Alert

Alert jQuery Plugin Definition

Alert noConflict

Alert Data API

Scala: Object equality and the canEqual method

Getting Object Equality Right

What is the canEqual method?

Does canEqual violate the Liskov Substitution Principle?

canEqual is a code smell

Scala: Understanding the self type annotation and how it relates to the Cake Pattern

What is the self type annotation?

What's this `+function` business?

`use strict`

Alert `close` function

Finding the `$parent` to close

Alert `noConflict`

What is the `canEqual` method?

Does `canEqual` violate the Liskov Substitution Principle?

`canEqual` is a code smell