Bryan Dragon

Conditional Exports in Node.js

2013-03-11T19:17:00Z

It is possible to detect whether a Node.js module is being run directly or whether it is being required into another module by checking whether the global require.main is equal to the current module.

Let’s imagine two modules, a.js and b.js:

// a.js
var util = require('util');

if (require.main === module) {
  console.log("a running directly");
  console.log(util.inspect(module.exports));
}
else {
  module.exports = function () {
    console.log("a running as import");
    console.log(util.inspect(module.exports));
  };
}

// b.js
var a = require('./a');
a();

When we run each module in turn, we see the behavior of a.js change accordingly:

$ node a.js
a running directly
{}

$ node b.js
a running as import
[Function]

While this example is contrived, you can see how this simple feature permits you to control module behavior based on how the module is executed.

Flash Builder: Debugging with FireFox

2012-10-23T08:47:00Z

If Firefox is your default web browser for debugging in Flash Builder, you may encounter this error after updating to the latest version of Firefox:

By default FlashBuilder will assume that the Firefox executable is located at /Applications/Firefox.app/Contents/MacOS/firefox-bin, which is incorrect.

To fix this, navigate to Preferences > General > Web Browser in the Flash Builder application menu, select Firefox in the External Web Browsers list, click Edit…, and change Location from /Applications/Firefox.app/Contents/MacOS/firefox-bin to /Applications/Firefox.app/Contents/MacOS/firefox.

Rails Asset Pipeline, CDNs and Serving Cross-Domain Fonts

2012-02-23T03:33:43-08:00

Recently I was working on a project for a client. My task was straightforward: “Can you make my site faster?” There was only one right answer.

My client’s web site was running on Rails 3.0.1 and using full page caching. The site made extensive use of JavaScript and high-res images and testing with the YSlow plugin for FireFox confirmed my suspicion that most of the bottlenecks could be ameliorated by combining and minifying external JavaScript and CSS files and by serving content from a CDN.

I had been eyeing the Asset Pipeline since it was released as part of Rails 3.1 and this was the perfect excuse to jump in. If you’re not familiar with the Asset Pipeline, you should check it out; explaining it in detail, however, is beyond the scope of this article. Essentially it makes your static assets first-class citizens in your Rails application, right alongside your Ruby code. Leveraging libraries such as Sprockets, Sass and UglifyJS, it makes writing JavaScript and CSS less painful and gives you the ability to create dependency trees and modularize your scripts and styles with imports. The best part, however, is that it can precompile your static assets, compressing all of your scripts and styles into a few core files, minifying them, and even gzipping them. Additionally, it uses file fingerprints to name the compiled files for better caching. Awesome.

First Roadblock: Namespace Chaos

As it goes with Rails, the Asset Pipeline adheres to a few conventions, one of which is dumping all static assets into the same namespace. In order words, once compiled, a stylesheet and an image requested with <%= stylesheet_link_tag "screen.css" %> and <%= image_tag "icon.png" %> will be served from /assets/screen.css and /assets/icon.png, respectively, instead of from /stylesheets/screen.css and /images/icon.png, as they would have been in previous versions of Rails.

This has the advantage of allowing you to reference static assets across libraries without needing to fuss with sub-folders. By default, the Asset Pipeline will bring into the asset search path anything under app/assets/, lib/assets/ and vendor/assets/. So you can require a JavaScript file located at vendor/assets/javascripts/jquery-ui.js from within app/assets/javascripts/application.js without having to worry about the path:

//=require jquery-ui.js

I imagine for most this works fine. However, I see a few problems with it. First, there is potential for files to overlap across libraries. For example, it is conceivable that two libraries might have a stylesheet called screen.css – which one would be imported? Second, it makes it difficult to organize and serve assets from multiple Content Delivery Networks, as your files are lumped together in one namespace. (Why multiple CDNs? More on that in a bit.) Finally, it pollutes the public/assets/ directory with any uncompiled files that your third-party libraries may contain – even READMEs, tests and documentation. This became especially apparent when I dropped the Google Closure library into vendor/assets/. When I ran rake assets:precompile, I ended up with this:

$ ls public/static/
AUTHORS
LICENSE
README
all_tests-2b7a9ce7ac70114656773b6a5eb47ffc.html
all_tests.html
application-9302184a59033b8f84b5c0c84d58beaf.js
application-9302184a59033b8f84b5c0c84d58beaf.js.gz
application-c57e646675665776d02ceda5774b69dc.css
application-c57e646675665776d02ceda5774b69dc.css.gz
application.css
application.css.gz
application.js
application.js.gz
arrow-left_20x14-102858d7051ca3cb338ec444dd1e41d5.png
arrow-left_20x14.png
beta_59x33-bbe810b7f16c710832057168e248cf9e.png
beta_59x33.png
bg-gradient-d1045408f33a832534950ec06b195fe3.jpg
bg-gradient.jpg
bullet_green-0995accbacf9bc3e11f805378cb085bc.png
bullet_green.png
bullet_orange-cf2e4090499d4dee019244b27993737b.png
bullet_orange.png
closure
# ... and 86 more. You get the idea.

As you can see, any non-JS or CSS files found in the assets search paths are dumped into public/static/, including the AUTHORS and README files from Google Closure. How was I supposed to maintain that? As I upload my static assets to a CDN like most, what would happen when I wanted to remove or upgrade a third-party library? Rather than find out, I decided to pass on dealing with that mess.

So I set out to fight the framework and namespace my static assets. There’s probably a really clever way to do this, but simply nesting my assets within sub-folders accomplished what I was hoping for. So, app/assets/fonts/ became app/therealretouch/assets/fonts/, vendor/assets/closure-library/ became vendor/assets/third_party/closure-library/, and so on.

When I compiled my static assets again, public/assets/ looked like this:

$ ls public/assets/
closure-library  images       jquery-ui-1.8.10  manifest.yml
fonts            javascripts  jqzoom            stylesheets

Sanity had been restored.

Second Roadblock: Relative Image Paths in Third-Party Library Stylesheets

Moving assets into logical namespaces made managing assets easier in the long run, but it created a new problem: relative image paths in third-party libraries were broken. Fortunately, this only affected jQuery UI, as the Google Closure library used absolute paths for images (on Google’s CDN). After considering my options, I decided to search-and-replace relative path strings with the Rails asset helper in the jQuery UI stylesheet like so: <%= asset_path 'jquery-ui/images/ui-bg_flat_75_ffffff_40x100.png' %>. Again, there may be a more elegant solution, but this worked for my purposes.

Third Roadblock: JavaScript File Size

The Asset Pipeline will by default compile two files: app/assets/application.js and app/assets/application.css. You can instruct it to precompile additional files like so:

config.assets.precompile += ['admin/admin.js', 'admin/admin.css', 'admin/editor.comp.js']

I had previously built a rich text editor with the Google Closure library for use in administrative back-ends. With closure-library now integrated into the Asset Pipeline, I decided to add the editor to the array of assets to precompile. Weighing in at 1,365 lines of JavaScript – after compiling it with calcdeps.py (hey, Closure isn’t exactly the most concise JavaScript library out there…) – the editor proved more than Sprockets could handle, as the latter died with stack overflow errors when trying to compile it.

Since breaking up my Closure editor into multiple files wasn’t an option, I removed it from the precompile array and simply wrote a Capistrano deploy task to copy it to the assets directory and add an entry for it to the manifest.yml file (so that the Asset Pipeline would recognize it) after the other assets were precompiled. It goes something like this:

run "cp #{release_path}/app/assets/therealretouch/javascripts/admin/editor.comp.js #{release_path}/public/assets/javascripts/admin/editor.comp.js"
run %{echo "javascripts/admin/editor.comp.js: javascripts/admin/editor.comp.js" >> #{release_path}/public/assets/manifest.yml}

With the my static assets organized into sane, modular namespaces, and with my rich text editor in place, I set about uploading everything to a CDN.

Fourth Roadblock: Firefox and Serving Fonts across Domains

My client required a CDN to host all JavaScript, CSS, image and font files. As she was already relying on Amazon S3 for storing large order files, Amazon CloudFront seemed like a logical choice for a CDN.

It turns out that Firefox will not load a font file served from one domain accessed within another domain. So, a font hosted at cdn.therealretouch.com would be inaccessible from www.therealretouch.com when the website were viewed in Firefox.

The workaround for this is to use the Access-Control-Allow-Origin header to specify the domain which would be accessing the resource (or, more flexibly, *, to permit any domain). Unfortunately, the Amazon S3 API does not allow one to set the Access-Control-Allow-Origin header. As a result, I needed another CDN solution that would allow setting this header when uploading fonts.

As the site was already being hosted with Rackspace, CloudFiles seemed a logical alternative. Thankfully CloudFiles has supported setting the Access-Control-Allow-Origin header via their API since May 2011.

Since my client was already tied to Amazon S3 for order files, I decided to use CloudFiles for serving fonts only and to serve all other static content from Amazon CloudFront.

Finish Line

Here is the Rake task for uploading the compiled assets to Amazon S3 and Rackspace CloudFiles according to the hybrid CDN solution described above:

require 'aws-sdk'
require 'cloudfiles'
require 'mime/types'

aws_interface = ::AWS::S3.new(
  :s3_endpoint => 's3.amazonaws.com',
  :access_key_id => AWS_KEY,
  :secret_access_key => AWS_SECRET
)
aws_bucket = aws_interface.buckets[AWS_BUCKET]

cloudfiles_connection = CloudFiles::Connection.new(
  :username => CF_USERNAME,
  :api_key => CF_API_KEY
)
cloudfiles_container = cloudfiles_connection.container(CF_CONTAINER)

namespace :cdn do
  namespace :upload do
    desc "Upload all static assets"
    task :all => [:fonts, :images, :javascripts, :stylesheets, :third_party] do
    end

    desc "Upload font files to CDN"
    task :fonts do
      fonts = get_files('public/assets/fonts/**/*')
      fonts.each do |filename|
        headers = { 'Access-Control-Allow-Origin' =>  '*' }
        write_cloudfiles_file(cloudfiles_container, filename, headers)
      end
    end

    desc "Upload image files to CDN"
    task :images do
      assets = get_files('public/assets/images/**/*')
      assets.each { |filename| write_aws_file(aws_bucket, filename) }
    end

    desc "Upload javascript files to CDN"
    task :javascripts do
      assets = get_files('public/assets/javascripts/**/*')
      assets.each { |filename| write_aws_file(aws_bucket, filename) }
    end

    desc "Upload stylesheet files to CDN"
    task :stylesheets do
      assets = get_files('public/assets/stylesheets/**/*')
      assets.each { |filename| write_aws_file(aws_bucket, filename) }
    end

    desc "Upload third party files to CDN"
    task :third_party do
      assets = get_files('public/assets/jquery-ui/**/*', 'public/assets/jqzoom/**/*')
      assets.each { |filename| write_aws_file(aws_bucket, filename) }
    end
  end # :upload
end # :cdn

def write_cloudfiles_file(container, filename, headers = {}, check_md5 = true)
  type = MIME::Types.type_for(filename)
  type = type.empty? ? get_font_mime_type(filename) : type.first.content_type
  headers['Content-Type'] = type unless type.nil?
  name = cdn_file_path(filename)
  puts "Writing to CloudFiles: #{name} (#{type})"
  object = container.object_exists?(name) ? container.object(name) : container.create_object(name, true)
  object.load_from_filename(filename, headers, check_md5)
end

def write_aws_file(bucket, filename, options = {})
  options[:acl] ||= :public_read
  options[:content_encoding] = 'gzip' if filename =~ /\.gz$/
  options[:content_type] ||= MIME::Types.type_for(filename.gsub(/\.gz$/, '')).first.content_type
  name = cdn_file_path(filename)
  puts "Writing to S3: #{name} (#{options[:content_type]})"
  object = bucket.objects[name]
  object.write(File.open(filename, 'rb').read, options)
end

def get_files(*dir_names)
  assets = Array.new.tap do |ary|
    dir_names.each do |dir|
      Dir[dir].each do |file|
        next if File.ftype(file) == 'directory'
        ary << file
      end
    end
  end
  assets
end

def cdn_file_path(path)
  path.gsub(%r{^public/}, '')
end

def get_font_mime_type(filename)
  extname = File.extname(filename)
  case extname
  when '.ttf' then 'application/x-font-ttf'
  when '.otf' then 'application/x-opentype'
  when '.eot' then 'application/vnd.ms-fontobject'
  when '.woff' then 'application/x-font-woff'
  else
    nil
  end
end

With assets encapsulated in logical namespaces (e.g., javascripts, images, fonts, etc.), additional assets marked for pre-compilation, large JavaScript files manually integrated into the Asset Pipeline, third-party relative paths resolved, and a hybrid CDN solution laid out for serving cross-domain fonts, all the pieces were in place. Here is the Capistrano task to bring it all together:

namespace :assets do
  desc "Compile assets for production"
  task :compile, :roles => :web do
    run "cd #{release_path} && RAILS_ENV=#{rails_env} bundle exec rake assets:precompile --trace"
    run "cp #{release_path}/app/assets/therealretouch/javascripts/admin/editor.comp.js #{release_path}/public/assets/javascripts/admin/editor.comp.js"
    run %{echo "javascripts/admin/editor.comp.js: javascripts/admin/editor.comp.js" >> #{release_path}/public/assets/manifest.yml}
    run "cd #{release_path} && RAILS_ENV=#{rails_env} bundle exec rake cdn:upload:all --trace"
  end
end

after 'deploy:update_code', 'assets:compile'

References:

Asset Pipeline. Sep. 2011. Rails Guides. 31 Jan. 2012 <http://guides.rubyonrails.org/asset_pipeline.html>.
Understanding the Asset Pipeline. Aug. 2011. Railscasts. 31 Jan. 2012 <http://railscasts.com/episodes/279-understanding-the-asset-pipeline>.
Upgrading to Rails 3.1. Sep 2011. Railscasts. 31 Jan. 2012 <http://railscasts.com/episodes/282-upgrading-to-rails-3-1>.

Inside ActionScript 3.0 Event Handling

2009-05-27T04:12:00Z

If you’ve programmed in ActionScript 3.0, you’re undoubtedly familiar with the following code:

someObject.addEventListener(Event.COMPLETE, completeHandler);

You may or may not know that addEventListener() takes five parameters, the last three of which are optional.

addEventListener(type:String, listener:Function, useCapture:Boolean=false, priority:int=0, useWeakReference:Boolean=false)

Have you ever wondered what the last three parameters do? In this article I take a closer look at events and event handling in ActionScript 3.0. Hopefully, by more fully understanding these features, you’ll be better able to leverage the language’s robust event architecture in your projects.

Event Flow

When a display object dispatches an event, the event will pass through three phases, which together comprise the event flow_: the capture phase, the target phase, and the bubbling phase. In ActionScript, these phases are represented by the constants EventPhase.CAPTURING_PHASE, EventPhase.AT_TARGET, and @EventPhase.BUBBLINGPHASE@. When handling an event, its current phase can be determined by examining its eventPhase property.

Capture Phase

First, during the capture phase, all ancestors in the event target’s display hierarchy are notified in reverse order, beginning with the top-level root ancestor and ending with the immediate parent of the event target. This gives ancestors a chance to perform some processing on the event object before the display object that dispatched the event itself is notified.

Target Phase

Next, once all ancestor listeners registered for the capture phase have been notified of the event, the event target itself will be notified. At this point, the event is said to be in the target phase. During the target phase, all listeners registered directly with the event target will be notified. By default, these listeners will be triggered in the order in which they registered with the event target. This order can be altered by passing an integer to the addEventListener() method’s priority parameter. The default event priority is 0. Among listeners registered for the same event type on the same object, those with the greatest priority will be notified first, and those will the lowest priority last, regardless of the order in which they registered with the object. To ensure that an event listener is notified only after all other listeners registered with the same object are notified, you can specify a negative priority. Do note that event priority only affects the order in which listeners are notified during the target phase; the order in which ancestor listeners are notified during the capture and bubbling phases cannot be altered.

Bubbling Phase

Finally, if the event is a bubbling event, meaning its bubbles property is true, all ancestors in the event target’s display hierarchy will be notified beginning with the immediate parent of the event target and bubbling up to the root ancestor. This is known as the bubbling phase. To register ancestor listeners on non-bubbling events, you must register to be notified during the capture phase, as there will be no bubbling phase:

// We pass true to the useCapture parameter
someObject.addEventListener(Event.COMPLETE, completeHandler, true);

`target` versus `currentTarget`

An event’s target property is a reference to the object that dispatched the event. For an event targeted at a nondisplay object, such as an instance of the URLLoader class, the event’s target and currentTarget properties will always be equal. For an event targeted at a display object, the event’s currentTarget property is a reference to the object whose listener is currently processing the event object. When an event is in the target phase, its currentTarget will be same as its target. When an event is in the capture or bubbling phases, currentTarget could be the event target or any of its display ancestors with registered listeners. You will never set the target or currentTarget properties: they are read-only properties set by Flash Player at runtime.

Manipulating Event Behavior

Some ActionScript events have a default behavior. For example, when a text field dispatches a TextEvent.TEXT_INPUT, the default behavior is for the entered text to appear in the text field. If an event is cancelable (i.e., its cancelable property is true), its default behavior can be canceled at runtime with the Event class’s preventDefault() method. The following example illustrates the effects of preventing the default behavior for a TextEvent.TEXT_INPUT event.

package {

import flash.display.Graphics;
import flash.display.Sprite;
import flash.events.MouseEvent;
import flash.events.TextEvent;
import flash.text.TextField;
import flash.text.TextFieldAutoSize;
import flash.text.TextFieldType;
 
[SWF(width="150", height="40", frameRate="40", backgroundColor="0x333333")]
public class Events extends Sprite {
  public function Events() {
    init();
  }
 
  private var enabled:Boolean = true;
  private var textField:TextField = null;
  private var indicator:Sprite = null;
 
  private function init():void {
    textField = new TextField();
    textField.type = TextFieldType.INPUT;
    textField.border = true;
    textField.borderColor = 0x000000;
    textField.background = true;
    textField.backgroundColor = 0xFFFFFF;
    textField.width = 100;
    textField.height = 20;
    textField.x = 10;
    textField.y = 10;
 
    addChild(textField);
 
    textField.addEventListener(TextEvent.TEXT_INPUT, textInputHandler,
      false, 0, true);
 
    indicator = new Sprite();
    indicator.buttonMode = true;
    indicator.useHandCursor = true;
    indicator.x = 130;
    indicator.y = 20;
 
    addChild(indicator);
    updateIndicator();
 
    indicator.addEventListener(MouseEvent.CLICK, clickHandler,
      false, 0, true);
  }
 
  private function textInputHandler(event:TextEvent):void {
    // If enabled is false, prevent default event behavior. As a result,
    // no text is entered into the TextField.
    if (!enabled)
      event.preventDefault();
  }
 
  private function clickHandler(event:MouseEvent):void {
    enabled = !enabled;
    textField.text = "";
    updateIndicator();
  }
 
  private function updateIndicator():void {
    var g:Graphics = indicator.graphics;
 
    g.clear();
    g.lineStyle(1, 0x000000, 1);
    g.beginFill(enabled ? 0x009900 : 0x990000, 1);
    g.drawCircle(0, 0, 10);
    g.endFill();
  }
}
}

Many ActionScript events are not cancelable; in these cases, calling preventDefault() will have no effect on the event’s behavior.

In addition to being able to prevent an event’s default behavior, you can stop an event dispatch altogether. To accomplish this, the Event class provides us with two methods: stopPropagation() and stopImmediatePropagation(). When an event’s stopPropogation() method is invoked, the event dispatch is stopped once all registered listeners on the node that is currently processing the event object have returned. Invoking stopImmediatePropagation() on an event will stop the event dispatch immediately, and no remaining event listeners will be notified.

Event Listeners and Performance Considerations

By default, when an event listener is registered with an object, the object keeps a reference to the event listener in an internal listener list. Furthermore, the object will retain this reference to the event listener throughout the execution of the program, even after there are no other references to the listener. Consider the following:

var o:Object = {};
o.listener = function(event:MouseEvent):void {
  trace("clicked!");
};
 
var s:Sprite = new Sprite();
s.addEventListener(MouseEvent.CLICK, o.listener);
 
// Even though we explicitly set o to null, s retains a reference to
// listener, which prevents o from being garbage collected!
o = null;

This behavior keeps the object to which the listener belongs in memory even after it has been explicitly set to null. It shouldn’t take long to see how this could cause memory management issues!

ActionScript does give us one way to get around this problem, in the form of addEventListener() method’s fifth and final parameter, useWeakReference. When true, the listener registered with the object can become eligible for garbage collection. Altering the previous example to take advantage of useWeakReference makes o.listener, and, consequently, o eligible for garbage collection.

var o:Object = {};
o.listener = function(event:MouseEvent):void {
  trace("clicked!");
};
 
var s:Sprite = new Sprite();
 
// Here we register the listener with useWeakReference set to true
s.addEventListener(MouseEvent.CLICK, o.listener, false, 0, true);
 
// Now o is eligible for garbage collection as we'd expect
o = null;

Just because o.listener is eligible for garbage collection, however, doesn’t necessarily mean it will be garbage collected. The solution is to explicitly unregister the event listener with the object, using addEventListener()’s counterpart, removeEventListener(), which has the following signature:

removeEventListener(type:String, listener:Function, useCapture:Boolean=false);

Note the optional third parameter, useCapture. Look familiar? It’s the same as addEventListener()’s third parameter. This is by design: you must pass the same value for useCapture to removeEventListener() when unregistering a listener as was passed to addEventListener() when registering the listener. Given we have a listener,

private function clickHandler(event:MouseEvent):void {
  // Determine the event's current phase:
  if (event.eventPhase == EventPhase.CAPTURING_PHASE) {
    // Handle event in capture phase
  }
  else if (event.eventPhase == EventPhase.BUBBLING_PHASE) {
    // Handle event in bubbling phase
  }
}

consider the following:

// clickHandler() is registered for the capture phase
container.addEventListener(MouseEvent.CLICK, clickHandler, true);
 
// ...and here it is registered again for the bubbling phase
container.addEventListener(MouseEvent.CLICK, clickHandler);

clickHandler() is registered twice with container: once for the capture phase and once for the bubbling phase. This means that two references to clickHandler() are stored in container‘s internal listener list. When container dispatches a MouseEvent.<span class="caps">CLICK</span> event, clickHandler() will be notified twice. Now let’s unregister clickHandler():

// Unregister clickHandler() for the bubbling phase
container.removeEventListener(MouseEvent.CLICK, clickHandler);
 
// ...and we must unregister it again for the capture phase
container.removeEventListener(MouseEvent.CLICK, clickHandler, true);

When clickHandler() is unregistered with container the first time, useCapture is not specified, so the default value of false is assumed. If we didn’t explicitly unregister clickHandler() again for the capture phase (i.e., passing true for useCapture), it would still receive subsequent MouseEvent.<span class="caps">CLICK</span> events dispatched by container.

You should make a habit of always removing event listeners when you no longer need them. Consider the following example:

public class Example extends Sprite {
  public function Example() {
    stage.addEventListener(MouseEvent.CLICK,
      function(event:MouseEvent):void {
        // Do something with the click event
      });
  }
}

Can you see the problem? The curious reader will notice that we cannot unregister the event listener because there is no reference to it; it is stranded! In this case, the stage will retain a reference to the anonymous function as long as the program is running, long after @Example@’s constructor has returned. To avoid this problem, simply don’t use anonymous listeners. This is much better:

public class Example extends Sprite {
   public function Example() {
      // Because we have a reference to clickHandler(),
      // we can unregister it later
      stage.addEventListener(MouseEvent.CLICK, clickHandler);
   }
   
   private function clickHandler(event:MouseEvent):void {
      // Do something with the click event
   }
}

Referenced Works:

Moock, Colin. Essential ActionScript 3.0. Cambridge: O’Reilley, 2007.
Adobe Flex 3.3 Language and Components Reference. Feb. 2009. Adobe Systems, Inc. 17 May 2009 <http://livedocs.adobe.com/flex/3/langref/>.

Other AS3 Event Resources:

McCauley, Trevor. Introduction to Event Handling in ActionScript 3.0. Feb. 2007. Adobe Developer Connection. 25 May 2009 <http://www.adobe.com/devnet/actionscript/articles/
event_handling_as3.html>