Pixel-in-Gene

More Writing on NetTuts+

Sun, 12 May 2013 14:25:00 PDT

Alright, this blog has been quiet for a few months. But that doesn’t mean that I have stopped writing.

On the contrary, I am doing more of it as a contributing author at NetTuts+. The topics are quite varying but are all related to Web Development in one form or other. A sampling of my articles so far include:

10 Tips for Learning a New Technology
Promise based approach to Client side Validations
HTTP : A Protocol every Web Developer Must Know (Part 1, Part 2)
jQuery Widget Factory

Thanks to my editor, Jeffrey Way, I was also given the opportunity to create a Video course on the latest JS technologies like NodeJS, MongoDB, EmberJS, RequireJS, etc. This should be live soon and I’ll tweet the link once it is prime.

So, if you find this place a little quiet, be sure to check out NetTuts+.

My Key Takeaways from SMACSS

Sun, 23 Dec 2012 06:40:00 PST

A seemingly simple language yet a tangled mess of complexity. If you are picturing a giant CSS file from your website, you are on the right track. Yes, CSS can start out as a really simple language to learn but can be hard to master. The CSS chaos starts slowly and seems innocuous at first. Overtime as you accumulate features and more variations on your website, you see the CSS explode and you are soon fighting with the spaghetti monster.

Luckily this complexity can be brought under control. By following a few simple rules, you can bring order and structure to your growing pile of CSS rules.

These rules, as laid down by Scalable Modular Architecture for CSS (SMACSS), have a guiding philosophy:

Do one thing well
Be context-free (as far as possible)
Think in terms of the entire website/system instead of a single page
Separate layout from style
Isolate the major concerns for a webpage into layout, modules and states
Follow naming conventions
Be consistent

SMACSS in action

The above principles can be translated in the following ways:

Avoid id-selectors since you can only have one ID on a page. Rely on class, attribute and pseudo selectors
Avoid namespacing classes under an ID. Doing so limits those rules only to that section of the page. If the same rules needs to be applied on other sections, you will end up adding more selectors to the rule. This seems harmless at the outset but soon becomes a habit. Avoid it with vengeance.
Modules help in isolating pieces of content on the page. Modules are identified by classes and can be extended with sub-modules. By relying on the fact that you can apply multiple classes to a HTML tag, you can mix rules from modules and sub-modules into a tag.
The page starts out as a big layout container, which is then broken down into smaller layout containers such as header, footer, navigation, sidebar, content. This can go as deep as you wish. For example, the content area will be broken down further on most websites. When defining a layout rule make sure you don’t mix presentation rules such as fonts, colors, backgrounds or borders. Layout rules should only contain box-model properties like margins, padding, positioning, width, height, etc.,
The content inside a layout container is described via modules. Modules can change containers but always retain their default style. Variations in modules are handled as states and sub-modules. States are applied via class selectors, pseudo selectors or attribute selectors. Sub-modules are handled purely via class selectors.
Naming conventions such as below make it easier to identify the type of rule: layout, module, sub-module or state
- layout: .l-*
- state: .is-*
- module: .<name>
- sub module: .<name> .<name>-<state>
Be conscious of Depth of applicability. Making the rule deeply nested will tie the CSS to your HTML structure making it harder to reuse and increasing duplicate rules.

An example to tie it all together

Alright, there are lot of abstract ideas in here. Let’s do something concrete and build a simple webpage that needs to show a bunch of contact cards, like below:

Demo

There are few things to note here:

There are 4 modules: card, pic, company-info and contact-info
The card module has a sub-module: card-gov, for contacts who work for the government
The card and contact-info module change layouts via media queries.

/* ----- Picture ----- */
.pic {}
.pic-right {}

/* ----- Card ----- */
.card {}
@media screen and (max-width: 640px) {
  .card {  }
}
.card h4 {}

.card-gov {}
.card-gov .contact-info {}

/* ----- Company Info ----- */
.company-info {}

.company-info-title {}
.company-info-name {}

/* ----- Contact Info ----- */
.contact-info {}
@media screen and (max-width: 640px) {
  .contact-info {  }
}

.contact-info-field {}
.contact-info-field:after {}

Parallels to OO languages

To me the whole idea of SMACSS seems like an application of some of the ideas from OO languages. Here is a quick comparison:

Minimize or avoid Singletons: minimize or avoid #id selectors
Instances: tags in html which have a class applied
Single inheritance: Modules and Sub-modules
Mixins: context free rules via states and layouts

Summary

SMACSS can save you a lot of maintenance headache by following few simple rules. It may seem a little alien at first but after you do a simple project, it will become more natural. In the end, its all about increasing productivity and having a worry-free sleep ;–)

Some resources to learn more about SMACSS:

The SMACSS website
Presentation by Jonathan Snook about SMACSS
State based Design

Common Idioms in JavaScript development

Sun, 07 Oct 2012 12:55:00 PDT

These are some of the common idioms I find myself using again and again. I am going to keep this as a live document and will update as I discover more useful idioms.

Disclaimer: I’ll be using the Underscore library in all of my examples

Array.join to concatenate strings
Minimize use of if/else blocks by creating object hashes
Make the paramter value be of any type: string | number | array | function
Use IIFE to compute values on the fly

Use Array.join to concatenate strings

It is quite common to build html in strings, especially when you are writing a custom formatter or just plain building simple views in code. Lets say you want to output the html for 3 buttons:

var html = '<div class="button-set">' +
  '<span class="button">OK</span>' +
  '<span class="button">Apply</span>' +
  '<span class="button">Cancel</span>' +
'</div>';

This works, but consider the alternate version, where you build the strings as elements of an array and join them using Array.join().

var html = [
  '<div class="button-set">'
      '<span class="button">OK</span>',
      '<span class="button">Apply</span>',
      '<span class="button">Cancel</span>',
  '</div>'
].join('');

It reads a little better and can almost look like real-html with the identation ;)

Minimize use of if/else blocks by creating object hashes

Lets say you want perform a bunch of different actions based on the value of a certain parameter. For example, if you want to show different views based on the weather condition received via an AJAX request, you could do something like below:

function showView(type) {
  if (_.isObject(type)) {
      // read object structure and prepare view
  }
  else if (_.isString(type)) {
      // validate string and show the view
  }
}

function showWeatherView(condition){
  
  if (condition === 'sunny') showView('sunny-01');
  else if (condition === 'partly sunny') showView('sunny-02');
  else if (condition === 'cloudy') showView('cloudy-01');
  else if (condition === 'rain') showView({ type: 'rain-01', style:'dark' })
}

$.get('http://myapp.com/weather/today', function(response){
  
  var condition = response.condition;

  // Show view based on this condition
  showWeatherView(condition);
});

You will notice in showWeatherView(), there is lot of imperative noise with if/else statements. This can be removed with an object hash:

function showWeatherView(condition){

  var viewMap = {
      'sunny': 'sunny-01',
      'partly sunny': 'sunny-02',
      'cloudy': 'cloudy-01',
      'rain': { type: 'rain-01', style:'dark' }
  };   

  showView(viewMap[condition]);
}

If you want to support more views, it should be easier to add it to the viewMap hash. The general idea is to look at a piece of code and think in terms of data + code. What part is pure data and what part is pure code. If you can make the separation, you can easily capture the data part as an object-hash and write simple code to loop/process the data.

As a side note, if you want to eliminate the use of if/else, switch statements, you can have Haskell-style pattern-matching with the matches library.

Make the parameter value be of any-type

When you are building a simple utility library/module, it is good to expose an option that can be any of string, number, array or function type. This makes the option more versatile and allows for some logic to be executed each time the option value is needed. I first saw this pattern used in libraries like HighCharts and SlickGrid and found it very natural.

Let’s say you want to build a simple formatter. It can accept a string to be formatted using one of the pre-defined formats or use a custom formatter. It can also apply a chain of formatters, when passed as an array. You can have the API for the formatter as below:

function format(formatter, value) {
  var knownFormatters = {
      '###,#': function(value) {},
      'mm/dd/yyyy': function(value) {},
      'HH:MM:ss': function(value) {}
  },
      formattedValue = value;

  if (_.isString(formatter)) {

      // Lookup the formatter from list of known formatters
      formattedValue = knownFormatters[formatter](value);

  }
  else if (_.isFunction(formatter)) {

      formattedValue = formatter(value);

  }
  else if (_.isArray(formatter)) {

      // This could be a chain of formatters
      formattedValue = value;
      _.each(formatter, function(f) {
          formattedValue = format(f, formattedValue); // Note the recursive use format()
      });

  }

  return formattedValue;
}

As an addendum to a multi-type parameter, it is also common to normalize the parameter value to an object hash and remove type differences.

Use IIFE to compute on the fly

Sometimes you just need a little bit of code to set the value of an option. You can either do it by computing the value separately or do it inline by writing an Immediately Invoked Function Expression (IIFE):

var options = {
  title: (function(){
      var html = '<h1>' + titleText + '</h1>';
      var icons = '<div class="icon-set"><span class="icon-gear"></span></div>';

      return html + icons;
  })(),
  buttons: ['Apply', 'Cancel', 'OK']
};

In the above code there is little bit of computation for the title text. For simple code like above it is sometimes best to have the logic right in there for improved readability.

A simple organization scheme for handling routes in ExpressJS apps

Thu, 14 Jun 2012 18:54:00 PDT

The ExpressJS framework is one of the simpler yet very powerful web frameworks for NodeJS. It provides a simple way to expose GET / POST endpoints on your web application, which then serves the appropriate response. Getting started with ExpressJS is easy and the Guides on the ExpressJS website are very well written to make you effective in short order.

Moving towards a flexible app structure

When you have a simple app with a few endpoints, it is easy to keep everything self-contained right inside of the top-level app.js. However as you start buliding up more GET / POST endpoints, you need to have an organization scheme to help you manage the complexity. As a simple rule,

When things get bigger, they need to be made smaller ;–)

Fortunately, several smart folks have figured this out earlier and have come up with approaches that are wildly successful. Yes, I am talking about Rails and the principle of “Convention over Configuration”. So lets apply them to our constantly growing app.

Route management

Most of the routes (aka restful endpoints) that you expose on your app can be logically grouped together, based on a feature. For example, if you have some endpoints such as:

/login
/login/signup
/login/signup/success
/login/lostpassword
/login/forgotusername

… you can try grouping them under the “login” feature. Similarly you may have other endpoints dedicated to handle other workflows in your app, like uploading content, creating users, editing content, etc. These kind of routes naturally fit into a group and that’s the first cue for breaking them apart. As a first step, you can put the logically related GET / POST endpoints in their own file, eg: login.js. Since you may have several groups of routes, you will end up with lots of route files.

Putting all of these files at the top-level is definitely going to cause a clutter. So to simplify this further, put all of these files into a sub-folder, eg: /routes. The project structure now looks more clean:

project
  |- routes
  |   |- login.js
  |   |- create_users.js
  |   |- upload.js
  |   |- edit_users.js
  |- app.js

Since we are working with NodeJS, each file becomes a module and the objects in the module can be exposed via the exports object. We can establish a simple protocol that each route module must have an init function which we call from app.js, passing in the necessary context for the route. In case of the login this could look like so:

Routes in login.js

function init(app) {
  
  app.get('/login', function (req, res){

  });

  app.get('/login/signup', function (req, res){

  });

  app.get('/login/signup/success', function (req, res){

  });

  app.get('/login/lostpassword', function (req, res){

  });

  app.get('/login/forgotusername', function (req, res){

  });

}

If you are using a recent version of ExpressJS, 2.5.8 as of this writing, the command-line interface provides a way to quickly generate the express app. If you type express [options] name-of-the-app, it will generate a folder named name-of-the-app in the current working directory. Not surprisingly, express creates the /routes folder for you, which is already taking you in the right direction. I only learnt this recently and have so far been doing the hard work of starting from scratch each time. Sometimes spending a little more time on the manual helps! RTFM FTW.

Once we have the route files as described, it is easy to load them from app.js. Using the filesystem module we can quickly load each module and call init() on each one of them. We do this before the app is started. The app.js skeleton looks like so:

App skeleton app.js

var fs = require('fs'),
    path = require('path');

var RouteDir = 'routes',
    files = fs.readdirSync(RouteDir);

files.forEach(function (file) {
    var filePath = path.resolve('./', RouteDir, file),
        route = require(filePath);
    route.init(app);
});

Now we can just keep adding more routes, grouped in their own file and continue to build several endpoints without severerly complicating the app.js. The app.js file now follows the Open-Closed-Principle (app.js is open for extension but closed for modification).

In short…

As you can see, it is actually a simple idea, but when applied to other parts of your application, it can substantially reduce the maintenance overhead. So in summary:

Establish conventions to standardize a certain aspect of the program. In our case it was routes.
Group related items into their own module
Collect the modules into a logical folder and load from that folder

Quick sketching using SketchBook Pro + Wacom Intuos 4

Sun, 06 May 2012 18:11:00 PDT

Its been a while since I posted anything on this blog. Thought I’ll break the calm with a quick post about my recent sketch.

I generally use Autodesk SketchBook Pro (SBP) on my Mac for the intial doodling. I then develop a fairly finished sketch before importing it into Photoshop for any post-processing. Luckily SBP saves the files in PSD format, making it easy to do the Photoshop import. The following sketch was entirely done in SBP:

This was done in about 30 mins as a quick sketch to demonstrate the use of SBP and a Wacom tablet to a close friend. He was quite impressed and immediately ordered a bunch of items, including a Wacom Bamboo stylus for the iPad. I guess marketing wouldn’t be a bad alternate career!

BTW, the sketch is called Rain and Tears.

Animating Pie Slices using a custom CALayer

Tue, 21 Feb 2012 10:48:00 PST

It’s going to be a rather long post, so if you want to jump around, here are your way points:

First steps
1. A path for the slice
2. Animating the pie-slice
Raising the level of abstraction
1. Custom CALayer, the PieSliceLayer
2. Rendering the PieSliceLayer
It all comes together in PieView
1. Managing the slices
Demo and Source code

With a powerful platform like iOS, it is not surprising to have a variety of options for drawing. Picking the one that works best may sometimes require a bit of experimentation. Case in point: a pie chart whose slices had to be animated as the values changed over time. In this blog post, I would like to take you through various stages of my design process before I ended up with something close to what I wanted. So lets get started.

First steps

Lets quickly look at the array of options that we have for building up graphics in iOS:

Use the standard Views and Controls in UIKit and create a view hierarchy
Use the UIAppearance protocol to customize standard controls
Use UIWebView and render some complex layouts in HTML + JS. This is a surprisingly viable option for certain kinds of views
Use UIImageView and show a pre-rendered image. This is sometimes the best way to show a complex graphic instead of building up a series of vectors. Images can be used more liberally in iOS and many of the standard controls even accept an image as parameter.
Create a custom UIView and override drawRect:. This is like the chain-saw in our toolbelt. Used wisely it can clear dense forests of UI challenges.
Apply masking (a.k.a. clipping) on vector graphics or images. Masking is often underrated in most toolkits but it does come very handy.
Use Core Animation Layers: CALayer with shadows, cornerRadius or masks. Use CAGradientLayer, CAShapeLayer or CATiledLayer
Create a custom UIView and render a CALayer hierarchy

As you can see there are several ways in which we can create an interactive UI control. Each of these options sit at a different level of abstraction in the UI stack. Choosing the right combination can thus be an interesting thought-exercise. As one gains more experience, picking the right combination will become more obvious and also be a lot faster.

A path for the slice

With that quick overview of the UI options in iOS, lets get back to our problem of building an animated Pie Chart. Since we are talking about animation, it is natural to think about Core Animation and CALayers. In fact, the choice of a CAShapeLayer with a path for the pie-slice is a good first step. Using the UIBezierPath class, it is easier than using a bunch of CGPathXXX calls.

-(CAShapeLayer *)createPieSlice {
  CAShapeLayer *slice = [CAShapeLayer layer];
  slice.fillColor = [UIColor redColor].CGColor;
  slice.strokeColor = [UIColor blackColor].CGColor;
  slice.lineWidth = 3.0;
  
  CGFloat angle = DEG2RAD(-60.0);
  CGPoint center = CGPointMake(100.0, 100.0);
  CGFloat radius = 100.0;
  
  UIBezierPath *piePath = [UIBezierPath bezierPath];
  [piePath moveToPoint:center];
  
  [piePath addLineToPoint:CGPointMake(center.x + radius * cosf(angle), center.y + radius * sinf(angle))];
  
  [piePath addArcWithCenter:center radius:radius startAngle:angle endAngle:DEG2RAD(60.0) clockwise:YES];
  
//   [piePath addLineToPoint:center];
  [piePath closePath]; // this will automatically add a straight line to the center
  slice.path = piePath.CGPath;

  return slice;
}

The path consists of two radial lines originating at the center of the cirlce, with an arc between the end-points of the lines
The angles in the call to addArcWithCenter use the following unit-coordinate system:

DEG2RAD is a simple macro that converts from degrees to radians
When rendered the pie slice looks like below. The background gray circle was added to put the slice in the context of the whole circle.

Animating the pie-slice

Now that we know how to render a pie-slice, we can start looking at animating it. When the angle of the pie-slice changes we would like to smoothly animate to the new slice. Effectively the pie-slice will grow or shrink in size, like a radial fan of cards spreading or collapsing. This can be considered as a change in the path of the CAShapeLayer. Since CAShapeLayer naturally animates changes to the path property, we can give it a shot and see if that works. So, let’s say, we want to animate from the current slice to a horizontally-flipped slice, like so:

To achieve that, lets refactor the code a bit and move the path creation into its own method.

-(CGPathRef)createPieSliceWithCenter:(CGPoint)center
              radius:(CGFloat)radius
              startAngle:(CGFloat)degStartAngle
              endAngle:(CGFloat)degEndAngle {
  
  UIBezierPath *piePath = [UIBezierPath bezierPath];
  [piePath moveToPoint:center];
  
  [piePath addLineToPoint:CGPointMake(center.x + radius * cosf(DEG2RAD(degStartAngle)), center.y + radius * sinf(DEG2RAD(degStartAngle)))];
  
  [piePath addArcWithCenter:center radius:radius startAngle:DEG2RAD(degStartAngle) endAngle:DEG2RAD(degEndAngle) clockwise:YES];
  
  // [piePath addLineToPoint:center];
  [piePath closePath]; // this will automatically add a straight line to the center

  return piePath.CGPath;
}

-(CAShapeLayer *)createPieSlice {
  
  CGPoint center = CGPointMake(100.0, 100.0);
  CGFloat radius = 100.0;

  CGPathRef fromPath = [self createPieSliceWithCenter:center radius:radius startAngle:-60.0 endAngle:60.0];
  CGPathRef toPath = [self createPieSliceWithCenter:center radius:radius startAngle:120.0 endAngle:-120.0];

  CAShapeLayer *slice = [CAShapeLayer layer];
  slice.fillColor = [UIColor redColor].CGColor;
  slice.strokeColor = [UIColor blackColor].CGColor;
  slice.lineWidth = 3.0;
  slice.path = fromPath;

  
  CABasicAnimation *anim = [CABasicAnimation animationWithKeyPath:@"path"];
  anim.duration = 1.0;
  
  // flip the path
  anim.fromValue = (__bridge id)fromPath;
  anim.toValue = (__bridge id)toPath;
  anim.removedOnCompletion = NO;
  anim.fillMode = kCAFillModeForwards;
  
  [slice addAnimation:anim forKey:nil];
  return slice;
}

In the refactored code, createPieSlice: just calls the createPieSliceWithCenter:radius:startAngle:endAngle function for the from and to-paths and sets up an animation between these two paths. In action, this looks like so:

Yikes! That is definitely not what we expected. CAShapeLayer is morphing the paths rather than growing or shrinking the pie slices. Of course, this means we need to adopt more stricter measures for animating the pie slices.

Raising the level of abstraction

Clearly CAShapeLayer doesn’t understand pie-slices and has no clue about how to animate a slice in a natural manner. We definitely need more control around how the pie slice changes. Luckily we have an API that gives a hint at the kind of abstraction we need: a pie slice described in terms of {startAngle, endAngle}. This way our parameters are more strict and not as flexible as the points of a bezier path. By making these parameters animatable, we should be able to animate the pie-slices just the way we want.

Applying this idea to our previous animation example, the path can be said to be changing from {-60.0, 60.0} to {120.0, -120.0}. By animating the startAngle and endAngle, we should be able to make the animation more natural. In general, if you find yourself tackling a tricky problem like this, take a step back and check if you are at the right level of abstraction.

Custom CALayer, the `PieSliceLayer`

If a CAShapeLayer can’t do it, we probably need our own custom CALayer. Let’s call it the PieSliceLayer and give it two properties: … you guessed it… startAngle and endAngle. Any change to these properties will cause the custom layer to redraw and also animate the change. This requires following a few standard procedures as prescribed by Core Animation Framework.

Firstly don’t @synthesize the animatable properties and instead mark them as @dynamic. This is required because Core Animation does some magic under the hood to track changes to these properties and call appropriate methods on your layer.

PieSliceLayer.h

#import <QuartzCore/QuartzCore.h>

@interface PieSliceLayer : CALayer


@property (nonatomic) CGFloat startAngle;
@property (nonatomic) CGFloat endAngle;

@property (nonatomic, strong) UIColor *fillColor;
@property (nonatomic) CGFloat strokeWidth;
@property (nonatomic, strong) UIColor *strokeColor;
@end

PieSliceLayer.m

#import "PieSliceLayer.h"

@implementation PieSliceLayer

@dynamic startAngle, endAngle;
@synthesize fillColor, strokeColor, strokeWidth;

...

@end

Override actionForKey: and return a CAAnimation that prepares the animation for that property. In our case, we will return an animation for the startAngle and endAngle properties.
Override initWithLayer: to copy the properties into the new layer. This method gets called for each frame of animation. Core Animation makes a copy of the presentationLayer for each frame of the animation. By overriding this method we make sure our custom properties are correctly transferred to the copied-layer.
Finally we also need to override needsDisplayForKey: to tell Core Animation that changes to our startAngle and endAngle properties will require a redraw.

PieSliceLayer.m

-(id<CAAction>)actionForKey:(NSString *)event {
  if ([event isEqualToString:@"startAngle"] ||
      [event isEqualToString:@"endAngle"]) {
      return [self makeAnimationForKey:event];
  }
  
  return [super actionForKey:event];
}

- (id)initWithLayer:(id)layer {
  if (self = [super initWithLayer:layer]) {
      if ([layer isKindOfClass:[PieSliceLayer class]]) {
          PieSliceLayer *other = (PieSliceLayer *)layer;
          self.startAngle = other.startAngle;
          self.endAngle = other.endAngle;
          self.fillColor = other.fillColor;

          self.strokeColor = other.strokeColor;
          self.strokeWidth = other.strokeWidth;
      }
  }
  
  return self;
}

+ (BOOL)needsDisplayForKey:(NSString *)key {
  if ([key isEqualToString:@"startAngle"] || [key isEqualToString:@"endAngle"]) {
      return YES;
  }
  
  return [super needsDisplayForKey:key];
}

With that we now have a custom PieSliceLayer that animates changes to the angle-properties. However the layer does not display any visual content. For this we will override the drawInContext: method.

Rendering the PieSliceLayer

Here we draw the slice just the way we did earlier. Instead of using UIBezierPath, we now go with the Core Graphics calls. Since the startAngle and endAngle properties are animatable and also marked for redraw, this layer will be rendered each frame of the animation. This will give us the desired animation when the slice changes its inscribed angle.

PieSliceLayer.m

-(void)drawInContext:(CGContextRef)ctx {
  
  // Create the path
  CGPoint center = CGPointMake(self.bounds.size.width/2, self.bounds.size.height/2);
  CGFloat radius = MIN(center.x, center.y);
  
  CGContextBeginPath(ctx);
  CGContextMoveToPoint(ctx, center.x, center.y);
  
  CGPoint p1 = CGPointMake(center.x + radius * cosf(self.startAngle), center.y + radius * sinf(self.startAngle));
  CGContextAddLineToPoint(ctx, p1.x, p1.y);

  int clockwise = self.startAngle > self.endAngle;
  CGContextAddArc(ctx, center.x, center.y, radius, self.startAngle, self.endAngle, clockwise);

  CGContextClosePath(ctx);
  
  // Color it
  CGContextSetFillColorWithColor(ctx, self.fillColor.CGColor);
  CGContextSetStrokeColorWithColor(ctx, self.strokeColor.CGColor);
  CGContextSetLineWidth(ctx, self.strokeWidth);

  CGContextDrawPath(ctx, kCGPathFillStroke);
}

It all comes together in PieView

When we originally started, we wanted to build a Pie Chart that animated changes to its slices. After some speed bumps we got to a stage where a single slice could be described in terms of start/end angles and have any changes animated.

If we can do one slice, we can do multiples! A Pie Chart is a visualization for an array of numbers, where each numbers is an instance of the PieSliceLayer. The size of a slice depends on its relative value within the array. An easy way to get the relative value is to normalize the array and use the normal value [0, 1] to arrive at the angle of the slice, ie. normal * 2 * M_PI. For example, if the normal value is 0.5, the angle of the slice will be M_PI or 180°.

Managing the slices

The PieView manages the slices in a way that makes sense for a Pie Chart. Given an array of numbers, the PieView takes care of normalizing the numbers, creating the right number of slices and positioning them correctly in the pie. Since PieView will be a subclass of UIView, we also have the option to introduce some touch interaction later. Having a UIView that hosts a bunch of CALayers is a common approach when dealing with an interactive element like the PieChart.

The PieView exposes a sliceValues property which is an NSArray of numbers. When this property changes, PieView manages the CRUD around the PieSliceLayers. If there are more numbers than slices, PieView will add the missing slices. If there are fewer numbers than slices, it removes the excess. All the existing slices are updated with the new numbers. All of this happens in the updateSlices method.

PieView.h

#import <UIKit/UIKit.h>

@interface PieView : UIView

@property (nonatomic, strong) NSArray *sliceValues;

-(id)initWithSliceValues:(NSArray *)sliceValues;
@end

PieView.m

#import "PieView.h"
#import "PieSliceLayer.h"
#import <QuartzCore/QuartzCore.h>

#define DEG2RAD(angle) angle*M_PI/180.0


@interface PieView() {
  NSMutableArray *_normalizedValues;
  CALayer *_containerLayer;
}

-(void)updateSlices;
@end

@implementation PieView
@synthesize sliceValues = _sliceValues;

-(void)doInitialSetup {
  _containerLayer = [CALayer layer];
  [self.layer addSublayer:_containerLayer];
}

- (id)initWithFrame:(CGRect)frame
{
    self = [super initWithFrame:frame];
    if (self) {
      [self doInitialSetup];
    }
  
    return self;
}

-(id)initWithCoder:(NSCoder *)aDecoder {
  if (self = [super initWithCoder:aDecoder]) {
      [self doInitialSetup];
  }
  
  return self;
}

-(id)initWithSliceValues:(NSArray *)sliceValues {
  if (self) {
      [self doInitialSetup];
      self.sliceValues = sliceValues;
  }
  
  return self;
}

-(void)setSliceValues:(NSArray *)sliceValues {
  _sliceValues = sliceValues;
  
  _normalizedValues = [NSMutableArray array];
  if (sliceValues) {

      // total
      CGFloat total = 0.0;
      for (NSNumber *num in sliceValues) {
          total += num.floatValue;
      }
      
      // normalize
      for (NSNumber *num in sliceValues) {
          [_normalizedValues addObject:[NSNumber numberWithFloat:num.floatValue/total]];
      }
  }
  
  [self updateSlices];
}

-(void)updateSlices {
  
  _containerLayer.frame = self.bounds;
  
  // Adjust number of slices
  if (_normalizedValues.count > _containerLayer.sublayers.count) {
      
      int count = _normalizedValues.count - _containerLayer.sublayers.count;
      for (int i = 0; i < count; i++) {
          PieSliceLayer *slice = [PieSliceLayer layer];
          slice.strokeColor = [UIColor colorWithWhite:0.25 alpha:1.0];
          slice.strokeWidth = 0.5;
          slice.frame = self.bounds;
          
          [_containerLayer addSublayer:slice];
      }
  }
  else if (_normalizedValues.count < _containerLayer.sublayers.count) {
      int count = _containerLayer.sublayers.count - _normalizedValues.count;

      for (int i = 0; i < count; i++) {
          [[_containerLayer.sublayers objectAtIndex:0] removeFromSuperlayer];
      }
  }
  
  // Set the angles on the slices
  CGFloat startAngle = 0.0;
  int index = 0;
  CGFloat count = _normalizedValues.count;
  for (NSNumber *num in _normalizedValues) {
      CGFloat angle = num.floatValue * 2 * M_PI;
      
      NSLog(@"Angle = %f", angle);
      
      PieSliceLayer *slice = [_containerLayer.sublayers objectAtIndex:index];
      slice.fillColor = [UIColor colorWithHue:index/count saturation:0.5 brightness:0.75 alpha:1.0];
      slice.startAngle = startAngle;
      slice.endAngle = startAngle + angle;
      
      startAngle += angle;
      index++;
      hue += num.floatValue;
  }
}
@end

There is one thing we didn’t do yet, which is enabling some touch interaction. I’ll leave that as a reader exercise for now.

Demo and Source code

With all that reading you did so far, your eyes are probably thirsty for some visuals. Well, treat yourself with the YouTube video and the github source on the side.

Simple helper method for async testing with Jasmine and RequireJS

Wed, 14 Dec 2011 14:40:00 PST

Unit testing in Javascript, especially with RequireJS can be a bit of challenge. Jasmine, which is our unit testing framework does not have any out of the box support for RequireJS. I have seen a few ways of integrating RequireJS but that requires hacking the SpecRunner.html file, the main test harness that executes all jasmine tests. That wasn’t really an option for us as we were using a ruby gem called jasmine to auto generate this html file from our spec files. There is however an experimental gem created by Brendan Jerwin that provides RequireJS integration. We did consider that option before ruling it out for lack of official support. After a bit of flailing around, we finally hit upon a little nugget in the core jasmine framework that seemed to provide a solution.

Async tests in Jasmine

For a long time, most of our tests used the standard prescribed procedure in jasmine, which is describe() with a bunch of it()s. This worked well for the most part until we switched to RequireJS as our script loader. Then there was only blood red on our test pages.

Clearly jasmine and RequireJS have no mutual contract, but there is a way to run async tests in jasmine with methods like runs(), waits() and waitsFor(). Out of these, runs() and waitsFor() were the real nuggets, which complement each other when running async tests.

waitsFor() takes in a function that should return a boolean when the work item has completed. Jasmine will keep calling this function until it returns true, with a default timeout of 5 seconds. If the worker function doesn’t complete by that time, the test will be marked as a failure. You can change the error message and the timeout period by passing in additional arguments to waitsFor().

runs() takes in a function that is called whenever it is ready. If a runs() is preceded by a waitsFor(), it will execute only when the waitsFor() has completed. This is great since it is exactly what we need to make our RequireJS based tests to run correctly. In code, the usage of waitsFor() and runs() looks as shown below. Note that I am using CoffeeScript here for easier readability.

— Short CoffeeScript Primer —
In CoffeeScript, the -> (arrow operator) translates to a function(){} block. Functions can be invoked without the parenthesis,eg: foo args is similar to foo(args). The last statement of a function is considered as the return value. Thus, () -> 100 would become function(){ return 100; } “With this primer, you should be able to follow the code snippet below.”

waitsFor() and runs()

    it "should do something nice", ->
        waitsFor ->
          isWorkCompleted()

        runs ->
            completedWork().doSomethingNice()
  

Jasmine meets RequireJS

waitsFor() along with runs() holds the key to running our RequireJS based tests. Within waitsFor() we wait for the RequireJS modules to load and return true whenever those modules are available. In runs() we take those modules and execute our test code. Since this pattern of writing tests was becoming so common, I decided to capture that into a helper method, called ait().

Helper method for running RequireJS tests

ait = (description, modules, testFn)->
    it description, ->
        readyModules = []
        waitsFor ->
            require modules, -> readyModules = arguments
            readyModules.length is modules.length # return true only if all modules are ready

        runs ->
            arrayOfModules = Array.prototype.slice.call readyModules
            testFn(arrayOfModules...)

If are wondering why the name ait(), it is just to keep up with the spirit of jasmine methods like it for the test case and xit for ignored test case. Hence ait, which stands for “async it”. This method takes care of waiting for the RequireJS modules to load (which are passed in the modules argument) and then proceeding with the call to the testFn in runs(), which has the real test code. The testFn takes the modules as individual arguments. Note the special CoffeeScript syntax arrayOfModules... for the expansion of an array into individual elements.

The ait method really reads as: it waitsFor() the RequireJS modules to load and then runs() the test code

To make things a little clear, here is an example usage:

Example usage of ait()

describe 'My obedient Model', ->

    ait 'should do something nice', ['obedient_model', 'sub_model'], (ObedientModel, SubModel)->
        subModel = new SubModel
        model = new ObedientModel(subModel)
        expect(model.doSomethingNice()).toEqual "Just did something really nice!"
      

The test case should do something nice, takes in two modules: obedient_model and sub_model, which resolve to the arguments: ObedientModel and SubModel, and then executes the test code. Note that I am relying on the default timeout for the waitsFor() method. So far this works great, but that may change as we build up more tests.

Using jQuery.Deferred() and RequireJS to Lazy Load Google Maps API

Tue, 18 Oct 2011 05:38:00 PDT

In the world of jQuery or for that matter, any JavaScript library, callbacks are the norm for programming asynchronous tasks. When you have several operations dependent on the completion of some other operation, it is best to handle them as a callback. At a later point when your dependent task completes, all of the registered callbacks will be triggered.

This is a simple and effective model and works great for UI applications. With jQuery.Deferred(), this programming model has been codified with a set of utility methods.

$.Deferred() is the entry point for dealing with deferred operations. It creates a “promise” (a.k.a Deferred object) to trigger all the registered done() or then() callbacks once the Deferred object goes into the resolve() state. This is according to the CommonJS specification for Promises. I am not going to cover all the details of $.Deferred(), since the jQuery docs do a much better job. Instead, I’ll jump right into the main topic of this post.

The soup of AMD, $.Deferred and Google Maps

In one of my recent explorations with web apps, the AMD pattern turned out to be extremely useful. AMD, with the RequireJS library, forces a certain structure on your project and makes building large web apps more digestible. Abstractions like the require/define calls allows building apps that are more composable and extensible. It sure is a great way to think about composable JS apps in contrast to the crude <script> tags.

With these abstractions, it was easier to think of the app as a set of modules. Some modules provide base level services, while others depend on such service-modules. One particular module, which also happens to be the entry point into the app, was heavily dependent on the Google Maps API. Early on, it was decided to never keep the user waiting for the maps to load and allow interaction right from the get go.This meant that they could do some map-related tasks even before the maps API had loaded. Although this felt impossible at the onset, it turned out to be quite easy, all thanks to $.Deferred().

The first step was to wrap the Google Maps API in a GoogleMaps object. This hides away the details about loading the maps while allowing the user to carry on with the map related tasks.

Wrapping the google maps API

function GoogleMaps() {
  
}

GoogleMaps.prototype.init = function() {
  
};

GoogleMaps.prototype.createMap = function(container) {
};

GoogleMaps.prototype.search = function(searchText) {
};

GoogleMaps.prototype.placeMarker = function(options) {
};

The calls to createMap, search and placeMarker need to be queued up until the maps API has loaded. We start off with a single $.Deferred() object, _mapsLoaded

The deferred object

_mapsLoaded = $.Deferred()

function GoogleMaps() {
  // ...
}

Then in each of the methods mentioned earlier, we wrap the actual code inside a deferred.done(), like so:

Wrapping calls in deferred.done()

function GoogleMaps() {
    _mapsLoaded.done(_.bind(function() {
        this.init();
    }, this));
}

GoogleMaps.prototype.init = function() {
};

GoogleMaps.prototype.createMap = function(container) {
    _mapsLoaded.done(_.bind(function() {
      // create the maps object
    }, this));
};

GoogleMaps.prototype.search = function(searchText) {
    _mapsLoaded.done(_.bind(function() {
      // search address
    }, this));
};

GoogleMaps.prototype.placeMarker = function(options) {
    _mapsLoaded.done(_.bind(function() {
      // position marker
    }, this));
};
  

With this, we can continue making calls to each of these methods as if the maps API is already loaded. Each time we make a call, it will be pushed into the deferred queue. At some point, when the maps API is loaded, we need to call a resolve() on the deferred object. This will cause the queue of calls to be flushed and resulting in real work being done.

One aside on the code above is the use of _.bind(function(){}, this)_. This is required because the callback to done() changes the context of this. To keep it pointing to the GoogleMaps instance, we employ _.bind().

Resolving the deferred object

window.gmapsLoaded = function() {
    delete window.gmapsLoaded;
    _mapsLoaded.resolve();
};

require(['http://maps.googleapis.com/maps/api/js?sensor=true&callback=gmapsLoaded']);
  

The google maps API has an async loading option with a callback name specified in the query parameter for the api URL. When the api loads, it will call this function (in our case: gmapsLoaded). Note that this needs to be a global function, ie. on the window object. A require call (from RequireJS) makes it easy to load this script.

Once the callback is made, we finally call resolve() on our deferred object: _mapsLoaded. This will trigger the enqueued calls and the user starts seeing the results of his searches.

Summary

In short, what we have really done is:

Abstract the google maps API with a wrapper object
Create a single $.Deferred() object
Queue up calls on the maps API by wrapping the code inside done()
Use the async loading option of google maps api with a callback
In the maps callback, call resolve() on the deferred object
Make the user happy

Demo

In the following demo, you can start searching on an address even before the map loads. Go ahead and try it. I have deliberately put in a 5 second delay on the call to load the maps API, just for a flavor of 3G connectivity!

Don’t forget to browse the code in your Chrome Inspector. You do use Chrome, don’t you? ;–)

Tips for Speeding Up Octopress Site Generation

Thu, 29 Sep 2011 05:42:00 PDT

As I blogged about earlier, Octopress is a great framework for writing blog posts and packs in all the features for writing a code-centric blogs. Of course, it goes without saying that the blog also looks awesome as if designed by a true designer. Some of the nicer things about writing posts is that there are rake tasks that do most of the grunt work:

rake new_post[“Just type the title of the post here in plain English”]
This will create a new file under source/_posts called 2011-09-29-just-type-the-title-of-the-post-here-in-plain-english.markdown
rake new_page[about]
This will create a new page under source/about, called index.markdown
rake preview
This sets up a local webserver on http://localhost:4000 and starts monitoring the source folder for any changes. It automatically generates the corresponding HTML/CSS for the Markdown/SASS files respectively.

Speed up

If you have just migrated from a Wordpress blog or have lots of posts under your source/_posts, the rake task that generates the HTML output can take a very long time (several minutes). Obviously if you are just working on one post, there is no need to wait for the entire site to generate. What you are looking for is the rake isolate[partial_post_name] task.

Using rake isolate, you can “isolate” only that post you are working on and move all the others to the source/_stash folder. The partial_post_name parameter is just some words in the file name for the post. For example, if I want to isolate the post from the earlier example, I would use

rake isolate[plain-english]

This will move all the other posts to source/_stash and only keep the 2011-09-29-just-type-the-title-of-the-post-here-in-plain-english.markdown post in source/_posts. You can also do this while you are running rake preview. It will just detect a massive change and only regenerate that one post from then on.

All set to publish

When you are ready to publish your site, just run rake integrate and it will pull all the posts from source/_stash and put them under source/_posts. Now you can run rake generate and then rake deploy to publish your updated blog.

If these seem like lot of commands to remember, don’t worry, they will become second nature once you do it few times. As a summary, below are all the tasks that we talked about in this post. The description of each task comes from the Rakefile used by Octopress. I just did a rake list -T to get a dump of all the tasks.

rake new_post[title]: Begin a new post in source/_posts
rake new_page[filename]: Create a new page in source/(filename)/index.markdown
rake generate: Generate jekyll site
rake deploy: Default deploy task
rake preview: Preview the site in a web browser
rake isolate[filename]: Move all other posts than the one currently being worked on to a temporary stash location (stash) so regenerating the site happens much quicker
rake integrate: Move all stashed posts back into the posts directory, ready for site generation

Switching to the Octopress Blogging Engine

Mon, 12 Sep 2011 17:43:00 PDT

I have been using Wordpress for few years now and have been very happy with its features. In the past year, I have tried several times to change the theme on my blog and also semantify my posts by using Markdown as my de facto style. Of course, none of it happened and I was still using a combination of HTML and Rich Text Editor for formatting my posts.The more I delayed, the more I realized that there were a lot more reasons to NOT like Wordpress:

I wanted to use Markdown to write all my posts and Wordpress forced me to use HTML. I could certainly use some plugins to upload a markdown file which would then convert it into html, but that meant I had to store these markdown files in the wordpress database: less than optimal.
Code formatting was not an easy task. I used Live Writer as my primary blog editor and it had a few plugins that can give you inline code highlighting. Although you get real time view of your syntax highlighted code, it internally converted everything to HTML and discarded the original code snippet. Also you had to be careful about editing around that code snippet as a simple delete in the wrong place would require redoing the whole process. I felt it was too much work just to get some code highlighting.
The Backup and local testing scenario was involving. For backup, I could either export all my posts in WXR format or take a dump of my database. To re-create my blog locally meant getting an installation of MAMP and then importing the WXR or the database backup. I would have preferred a less intrusive approach to try out my wordpress site locally.
The wordpress technology stack was not very exciting for me. I never really enjoyed PHP and learnt it only to maintain my Wordpress site.

Exploring beyond Wordpress

I had seen a few bloggers use GitHub as their blogging engine with the Jekyll framework to auto-generate their HTML pages from their markdown posts. This was very inviting except for the fact that I had to store all my posts publicly on Github. Even if I purchased a private plan from Github, the storage allocated was quite minimal. GitHub for me was definitely not cost effective.

About this time, I saw a tweet from Matt Gemmell where he migrated from Wordpress to a different engine called Octopress. After reading his blog entry, I realized this was exactly the kind of framework I wanted. Matt has lot more content than I do and seeing him convert his blog successfully gave me the courage to do the same. Thus began an almost 10 day journey to convert my Wordpress blog to an Octopress blog!

There are many things to like about Octopress:

Write all my posts in Markdown
Default theme is very beautiful with rich support for styling via Compass/SASS
Modifying the theme is simple as its based on Jekyll. If you haven’t explored Jekyll yet, I strongly encourage to give it a try.
Writing plugins is also quite simple and uses the Liquid templating system
My entire blog is contained within a folder from which I can generate the HTML
Uploading is taken care with a rake task to deploy (Did I mention Octopress uses Ruby!)
I can preview my site locally with a simple rake preview command that starts up a local web server. It monitors changes to my blog and auto generates the html. This is great for composing posts and testing on the fly.
Excellent integration with social features like Google+, Twitter, Disqus, etc.
The Octopress tagline says its “the blogging framework for hackers” :–)

Migrating Wordpress posts

This was the most elaborate part of the process. Octopress requires that you do write all your posts in Markdown or Textile, however my Wordpress posts were all plain html. So I needed some converter that would do this transformation for me. Luckily on Matt’s blog I read about the exitWP plugin that takes care of this conversion. Although not seamless, exitWP did give me a good starting ground since it converts all the posts to a Jekyll-compliant site.

I did have to go in and change several of my posts that used code snippets. I had been using a variety of code prettifiers over the years and the corresponding HTML was not the best for a Markdown conversion. It did mess up lot of my posts and I spent several hours touching up the Markdown text.

I also got the chance to fix some of my old Urls that were still pointing to my old blog on Live Spaces. I also decided to make all my internal blog links relative and this required a combination of grep/awk and some manual intervention to fix up all the links. Overall it was a fun exercise experimenting with some bash shell commands and a mix of some ruby scripting.

Migrating Wordpress comments to Disqus

Octopress has excellent integration with Disqus, a hosted comment management system. Disqus works by linking all the comments to a specific Url. As long as your posts maintain the same Url you can just use Disqus to import all of your comments into your octopress blog. In my case, my comments were all on Wordpress and I had to first import them into Disqus. As it turns out, this wasn’t a straightforward process.

I started by exporting my comments from Wordpress in the standard WXR Xml format. When I tried to import this file into Disqus, it choked by complaining that the <link> tags were missing. The <link> tag contains the url that links the post to the comments. To fix that I wrote some simple ruby code to update the WXR with the proper <link> tags. Now trying the import again inside Disqus went through without issues and all my comment threads got pulled in. The threads however were using the raw wordpress url (http://blog.pixelingene.com/?p=123_) and I wanted to use a more semantic url of the form http://blog.pixelingene.com/year/month/the-post-slug_. To fix this I created a simple Url map (CSV) and used the Disqus Url Mapping Tool to fix these links.

Finally with all that done, my comments were safe and sound inside Disqus, with the right permalink-Urls. Now the next part was to link them up with my blog. Luckily this is as simple as specifying a disqus_short_name in the Octopress config file!

Url Rewrites and other changes

Now that I had chosen to use a semantic permalink to my posts, I also had to make sure my existing links to the posts continued working. This was a matter to having some redirects set up on my website. I used the standard Apache directives (RewriteCond, RewriteRule) in my .htaccess to permanently redirect all of my old urls.

A few other things I had to do include:

404 page
Plugins (Liquid Tags) to embed Silverlight apps and Youtube videos
Change the feed Url from the default /atom.xml to my FeedBurner url

The one thing I havent’ done yet is modify the theme from the default. I’ll probably get to it one of these days.

Epilogue

So that’s my experience with the Wordpress to Octopress migration. Although not a smooth transition, it wasn’t terribly bad and I actually enjoyed the process using a variety of tools. I have tried my best to make sure that all existing wordpress links, images, download links, demos, etc. continue working, but there is always that infinitesimal probability of missing something. If something does break, I’ll find out in one way or other. Until then “enjoy the new blog!”

Be careful declaring properties in CoffeeScript

Thu, 25 Aug 2011 17:36:57 PDT

In JavaScript, if you set a property on the prototype, it is like a static property that is shared by all instances of the Function. This is common knowledge in JavaScript and quite visible in the code. However if you are writing all your code in CoffeeScript, this fact gets hidden away by the way you declare properties.

Properties in CoffeeScript

class Site extends Backbone.view
  staticProp: "hello"

  initialize: ->
    @instanceProp: "instance hello"

If you declare properties without the @ symbol, you are effectively creating properties on the prototype of the class. This of course works great if you want a shared property but certainly not the way to go if you want per-instance properties. I missed out using the @ symbol and my app went bonkers. This simple oversight cost me fair bit of time debugging it. The right thing to do was using the @property syntax, since I needed per-instance properties. In the code snippet shown above, the staticProp is a property on the prototype of the Site function. @instanceProp is an instance property that will be available on each instance of Site. CoffeeScript translates the above source to the following JavaScript:

Compiled JavaScript output

var Site;
var __hasProp = Object.prototype.hasOwnProperty, __extends = function(child, parent) {
  for (var key in parent) { if (__hasProp.call(parent, key)) child[key] = parent[key]; }
  function ctor() { this.constructor = child; }
  ctor.prototype = parent.prototype;
  child.prototype = new ctor;
  child.__super__ = parent.prototype;
  return child;
};
Site = (function() {
  __extends(Site, Backbone.view);
  function Site() {
    Site.__super__.constructor.apply(this, arguments);
  }
  Site.prototype.staticProp = "hello";
  Site.prototype.initialize = function() {
    return {
      this.instanceProp: "instance hello"
    };
  };
  return Site;
})();

As you can see, staticProp (line# 15)is set on the Site.prototype and instanceProp (line# 18) is on the instance (this) of Site. So the take away is:

Be careful while declaring properties in CoffeeScript

CoffeeScript offers a lot of syntax sugar which makes programming JavaScript a lot more fun. Do check out the website for other interesting features.

Progressive reveal animations in SVG using a

Thu, 11 Aug 2011 19:46:24 PDT

In the previous post we saw how the D3.js library could be used to render tree diagrams. If you haven’t read that post yet, I would encourage reading it as we will be expanding on it in this post.

Now that we have a nice tree diagram of a hierarchy, it would be good to build in some interactions. After all, given a tree, one would certainly like to click on the nodes and see something happening. Lets do that by animating the path from the clicked node all the way to the root. To pull this off, we need three things:

A set of all nodes from the clicked node to the root
A set of all links (paths) from the clicked node back to the root
A revealing animation that progressively draws the paths from the clicked node to the root

The first two parts are easy and we have already seen that in the previous post. d3.layout.tree has a method called nodes() that gives us the collection of the nodes with their (x, y) locations and links() gives all links between the nodes. We will use the nodes collection to traverse the parent chain from the clicked node all the way to the root. Once we have the nodes along the parent chain, we use that to select the links that lie between each of these nodes. With the links between the nodes, the last part is to animate them into view. The animation part is the most interesting and also the topic of this post.

Animating the path to root

Now that we have the links between the nodes, the next step is to simply draw the SVG Path segments connecting these nodes. We will keep these path segments in its own SVG Group for easier manipulation. To animate these paths, there are two different approaches we can take:

We can draw the path progressively by setting the SVG Path data in each time interval of the animation OR
We can use a clipping path for the SVG Group and grow the bounds of the path from right to left. As the clipping path grows in size, it reveals more of the underlying group (which contains the paths), thus animating the path from the clicked node to root. This technique can even be used for progressively revealing complicated graphics.

I am adopting the later approach for this post. To set this up, we first need to add a <clipPath> node to the <svg>. We will also give it an id, so we can reference it later. This clip-path is going to be a <rect> since that is all we need. The code below sets up the clipping path for the <group> that contains the paths to root. The variable animGroupholds the reference to this group.

var svgRoot = d3.select(containerName)
    .append("svg:svg").attr("width", size.width).attr("height", size.height);

// Add the clipping path
svgRoot.append("svg:clipPath").attr("id", "clipper")
    .append("svg:rect")
    .attr('id', 'clip-rect');

var layoutRoot = svgRoot
    .append("svg:g")
    .attr("class", "container")
    .attr("transform", "translate(" + maxLabelLength + ",0)");

// set the clipping path
var animGroup = layoutRoot.append("svg:g")
    .attr("clip-path", "url(#clipper)");

Note that we have also set up an “id” for the <rect> (#clip-rect), which we will use later for animating the clipping path. The “click” handler To kick off the animation, we will detect a click happening on a node and then draw the path from the clicked node to the root. In the code below we do this using d3.js’ event API: the on(“event”) method.

function setupMouseEvents()
{
    ui.nodeGroup.on('mouseover', function(d, i)
    {
        d3.select(this).select("circle").classed("hover", true);
    })
        .on('mouseout', function(d, i)
        {
            d3.select(this).select("circle").classed("hover", false);
        })
        .on('click', function(nd, i)
        {
            // Walk parent chain
            var ancestors = [];
            var parent = nd;
            while (!_.isUndefined(parent)) {
                ancestors.push(parent);
                parent = parent.parent;
            }

            // Get the matched links
            var matchedLinks = [];
            ui.linkGroup.selectAll('path.link')
                .filter(function(d, i)
                {
                    return _.any(ancestors, function(p)
                    {
                        return p === d.target;
                    });
                })
                .each(function(d)
                {
                    matchedLinks.push(d);
                });

            animateParentChain(matchedLinks);
        });
}

In the the “click” event handler, we traverse the parent links back to the root and record all the ancestors in the path. We then filter all the rendered links (<path>) by picking only the ones that contain the nodes in the ancestors list. This becomes our list of matched links. Using these links we can now finally handle the animation that progressively reveals the emboldened path back to the root.

Back to my Mac root

Since we have all the links that take us from the clicked node to the root, we apply the same method that we used earlier to render the links. Using d3.diagonal(), we can generate the <path> data between the ancestor nodes. Only this time, the path will be rendered with a class set to “selected”, which emboldens the route back to the root.

function animateParentChain(links)
{
    var linkRenderer = d3.svg.diagonal()
        .projection(function(d)
        {
            return [d.y, d.x];
        });

    // Links
    ui.animGroup.selectAll("path.selected")
        .data([])
        .exit().remove();

    ui.animGroup
        .selectAll("path.selected")
        .data(links)
        .enter().append("svg:path")
        .attr("class", "selected")
        .attr("d", linkRenderer);

    // Animate the clipping path
    var overlayBox = ui.svgRoot.node().getBBox();

    ui.svgRoot.select("#clip-rect")
        .attr("x", overlayBox.x + overlayBox.width)
        .attr("y", overlayBox.y)
        .attr("width", 0)
        .attr("height", overlayBox.height)
        .transition().duration(500)
        .attr("x", overlayBox.x)
        .attr("width", overlayBox.width);
}
  

Once the paths have been rendered, we set the clipping path starting with a zero-width <rect>, which is then animated to the full width of the tree-diagram. It is in this animation of the clipping-path where you will see the path drawing itself out, giving us the final effect we were looking for!

Demo

You can see this code in action here.

Building a tree diagram in D3.js

Wed, 20 Jul 2011 09:25:41 PDT

In the past few weeks, I have spent some time evaluating some visualization frameworks in Javascript. The most prominents ones include: Javascript InfoVis Tookit, D3 and Protovis. Each of them is feature rich and provides a varieties of configurable layouts. In particular I was impressed with D3 as it gives a nice balance of features and flexibility and allowed me to build just the visualizations I wanted. In this post, I want to take a quick dive into using D3 for building a tree diagram.

A brief course on D3

One of the most striking features of the D3 framework is the use of selections, which allows you to add, update and remove elements in one single chained call. It does this by maintaining an inner-join between the data and the render-elements. This is a pretty powerful feature and greatly aids in building visualizations.

Every render element has an __data__ property that contains the bound data. New render elements will not have the __data__ property and will be created. Existing render elements will get updated and render-elements that have __data__ but no corresponding presence in the new data set will be removed. With that context, the call chain below should look more meaningful.

layoutRoot.selectAll("path.link")
.data(links)
.enter()
.append("svg:path")
.attr("class", "link")
.attr("d", link);
  

This selects all SVG Path elements with a class name of “link” from the parent element: layoutRoot. We enter the selection with a binding to data(), followed by enter(). By entering the selection, we create the inner-join which will automatically know which elements to create and which ones to update. These calls are part of the Selection API. D3 also has APIs for doing animations (Transitions), data processing, computing a varieties of layouts and generating shapes using SVG.

Other powerful features of D3 include:

Easy mapping of data to Html elements and vice versa
Flexibility to choose your own render elements (be it html or svg)
Simple API to configure the layouts and styling
Animation support with the transition API

Building the Tree

For this blog post, I am going to use sample tree data that looks like so:

var treeData = {
    name: "/",
    contents: [
        {
            name: "Applications",
            contents: [
                { name: "Mail.app" },
                { name: "iPhoto.app" },
                { name: "Keynote.app" },
                { name: "iTunes.app" },
                { name: "XCode.app" },
                { name: "Numbers.app" },
                { name: "Pages.app" }
            ]
        },
        {
            name: "System",
            contents: []
        },
        {
            name: "Library",
            contents: [
                {
                    name: "Application Support",
                    contents: [
                        { name: "Adobe" },
                        { name: "Apple" },
                        { name: "Google" },
                        { name: "Microsoft" }
                    ]
                },
                {
                    name: "Languages",
                    contents: [
                        { name: "Ruby" },
                        { name: "Python" },
                        { name: "Javascript" },
                        { name: "C#" }
                    ]
                },
                {
                    name: "Developer",
                    contents: [
                        { name: "4.2" },
                        { name: "4.3" },
                        { name: "5.0" },
                        { name: "Documentation" }
                    ]
                }
            ]
        },
        {
            name: "opt",
            contents: []
        },
        {
            name: "Users",
            contents: [
                { name: "pavanpodila" },
                { name: "admin" },
                { name: "test-user" }
            ]
        }
    ]
};
  

d3.layout.tree() is the starting point for tree layouts in D3. The call to this function returns an object that contains a bunch of methods to configure the layout and also provides methods to compute the layout.

var tree = d3.layout.tree()
    .sort(null)
    .size([size.height, size.width - maxLabelLength*options.fontSize])
    .children(function(d)
    {
        return (!d.contents || d.contents.length === 0) ? null : d.contents;
    });

var nodes = tree.nodes(treeData);
var links = tree.links(nodes);
  

You can ignore the call to the size()method, it is just setting the width and height of the tree, passing in as a 2-element array ([w,h]). If you are curious why I have the size.height as my first element, its because I am rotating the tree by 90 degrees. We will see more about his further down the post. The children()function is more interesting, as it tells the tree layout about the child nodes of the data-item. In my example, the contents property represents the children, as seen in the treeData variable above.

The next two methods, nodes() and links()does what you expect. It recurses through the data (by calling children() on each item) and computes the layout info for each data item. The links() method takes the output of nodes() and computes the edges between the different nodes. We are storing this computed layout in the nodes and links variables, each of which is a flat array of elements. Each element in the nodes array is a wrapper around the original data item with augmented layout info, whereas each element in the links array is a wrapper around the node item. Below you can see these wrapper objects:

The node item is augmented with the children, parent, x and y properties. The link item just has the source and target properties, which represents the edge from the parent to the child respectively. You can see that the source and target properties point to the node objects.

Rendering the tree

Now that we have the layout computed, the next step is to setup the UI elements that render the data and layout. For the tree diagram we are going to use SVG, although the same layout can also be achieved using plain Html,CSS with absolute positioning. To create our UI elements, we will use D3’s selection API, as mentioned above, to generate the SVG elements and set properties based on the computed layout.

/*
     <svg>
         <g class="container" />
     </svg>
  */
 var layoutRoot = d3.select(containerName)
     .append("svg:svg").attr("width", size.width).attr("height", size.height)
     .append("svg:g")
     .attr("class", "container")
     .attr("transform", "translate(" + maxLabelLength + ",0)");


 // Edges between nodes as a <path class="link" />
 var link = d3.svg.diagonal()
     .projection(function(d)
     {
         return [d.y, d.x];
     });

 layoutRoot.selectAll("path.link")
     .data(links)
     .enter()
     .append("svg:path")
     .attr("class", "link")
     .attr("d", link);


 /*
     Nodes as
     <g class="node">
         <circle class="node-dot" />
         <text />
     </g>
  */
 var nodeGroup = layoutRoot.selectAll("g.node")
     .data(nodes)
     .enter()
     .append("svg:g")
     .attr("class", "node")
     .attr("transform", function(d)
     {
         return "translate(" + d.y + "," + d.x + ")";
     });

 nodeGroup.append("svg:circle")
     .attr("class", "node-dot")
     .attr("r", options.nodeRadius);

 nodeGroup.append("svg:text")
     .attr("text-anchor", function(d)
     {
         return d.children ? "end" : "start";
     })
     .attr("dx", function(d)
     {
         var gap = 2 * options.nodeRadius;
         return d.children ? -gap : gap;
     })
     .attr("dy", 3)
     .text(function(d)
     {
         return d.name;
     });
  

The code above creates the root container (SVG with a Group (<g>) element) and adds the edges first followed by the nodes and text labels. This order ensures that the nodes and labels always stay on top of the edges. You can also see the use of the .data().enter() method chain to setup the inner-join for binding data to UI. The attr() method is used to set properties on the SVG elements. One thing to note here is that we are creating a group (<g>) element to hold both the node (<circle>) and the label (<text>). Also this group element is translated by [y, x], ie. by interchanging the original layout co-ordinates. We do this to rotate the tree by 90 degrees. This rotation makes the labels more readable.

I would heartily recommend D3.js to anyone looking into building 2D visualizations in Javascript. Although it has a slight learning curve, it is worth the effort and allows building some fancy visualizations. Do take a look at the examples to see the capabilities of this library.

Demo

You can take a look at the tree demo here.

Complex filtering in isotope.js

Sun, 10 Jul 2011 18:26:35 PDT

Of late, I have been building some Html/Javascript apps and exploring a bunch of javascript libraries, including the usual suspects (jQuery, jQuery UI, jQuery template, underscore, etc). The more interesting ones are visualization libraries like d3, isotope, highcharts. In this post, I will focus on a specific scenario in the isotope.js library.

Isotope.js

Isotope.js is a neat jQuery plugin for doing layout animations and provides a bunch of cool layout modes. When it is applied to a list of items, it lays them out in one of the several layout-modes and animates their positions upon changes in the list. It also provides sorting and filtering hooks which also trigger layout animations when applied. The GIF animation below gives a glimpse of the ‘masonry’ layout mode.

The way isotope treats filters is by looking for a particular CSS class on each of the items. If the item has that class, it is included in the filtered list. This form of filtering is very declarative and easy to apply.

However if you need more complex filtering, you will have to do some leg work. You will have observed in other toolkits, frameworks that filter is generally considered as a lambda-function that will be invoked for each item in the list. This is a convenient form of providing the filtering logic.

Isotope, however does not think that way and only looks at the class attribute of the item and matches on the supplied filter-class-name. This means, we will have to pre-process the items, apply the complex filtering logic and attach an ad-hoc class to the item. That is the key to complex filtering in isotope: a pre-processing step that attaches an ad-hoc class on matched items, which is then used by isotope.

The code-snipped below shows the pre-processing step before invoking the $.isotope() function. Look for the comments starting with [1], [2], [3].

function createTestData()
{
    var people = _.range(0, 100).map(function(p)
    {
        return {
            name: "Name-" + p,
            age: Math.round(Math.random() * 50),
            email: "email-" + p + "@company.com",
            image: "css/ninja/" + Math.ceil(Math.random() * 6) + ".png"
        }
    });

    $("#person-template").tmpl(people).appendTo("#people-list");
    $("#people-list").isotope({
        layoutMode:'masonry'
    });
}

$(document).ready(function()
{
    createTestData();

    // [1] Filtering function invoked for each item
    function predicate(data) {
        return data.age > 25;
    }

    // [2] Applies the ad-hoc 'matched-item' class to items that match the filter predicate
    $("#invoke").click(function(){
        $(".isotope-item").each(function(){
            var item = $(this).tmplItem().data;

            // [3] Apply the 'matched-item' class
            if (predicate(item)) $(this).addClass("matched-item");
            else $(this).removeClass("matched-item");
        });
        $("#people-list").isotope({
            filter: '.matched-item'
        });
    });

    $("#reset").click(function(){
        $(".isotope-item").each(function(){

            // Clear the class
            $(this).removeClass("matched-item");
        });

        $("#people-list").isotope({
            filter: '*'
        });
    });
});
  

So filtering in isotope can still be done the traditional way, just that we need a pre-processing step.

Demo

For a quick demo of the isotope-filtering, click here.

Blinking UI with a CaretBrush

Wed, 25 May 2011 21:14:59 PDT

A few days back while I was busy designing some UI for a Silverlight app, I accidentally hit upon this fun hack.

If you assign a shared Brush resource to the CaretBrush property of the TextBox control, then you start seeing some crazy blinking-light effects at places where the shared Brush is used. It is really fun the first time you see it happening and then on, it is sure to cause some Dilbert style “Mahjobbis Crappus”.

Fortunately the solution is quite simple: DO NOT use a shared brush resource for the CaretBrush !

Demo / Download

Below you will find a sample Silverlight app that shows this in action:

Download Solution/Project

Its Consulting time!

Sat, 19 Mar 2011 07:47:17 PDT

After having worked full-time for several years in the Corporate world, I have decided to make a career change and jump on to Consulting. I have joined my friends at
, where I’ll be working in the Financial district of New York, building solutions using Microsoft .Net, C\#, WPF, Silverlight, Html5 + JavaScript and others.

I have known some people at “the Lab” for several years, mostly when they were consulting with my earlier company. So it feels nice to go into a familiar crowd. Lab49 works on a variety of technologies and have a rich portfolio of clients. Many of the folks working here are experts on some technologies and also have active blogs. It is surely a great place to learn new things and work on exciting projects.

I think it will be fun.

Building a CoverFlow visualization using Quartz Composer

Sat, 12 Mar 2011 09:01:17 PST

I have been playing around with Quartz Composer (included as part of the Developer tools installation on Mac OSX) for almost a year. It’s a great tool for creating screen savers, music visualizations and also for quick prototyping of some visual concepts. I personally find the patch-based approach to solving problems quite refreshing and offers a different perspective to looking at complex problems. It is very much like programming but with functional blocks (called patches) rather than real code.

Understanding the CoverFlow visualization

Before I talk about how we can pull this off in QC, it would be good to take a quick look at the building blocks of CoverFlow. We all have seen it before, but it would be good to analyze it from the point of view of a QC composition:

We have a set of tiles placed left to right with some gap between tiles. The selected tile is in the center of the viewport with some additional gap between the center tile and the adjacent tiles.
A tile can be in one of three orientations: tilted on left, straight center, tilted on right (as shown in the picture above)
Each tile has a reflection at the bottom, fading into the background
As the selected tile changes, every item does a sliding+rotating animation to take up a new position and orientation
A few polishing touches include a dark vertical-gradient as background and a horizontal gradient that fades off the edges. The edge-fading gradient (called a vignette) is needed to give a lighting effect on the center, selected tile.

Decomposing the Quartz composition!

Quartz Composer is a patch-based programming tool, which means we will have to think in terms of functional blocks or patches that do some simple operation. A patch has some inputs and outputs. Your job is to provide proper inputs and use the outputs to feed other patches. You can also encapsulate a set of patches into a Macro Patch, which provides a simpler abstraction over some complex operation. The Macro Patch can be used like regular patches, possibly having its own inputs and outputs.

Connecting these patches together we can create visualizations. I like to think of this as circuit-board design, where we take a bunch of ICs (Integrated Chips) and design a micro-processor. The Quartz Composer provides a way to design a micro-processors that can generate visualizations. The figure below shows a part of the CoverFlow composition.

The CoverFlow composition is built up of a few Macro Patches that are layered to create the visualization. Lets understand this from the bottom-up.

[A] A CoverFlow tile

At the bottom of the stack is the notion of a single CoverFlow tile. This tile provides the base properties that will be controlled from higher level patches. From our earlier analysis, we know we need the following capabilities:

Reflection
Positioning on the X-axis
Y-Rotation to show the tilt
An Image that acts as the texture for the tile and the reflection

A Sprite patch provides all of these capabilities, except for the reflection. To get the reflection we use an extra Sprite and apply an inverted version of the supplied Image. We finally apply a gradient mask to obtain the fading reflection effect. The mask gradient is from 85% transparency to 100% transparency (fading into background). To make it easy, I have encapsulated all of these patches into a Macro Patch called “Reflected Tile”. The following figure shows the “Reflected Tile” patch. Click on it for a full-size image.

One thing you will notice is that I am exposing the “Image”, “X Position” and “Y Rotation” as inputs (shown with light-green dots) into the “Reflected Tile” Patch. These will be set from a higher level patch, the “CoverFlow Tile” patch, which is yet another Macro Patch.

The “CoverFlow Tile” Patch

This patch represents a single CoverFlow Tile.

This patch provides an numbered input called “State Index” that can be either 0,1,2, representing the three different orientations: left tilted, straight-center, right tilted respectively. Depending on the state we apply the correct “Tilt Angle”. The left tilt is positive and the right tilt is negative. The negative tilt is applied with a simple Math patch that multiplies the “Tilt Angle” by –1. This patch wraps the Reflected Tile patch and also exposes the “Y Rotation” input on the Reflected Tile patch as “Tilt Angle”. We have also applied a Smooth patch for the “X Position” and the “Y Rotation” to animate the position and orientation changes on the tile. The default animation-time is 0.5 seconds, and can be controlled with the “Animation Duration” input on the CoverFlow Tile patch.

[B] A list of CoverFlow Tiles

With the basic tile patches in place, we are now ready to tackle the display of a set of tiles. Each tile will be rendered using the “CoverFlow Tile” patch but needs to be positioned and oriented depending on a “Selected Index”. The Selected Index is exposed as input into the Iterator patch, a stock Macro Patch provided within Quartz Composer. The Selection Index divides the tiles into 3 sets: the selected tile (center tile), the tiles to the left and the tiles to the right. The X Position and Tilt Angle of each tile is entirely driven by the Selected Index and the “Current Index” of the Iterator patch.

To obtain the “Current Index” within the Iterator Macro Patch, we use the standard Iterator Variables patch provided within QC. Using the Selected Index and the Current Index of the Iterator, we can determine the “State Index” of the tile. Recall that we have 3 states for each tile, that specify the orientation of the tile. The state of the tile is controlled by this State Index.

The X Position of the tile requires more calculation as we use the “Item Gap” and the “Front Item Gap” inputs to correctly position the tile. Note that the Item Gap and Front Item Gap is only applied to the left and right tiles. The center tile is unaffected by these inputs. The figure below shows the complete wiring of the “Tile Iterator” patch. The value of the X Position is governed by the fact that we use a 3D co-ordinate system where the origin is in the center of the screen. The X values decrease to the left of the origin and increase to the right of the origin.

The “Image List” input is the set of the images over which the Iterator patch iterates. This is fed as input from higher level patch that represents our entire coverflow visualization. This patch is aptly called the “CoverFlow Control” patch, as shown in the figure below. Note that all the necessary inputs are exposed on this patch.

[C] Providing Keyboard input for selection

Of course, no CoverFlow control is void of user interaction! Thus our composition dutifully provides some control using keyboard input. In Quartz Composer the Keyboard patch can be used to detect keyboard input. A set of keys can be configured in the settings for the Keyboard patch, which will generate a signal (a momentary boolean value) whenever that key is hit. In our case, we use the Left/Right arrow keys for changing the Selected Index of the CoverFlow Control.

The Keyboard generated signals are fed into a Counter patch that increments or decrements a count. The Left arrow decrements and the Right arrow increments. The output of the Counter acts as input to the Selected Index of the CoverFlow Control patch. We also use a Conditional patch to ensure that the count generated by the Counter is always within the index range [0, n-1] of the Image List . A Directory Scanner patch provides the location that contains all the images. This patch creates a Structure (an array of objects) that then becomes the Image List input to the CoverFlow Control patch.

With this setup we now have a way to drive the CoverFlow visualization. The figure below shows the wiring for the keyboard input.

Final polishing

The final polish to this composition is done by applying a bunch of Gradient patches that generate the background and the fading edge effect (vignette) on the CoverFlow. We also wrap the previously described patch in section [C] inside a 3D Transformation. This is used to scale down the entire visualization and leave some room at the bottom to show keyboard-navigation instructions.

Quick video showing it in action

CoverFlow using Quartz Composer

Download

For exploring all the details about this composition you can download and peruse the .QTZ file:

Tokenizing control – convert text to tokens

Thu, 28 Oct 2010 13:59:57 PDT

In this post I want to talk about some interesting ideas regarding a control called TokenizingControl? What is that you may ask, so lets start with the basics. A Tokenizing control takes in some text, delimited by some character and converts that text to a token, a token that is represented by some UI element other than the original text. For example, if you have text like “John Doe;” (note the ; acting as delimiter), then the tokenizing control will convert it to some UI Element like a Button, say.

In fact the text can be replaced by a complex backing object (ViewModel) that is rendered using some UI element (in this case a Button). We can add more flexibility for the UI element by making it into a ContentPresenter that takes in a DataTemplate, with the Content being the ViewModel!

This is the purpose of a tokenizing control. Since we are dealing with text most of the time and replacing some pattern of text into a token, we continue to retain the editing capabilities. In other words, if I hit the BackSpace key on the token-UI (shown as a Button), it is deleted completely. You can think of this control as a runtime parser that detects some pattern of text and converts that into a UI token (backed by some ViewModel, potentially).

Now you may be thinking where could such a control be used. Well, the most common place is in an Email editor for the To/CC/BCC input areas. When you type in a prefix of a name, the control will try to match that against some AddressBook and convert that typed text into a rich token (backed by the Contact from the AddressBook). Outlook does this and so do many other email programs. One other place you will find a use is in data-entry forms where some typed text is converted to a matched object. Having such a control minimizes the errors in typing because you will get real-time validation with some visual feedback. Now that we know there is a “real” use case for this control, lets get into some implementation details, in WPF.

Behavior of the TokenizingControl

The general expectations from this control are outlined below:

Should allow text editing with inline representation of matched text with a UI token
Should provide ability to customize appearance of the UI token
Should provide a way to match text and convert matched-text to a token object

Lets tackle one at a time. The first bullet tells us that the TokenizingControl is like a hybrid TextBox that can hold text as well as other UI elements, in other words we are looking at a RichTextBox as our base. A RichTextBox encapsulates a FlowDocument (as its Document property), which can hold both text and UI elements. By manipulating this Document, we should be able to convert the typed text (which would be in a Run) and convert that to a InlineUIContainer (a subclass of Inline that wraps a UIElement). Thus at the UI level we are looking at a Run to InlineUIContainer conversion, all happening inside the FlowDocument.

Now that we have an InlineUIContainer to work with, we will need to address bullet 2: customizing appearance of the token. This can be easily achieved by using a ContentPresenter with a DataTemplate. We can expose a DataTemplate property (let’s call it TokenTemplate) on the TokenizingControl and provide this ability.

As regards the last bullet, we can have a Func<string,object> that takes in a string (typed-text) and returns an object for the matched token and null for no-match. We can expose this with a TokenMatcher property of type Func<string, object>. This is the lambda that you will use to convert text to a backing object (aka ViewModel). This backing object becomes the Content of the ContentPresenter.

With that we have our class definition for the TokenizingControl, which looks like below:

You can see the methods in this class that do the actual work. The processing begins in the TextChanged event handler, where we get the text from the CaretPosition and apply the TokenMatcher to determine the token. If a valid token is found, we create the UI container and replace the Run with the InlineUIContainer. The code below shows this in detail:

public TokenizingControl()
{
    TextChanged += OnTokenTextChanged;
}

private void OnTokenTextChanged(object sender, TextChangedEventArgs e)
{
    var text = CaretPosition.GetTextInRun(LogicalDirection.Backward);
    if (TokenMatcher != null)
    {
        var token = TokenMatcher(text);
        if (token != null)
        {
            ReplaceTextWithToken(text, token);
        }
    }
}

private void ReplaceTextWithToken(string inputText, object token)
{
    // Remove the handler temporarily as we will be modifying tokens below, causing more TextChanged events
    TextChanged -= OnTokenTextChanged;

    var para = CaretPosition.Paragraph;

    var matchedRun = para.Inlines.FirstOrDefault(inline =>
    {
        var run = inline as Run;
        return (run != null && run.Text.EndsWith(inputText));
    }) as Run;
    if (matchedRun != null) // Found a Run that matched the inputText
    {
        var tokenContainer = CreateTokenContainer(inputText, token);
        para.Inlines.InsertBefore(matchedRun, tokenContainer);

        // Remove only if the Text in the Run is the same as inputText, else split up
        if (matchedRun.Text == inputText)
        {
            para.Inlines.Remove(matchedRun);
        }
        else // Split up
        {
            var index = matchedRun.Text.IndexOf(inputText) + inputText.Length;
            var tailEnd = new Run(matchedRun.Text.Substring(index));
            para.Inlines.InsertAfter(matchedRun, tailEnd);
            para.Inlines.Remove(matchedRun);
        }
    }

    TextChanged += OnTokenTextChanged;
}

private InlineUIContainer CreateTokenContainer(string inputText, object token)
{
    // Note: we are not using the inputText here, but could be used in future

    var presenter = new ContentPresenter()
    {
        Content = token,
        ContentTemplate = TokenTemplate,
    };

    // BaselineAlignment is needed to align with Run
    return new InlineUIContainer(presenter) { BaselineAlignment = BaselineAlignment.TextBottom };
}
  

In action

The following picture shows the different stages in converting the text to a token: user inputs text, types a semi-colon ;, text converted to a token. We are using ; as our delimiter here.

The TokenMatcher for this example looks like so:

Tokenizer.TokenMatcher = text =>
                             {
                                 if (text.EndsWith(";"))
                                 {
                                     // Remove the ';'
                                     return text.Substring(0, text.Length - 1).Trim().ToUpper();
                                 }

                                 return null;
                             };

If you run the example from the attached solution, there is a nice animation that fades-in the token-UI once the user types in the ;. This gives a nice effect of some transformation happening to the text.

Summary

This post showed you a neat way to transform text, that matches some criteria, into tokens represented by a different UI. The TokenizingControl does this job by using the TokenMatcher (Func<string, object>) and converting matched text into tokens represented by the TokenTemplate (DataTemplate). The tokens are inserted inline using the InlineUIContainer. The RichTextBox was the base for the TokenizingControl.

As a parting thought, I want to mention that you can add several useful features to this control:

An inline autocompletion popup that shows up as you type text. The autocompletion helps in narrowing down the options even more
The token-UI can be much more sophisticated (potentionally a custom control of its own that is used internally by the TokenizingControl)
There can be an ItemsSource-like property that takes in a collection of ViewModel objects and converts them to UI-tokens and also the other way around
The TokenMatcher can be far more intelligent and generate not just a single token out of the text but also help in the autocompletion!

[Note: I do have a control that does all of the above ]. Hopefully this post shares enough info to create one of your own!

Source code for TokenizingControl

A DoubleBorderDecorator to simplify rounded-border decorations

Mon, 25 Oct 2010 14:26:57 PDT

The designers in my team use a lot of nested double-Border elements to achieve a nice rounded border-effect around containers. In XAML this looks like so:

<Border Background="#FF414141"
        Padding="3"
        Width="300"
        Height="200"
        CornerRadius="8">
    <Border Padding="3"
            CornerRadius="8">
        <Border.Background>
            <LinearGradientBrush EndPoint="0.5,1"
                                 StartPoint="0.5,0">
                <GradientStop Color="#FF910000"
                              Offset="1" />
                <GradientStop Color="#FFAF5959" />
            </LinearGradientBrush>
        </Border.Background>
    </Border>
</Border>
  

You will notice that there is no use of the BorderThickness and BorderBrush properties. Instead this effect achieved by nesting one Border inside another using the Background property and setting a Padding on the outer-Border. The reason why they do this is because of a rendering glitch in WPF’s Border element. If you try to create the above look using a single Border with BorderThickness, BorderBrush and Background, you will see the corners having some glitches. The image below (zoomed to 150%) shows this clearly. Notice the white inner-curve around the corners and compare this to the image above. Clearly there is a glitch here.

Here’s the single-Border XAML that was used for the above look:

<Border BorderBrush="#FF414141"
        CornerRadius="8"
        Margin="137,111,193,137"
        BorderThickness="3">
    <Border.Background>
        <LinearGradientBrush EndPoint="0.5,1"
                             StartPoint="0.5,0">
            <GradientStop Color="#FF910000"
                          Offset="1" />
            <GradientStop Color="#FFAF5959" />
        </LinearGradientBrush>
    </Border.Background>
</Border>

So, now you know why the nested double-Border technique is so effective and creates a much more pleasing look. But, we have a problem here. If your project is large and using several different kinds of containers with the rounded–border effect, you will be using a LOT of these Borders! It also hampers the readability at some point. Surely there can be a better way…in the form of a custom DoubleBorderDecorator!

DoubleBorderDecorator

This is a simple Decorator derived class that I created which bakes in the above discussed technique with simple configurable properties. To achieve the effect from our previous example, here is the XAML using the DoubleBorderDecorator:

<shared:DoubleBorderDecorator Height="200"
                              Width="300"
                              OuterBorderThickness="3"
                              OuterBorderBrush="#FF414141"
                              CornerRadius="8"
                              Background="{DynamicResource RedGradient}" />
  

Visually it looks exactly like our first figure, but lot simpler to use and modify. In fact, you can even define a Style and set the defaults at a global level (inside Application Resources).

Here is a Blend screenshot that shows other useful properties of this decorator:

With an inner-border and an outer-border, you get a pretty flexible way of creating rounder-border effects that look great. Here are a few examples:

Download Source

Simple TriggerAction for docking using GridSplitters

Sat, 07 Aug 2010 09:31:09 PDT

GridSplitters work great if you want to provide a split view between two views. By dragging the GridSplitter you can adjust the space allocated to each view. As one view grows in size, the other reduces by the same size. For most cases, this is exactly what is required. In my case, this wasn’t enough. In addition to adjusting the splitter, I also wanted a way to quickly collapse one view and allocate all the space to the other view (a.k.a. Docking). The views were arranged horizontally like so:

To do the collapse action to one side, I added two buttons to the GridSplitter’s ControlTemplate (shown below). One would collapse the left-view and the other the right-view.

What you are seeing in the figure above is a Grid with 3 columns. The middle column is assigned to the GridSplitter. This is an important assumptionthat I make: that the GridSplitter occupies the center column (or center row) and there are views to the either side in their own columns (or rows). This assumption will be used in my custom TriggerAction, called CollapseAction.

The CollapseAction for the GridSplitter buttons

The idea of collapse is to maximize one of the views and assign zero space to the other view. This can be achieved by adjusting the Widths of the ColumnDefinitions of the containing Grid (or adjusting the Heights of the RowDefinitions). It is probably easier to see it all in code, so here you go:

public class CollapseAction : TriggerAction<Button>
{
    public Dock Direction { get; set; }
    protected override void Invoke(object parameter)
    {
        // First find the nearest splitter
        var splitter = FindVisual<GridSplitter>(AssociatedObject);

        if (splitter != null)
        {
            var grid = FindVisual<Grid>(splitter); // Find nearest Grid
            if (grid != null)
            {
                ApplyDock(grid);
            }
        }
    }

    private void ApplyDock(Grid grid)
    {
        var cDef1 = grid.ColumnDefinitions.FirstOrDefault();
        var cDef2 = grid.ColumnDefinitions.LastOrDefault();
        var rDef1 = grid.RowDefinitions.FirstOrDefault();
        var rDef2 = grid.RowDefinitions.LastOrDefault();
        switch (Direction)
        {
            case Dock.Left:
                cDef1.Width = new GridLength(0);
                cDef2.Width = new GridLength(1, GridUnitType.Star);
                break;
            case Dock.Right:
                cDef2.Width = new GridLength(0);
                cDef1.Width = new GridLength(1, GridUnitType.Star);
                break;
            case Dock.Top:
                rDef1.Height = new GridLength(0);
                rDef2.Height = new GridLength(1, GridUnitType.Star);
                break;
            case Dock.Bottom:
                rDef2.Height = new GridLength(0);
                rDef1.Height = new GridLength(1, GridUnitType.Star);
                break;
        }
    }

    private T FindVisual<T>(FrameworkElement relElt) where T : FrameworkElement
    {
        var parent = VisualTreeHelper.GetParent(relElt);

        while (parent != null && !(parent is T))
        {
            parent = VisualTreeHelper.GetParent(parent);
        }

        return parent as T;
    }
}
  

The core of the work happens in the ApplyDock() method. Depending on the Direction, I zero-size one of the columns/rows and give all the layout-space to the other column/row. The middle column/row is of fixed-size and is used by the GridSplitter (as noted earlier). In the ControlTemplate I assign this action to each of the buttons and set the Direction appropriately. This can be seen in the following snippet of the GridSplitter’s ControlTemplate. Note the actions assigned to the Buttons.

<ControlTemplate TargetType="{x:Type GridSplitter}">
    <Border BorderBrush="{TemplateBinding BorderBrush}"
            BorderThickness="{TemplateBinding BorderThickness}"
            Background="{TemplateBinding Background}">
        <Grid Height="Auto">
            <StackPanel x:Name="ColumnsCollapsers"
                        VerticalAlignment="Stretch"
                        d:LayoutOverrides="Height">
                <Button Height="10"
                        Margin="0,3,0,0"
                        Padding="0"
                        Style="{DynamicResource ButtonStyle1}"
                        RenderTransformOrigin="0.5,0.5"
                        Cursor="Arrow">
                    <Button.RenderTransform>
                        <TransformGroup>
                            <ScaleTransform ScaleY="1"
                                            ScaleX="-1" />
                            <SkewTransform AngleY="0"
                                            AngleX="0" />
                            <RotateTransform Angle="0" />
                            <TranslateTransform />
                        </TransformGroup>
                    </Button.RenderTransform>
                    <i:Interaction.Triggers>
                        <i:EventTrigger EventName="Click">
                            <local:CollapseAction />
                        </i:EventTrigger>
                    </i:Interaction.Triggers>
                    <Path Data="M20.500334,30.5 L20.500334,49.166667 35.500332,38.833333 z"
                            Fill="Black"
                            HorizontalAlignment="Center"
                            Height="6"
                            Margin="0"
                            Stretch="Fill"
                            Stroke="{x:Null}"
                            Width="6"
                            StrokeThickness="0"
                            VerticalAlignment="Center" />
                </Button>
                <Button Height="10"
                        Margin="0,3,0,0"
                        Padding="0"
                        Style="{DynamicResource ButtonStyle1}"
                        Cursor="Arrow">
                    <i:Interaction.Triggers>
                        <i:EventTrigger EventName="Click">
                            <local:CollapseAction Direction="Right" />
                        </i:EventTrigger>
                    </i:Interaction.Triggers>
                    <Path Data="M6.4035191E-08,0 L-1.5987212E-14,5.9999996 5.9999999,2.6785712 z"
                            Fill="Black"
                            HorizontalAlignment="Center"
                            Height="6"
                            Margin="0"
                            Stroke="{x:Null}"
                            Width="6"
                            StrokeThickness="0"
                            VerticalAlignment="Center"
                            StrokeLineJoin="Round"
                            Stretch="Fill" />
                </Button>
            </StackPanel>
            <StackPanel x:Name="RowCollapsers"
                        VerticalAlignment="Stretch"
                        d:LayoutOverrides="Height"
                        Orientation="Horizontal"
                        Visibility="Collapsed">
                <Button Height="10"
                        Padding="0"
                        Style="{DynamicResource ButtonStyle1}"
                        RenderTransformOrigin="0.5,0.5"
                        Cursor="Arrow"
                        Width="10"
                        HorizontalAlignment="Left"
                        Margin="3,0,0,0">
                    <Button.RenderTransform>
                        <TransformGroup>
                            <ScaleTransform ScaleY="1"
                                            ScaleX="-1" />
                            <SkewTransform AngleY="0"
                                            AngleX="0" />
                            <RotateTransform Angle="90" />
                            <TranslateTransform />
                        </TransformGroup>
                    </Button.RenderTransform>
                    <i:Interaction.Triggers>
                        <i:EventTrigger EventName="Click">
                            <local:CollapseAction Direction="Top" />
                        </i:EventTrigger>
                    </i:Interaction.Triggers>
                    <Path Data="M20.500334,30.5 L20.500334,49.166667 35.500332,38.833333 z"
                            Fill="Black"
                            HorizontalAlignment="Center"
                            Height="6"
                            Margin="0"
                            Stretch="Fill"
                            Stroke="{x:Null}"
                            Width="6"
                            StrokeThickness="0"
                            VerticalAlignment="Center" />
                </Button>
                <Button Height="10"
                        Padding="0"
                        Style="{DynamicResource ButtonStyle1}"
                        Cursor="Arrow"
                        Width="10"
                        HorizontalAlignment="Left"
                        Margin="3,0,0,0"
                        RenderTransformOrigin="0.5,0.5">
                    <Button.RenderTransform>
                        <TransformGroup>
                            <ScaleTransform />
                            <SkewTransform />
                            <RotateTransform Angle="90" />
                            <TranslateTransform />
                        </TransformGroup>
                    </Button.RenderTransform>
                    <i:Interaction.Triggers>
                        <i:EventTrigger EventName="Click">
                            <local:CollapseAction Direction="Bottom" />
                        </i:EventTrigger>
                    </i:Interaction.Triggers>
                    <Path Data="M6.4035191E-08,0 L-1.5987212E-14,5.9999996 5.9999999,2.6785712 z"
                            Fill="Black"
                            HorizontalAlignment="Center"
                            Height="6"
                            Margin="0"
                            Stroke="{x:Null}"
                            Width="6"
                            StrokeThickness="0"
                            VerticalAlignment="Center"
                            StrokeLineJoin="Round"
                            Stretch="Fill" />
                </Button>
            </StackPanel>
        </Grid>
    </Border>
    <ControlTemplate.Triggers>
        <Trigger Property="ResizeDirection"
                    Value="Rows">
            <Setter Property="Visibility"
                    TargetName="ColumnsCollapsers"
                    Value="Collapsed" />
            <Setter Property="Visibility"
                    TargetName="RowCollapsers"
                    Value="Visible" />
        </Trigger>
    </ControlTemplate.Triggers>
</ControlTemplate>
  

In action

Below you can see the two configurations of docking to the left and to the right. Note that you can still grab the GridSplitter and drag to adjust the columns.

Subtle things to note about the GridSplitter

In the ControlTemplate, I have added two Buttons and set their Cursor to Arrow. This is required because by default the GridSplitter assigns a Cursor of SizeWE or SizeNS depending on the alignment. When you move the mouse on the Buttons, you continue to get this sizing cursor. This hinders with the usability of the buttons and to aid in the usage, we set the Cursor of the buttons to Arrow.
The ResizeBehavior has been explicitly set to PreviousAndNext. This should make sense now given our earlier assumption. Additionally, the ResizeDirection has also been set to Columns.

Download Source

Pixel-in-Gene

More Writing on NetTuts+

My Key Takeaways from SMACSS

SMACSS in action

An example to tie it all together

Parallels to OO languages

Summary

Common Idioms in JavaScript development

Use Array.join to concatenate strings

Minimize use of if/else blocks by creating object hashes

Make the parameter value be of any-type

Use IIFE to compute on the fly

A simple organization scheme for handling routes in ExpressJS apps

Moving towards a flexible app structure

Route management

In short…

Quick sketching using SketchBook Pro + Wacom Intuos 4

Animating Pie Slices using a custom CALayer

First steps

A path for the slice

Animating the pie-slice

Raising the level of abstraction

Custom CALayer, the PieSliceLayer

Rendering the PieSliceLayer

It all comes together in PieView

Managing the slices

Demo and Source code

Simple helper method for async testing with Jasmine and RequireJS

Async tests in Jasmine

Jasmine meets RequireJS

Using jQuery.Deferred() and RequireJS to Lazy Load Google Maps API

The soup of AMD, $.Deferred and Google Maps

Summary

Demo

Tips for Speeding Up Octopress Site Generation

Speed up

All set to publish

Switching to the Octopress Blogging Engine

Exploring beyond Wordpress

Migrating Wordpress posts

Migrating Wordpress comments to Disqus

Url Rewrites and other changes

Epilogue

Be careful declaring properties in CoffeeScript

Progressive reveal animations in SVG using a

Animating the path to root

Back to my Mac root

Demo

Building a tree diagram in D3.js

A brief course on D3

Building the Tree

Rendering the tree

Demo

Complex filtering in isotope.js

Isotope.js

Demo

Blinking UI with a CaretBrush

Demo / Download

Its Consulting time!

Building a CoverFlow visualization using Quartz Composer

Understanding the CoverFlow visualization

Decomposing the Quartz composition!

[A] A CoverFlow tile

The “CoverFlow Tile” Patch

[B] A list of CoverFlow Tiles

[C] Providing Keyboard input for selection

Final polishing

Quick video showing it in action

Download

Further Reading

Tokenizing control – convert text to tokens

Behavior of the TokenizingControl

In action

Summary

A DoubleBorderDecorator to simplify rounded-border decorations

DoubleBorderDecorator

Simple TriggerAction for docking using GridSplitters

The CollapseAction for the GridSplitter buttons

In action

Subtle things to note about the GridSplitter

Custom CALayer, the `PieSliceLayer`