yellow-brick-road 0.1.1

data/README.rst

@@ -0,0 +1,148 @@
+Yellow Brick Road
+=================
+
+Closure library on rails
+------------------------
+
+..  image:: http://i.imgur.com/BeZpM.jpg
+    :align: right
+
+Yellow-brick-road is a set of tools to integrate google `closure library <http://code.google.com/closure/library/>`_ and `soy closure template <http://code.google.com/closure/templates/>`_ into rails. This gem can be used for:
+
+* Automatic dependency generation of a closure-library based application, just add the ``//= require_closure_root`` directive.
+
+* Using soy templates as part of the closure-library.
+
+* Using stand-alone soy templates without closure-library, just configure the gem add the ``.js.soy`` file in assets directory, and it gets compiled automatically.
+
+Setup
++++++
+
+To use yellow-brick-road in rails, add the gem to ``Gemfile``:
+
+::
+  
+  gem 'yellow-brick-road',
+    :git => 'git://github.com/alitn/yellow-brick-road.git',
+    :submodules => true
+
+A copy of the closure library comes with the gem as a git submodule. The ``:submodules => true`` option is required to clone this copy.
+
+Integrating closure library
++++++++++++++++++++++++++++
+
+Yellow-brick-road provides a `sprockets <https://github.com/sstephenson/sprockets>`_ directive for requiring a closure root. Given ``my-closure-app/`` as a closure app directory, it can be required by:
+
+::
+  
+  //= require_closure_root ./my-closure-app
+  
+This renders a couple of script tags:
+
+::
+  
+  <script src="/assets/closure/goog/base.js" type="text/javascript"></script>
+  <script src="/assets/closure-deps.js" type="text/javascript"></script>
+  
+The former tag is the base requirement for closure library.
+
+The latter tag, generated using `depswriter.py <http://code.google.com/closure/library/docs/depswriter.html>`_, is the dependency structure of the closure application. When the required closure root is modified, this dependency file is regenerated. It is safe to ignore this file in source revision control.
+
+Soy templates used with closure-library
++++++++++++++++++++++++++++++++++++++++
+
+Requiring a ``.js.soy`` template works out-of-the-box:
+
+::
+  
+  //= require simple.js.soy
+  
+By default, it is assumed that soy templates are used as part of the closure-library. The gem adds the ``soyutils_usegoog.js`` file to closure dependency search path, and the soy templates get compiled with these options:
+
+::
+  
+  --shouldProvideRequireSoyNamespaces
+  --cssHandlingScheme goog
+  --shouldGenerateJsdoc
+  
+This means that a template like this:
+
+::
+  
+  {namespace myproject.templates}
+
+  /**
+   * Greets a person using "Hello" by default.
+   * @param name The name of the person.
+   * @param? greetingWord Optional greeting word to use instead of "Hello".
+   */
+  {template .hello}
+    {if not $greetingWord}
+      Hello {$name}!
+    {else}
+      {$greetingWord} {$name}!
+    {/if}
+  {/template}
+  
+is compiled to:
+
+::
+  
+  // This file was automatically generated from simple.js.soy.
+  // Please don't edit this file by hand.
+
+  goog.provide('myproject.templates');
+
+  goog.require('soy');
+  goog.require('soy.StringBuilder');
+
+
+  /**
+   * @param {Object.<string, *>=} opt_data
+   * @param {soy.StringBuilder=} opt_sb
+   * @return {string}
+   * @notypecheck
+   */
+  myproject.templates.hello = function(opt_data, opt_sb) {
+    var output = opt_sb || new soy.StringBuilder();
+    output.append((! opt_data.greetingWord) ? 'Hello ' + soy.$$escapeHtml(opt_data.name) + '!' :
+     soy.$$escapeHtml(opt_data.greetingWord) + ' ' + soy.$$escapeHtml(opt_data.name) + '!');
+    return opt_sb ? '' : output.toString();
+  };
+
+Standalone Soy templates
+++++++++++++++++++++++++
+
+Yellow-brick-road can also be used for automatic compilation of soy templates without the use of closure-library. This helps to integrate soy templates with other javascript frameworks like backbone.js.
+
+To do this, add this line to a rails initializer, eg ``config/initializers/yellow_brick_road.rb``:
+
+::
+  
+  YellowBrickRoad::Config.standalone_soy = true
+  
+Then require the soy javascript utility, which is shipped with the gem:
+
+::
+  
+  //= require soyutils.js
+  //= require simple.js.soy
+
+In this case, the above template is compiled to:
+
+::
+  
+  // This file was automatically generated from simple.js.soy.
+  // Please don't edit this file by hand.
+
+  if (typeof myproject == 'undefined') { var myproject = {}; }
+  if (typeof myproject.templates == 'undefined') { myproject.templates = {}; }
+
+
+  myproject.templates.hello = function(opt_data, opt_sb) {
+    var output = opt_sb || new soy.StringBuilder();
+    output.append((! opt_data.greetingWord) ? 'Hello ' + soy.$$escapeHtml(opt_data.name) + '!' :
+     soy.$$escapeHtml(opt_data.greetingWord) + ' ' + soy.$$escapeHtml(opt_data.name) + '!');
+    return opt_sb ? '' : output.toString();
+  };
+  

data/Rakefile

@@ -0,0 +1,37 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'YellowBrickRoad'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/tasks/yellow-brick-road_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :yellow-brick-road do
+#   # Task goes here
+# end

data/lib/yellow-brick-road.rb

@@ -0,0 +1,6 @@
+require 'yellow-brick-road/version'
+require 'yellow-brick-road/config'
+require 'yellow-brick-road/utils'
+require 'yellow-brick-road/directive_processor'
+require 'yellow-brick-road/soy_processor'
+require 'yellow-brick-road/engine'

data/lib/yellow-brick-road/config.rb

@@ -0,0 +1,15 @@
+module YellowBrickRoad
+  module Config
+    mattr_accessor :standalone_soy
+    @@stand_alone_soy = false
+  end
+
+  # Constants.
+  ROOT = File.expand_path File.join(File.dirname(__FILE__), '..', '..')
+  VENDOR_ASSETS_ROOT = File.join ROOT, 'vendor'
+  CLOSURE_LIBRARY_ROOT = File.join VENDOR_ASSETS_ROOT, 'closure-library'
+  CLOSURE_LIBRARY_BASE = File.join CLOSURE_LIBRARY_ROOT, 'closure', 'goog', 'base.js'
+  CLOSURE_SOYUTILS_ROOT = File.join VENDOR_ASSETS_ROOT, 'closure-soyutils'
+  CLOSURE_SOYUTILS_USEGOOG_ROOT = File.join VENDOR_ASSETS_ROOT, 'closure-soyutils-usegoog'
+  CLOSURE_DEPSWRITER = File.join CLOSURE_LIBRARY_ROOT, 'closure', 'bin', 'build', 'depswriter.py'
+end

data/lib/yellow-brick-road/directive_processor.rb

@@ -0,0 +1,68 @@
+require 'sprockets/directive_processor.rb'
+
+module YellowBrickRoad
+class ClosureBuilderProcessor < Sprockets::DirectiveProcessor
+
+  def prepare
+    super
+    @closure_roots = []
+    @closure_deps_file = Rails.root.join 'app', 'assets', 'javascripts', 'closure-deps.js'
+    @has_executed_closure_builder = false
+  end
+
+  def process_require_closure_root_directive path
+    context.require_asset CLOSURE_LIBRARY_BASE
+    context.require_asset @closure_deps_file
+
+    if relative? path
+      closure_root = pathname.dirname.join(path).expand_path
+
+      unless (stats = stat(closure_root)) && stats.directory?
+        raise ArgumentError, 'require_closure_root argument must be a directory'
+      end
+
+      context.depend_on closure_root
+
+      each_entry closure_root do |pathname|
+        context.depend_on pathname
+      end
+    else
+      # The path must be relative and start with a `./`.
+      raise ArgumentError, 'require_closure_root argument must be a relative path'
+    end
+
+    @closure_roots << closure_root.to_s
+  end
+
+  def process_directives
+    super
+    generate_closure_dependencies
+  end
+
+private
+  
+  def generate_closure_dependencies
+    return nil if @closure_roots.empty? || @has_executed_closure_builder
+
+    if !Config.standalone_soy
+      @closure_roots.unshift << CLOSURE_SOYUTILS_USEGOOG_ROOT
+    end
+
+    closure_roots_with_prefix = @closure_roots.map { |cr| "'#{cr} ../../'" }
+
+    result = Utils::run_command CLOSURE_DEPSWRITER,
+      command_options: {
+        root_with_prefix: closure_roots_with_prefix,
+        output_file: @closure_deps_file
+      },
+      command_error_message: 'An error occured while running closure depswriter.py.'
+
+    @has_executed_closure_builder = true
+    Rails.logger.info "Executed closure depswriter.py on root paths: #{@closure_roots.join(', ')}"
+
+
+    result
+  end
+
+end
+end

data/lib/yellow-brick-road/engine.rb

@@ -0,0 +1,22 @@
+module YellowBrickRoad
+CONFIG = ActiveSupport::OrderedOptions.new
+
+class Engine < Rails::Engine
+
+  initializer :yellow_brick_road do |app|
+    app.assets.append_path CLOSURE_LIBRARY_ROOT
+
+    if Config.standalone_soy
+      app.assets.append_path CLOSURE_SOYUTILS_ROOT
+    else
+      app.assets.append_path CLOSURE_SOYUTILS_USEGOOG_ROOT
+    end
+
+    app.assets.unregister_processor 'application/javascript', Sprockets::DirectiveProcessor
+    app.assets.register_processor 'application/javascript', ClosureBuilderProcessor
+
+    app.assets.register_engine '.soy', SoyProcessor
+  end
+
+end
+end

data/lib/yellow-brick-road/soy_processor.rb

@@ -0,0 +1,56 @@
+require 'tilt'
+require 'closure'
+
+module YellowBrickRoad
+class SoyProcessor < Tilt::Template
+
+  def self.default_mime_type
+    'application/javascript'
+  end
+
+  def self.default_namespace
+    'this.SOY'
+  end
+
+  def prepare
+    @namespace = self.class.default_namespace
+  end
+
+  attr_reader :namespace
+
+  def evaluate scope, locals, &block
+    # Since SoyToJsSrcCompiler does not provide a stdout access to
+    # the output, the output is written to a tempfile.
+    tempoutput = Rails.root.join 'tmp', "soy-#{Time.now.to_i.to_s}.js"
+
+    compiler_args = []
+    if !Config.standalone_soy
+      compiler_args = compiler_args | %w{
+        --shouldProvideRequireSoyNamespaces
+        --cssHandlingScheme goog
+        --shouldGenerateJsdoc
+      }
+    end
+    compiler_args << "--outputPathFormat" << tempoutput
+    compiler_args << file
+    compile compiler_args
+
+    @output = IO.read tempoutput
+    File.delete tempoutput
+
+    @output
+  end
+
+private
+
+  def compile args
+    args = args.collect {|a| a.to_s } # for bools and numerics
+
+    out, err = Closure.run_java Closure.config.soy_js_jar, 'com.google.template.soy.SoyToJsSrcCompiler', args
+    unless err.empty?
+      raise err
+    end
+  end
+
+end
+end

data/lib/yellow-brick-road/utils.rb

@@ -0,0 +1,38 @@
+require 'open3'
+
+module YellowBrickRoad
+class Utils
+
+  def self.run_command command, options
+    options = {
+      command_options: {},
+      command_error_message: "An error occured while running command: #{command}"
+    }.merge options
+
+    command_options = self.serialize_options options[:command_options]
+    command_string = [command, command_options].flatten.join(' ')
+
+    begin
+      stdin, stdout, stderr = Open3.popen3 command_string
+    rescue StandardError => error
+      raise "#{options[:command_error_message]}\n\n#{error.message}"
+    end
+
+    stdout.readlines
+  end
+
+  private
+
+  def self.serialize_options options
+    options.map do |k, v|
+      if v.is_a?(Array)
+        v.uniq!
+        v.map {|v2| ["--#{k}", v2.to_s]}
+      else
+        ["--#{k}", v.to_s]
+      end
+    end.flatten
+  end
+
+end
+end

data/lib/yellow-brick-road/version.rb

@@ -0,0 +1,3 @@
+module YellowBrickRoad
+  VERSION = '0.1.1'
+end

data/test/dummy/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,12 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_closure_root ./my-closure
+//= require ./my-closure/simple.js.soy
+//= require ./my-closure/start
+//

data/test/dummy/app/assets/javascripts/closure-deps.js

@@ -0,0 +1,4 @@
+// This file was autogenerated by /Volumes/Development/dev-web/yellow-brick-road/vendor/closure-library/closure/bin/build/depswriter.py.
+// Please do not edit.
+goog.addDependency('../../soyutils_usegoog.js', ['soy', 'soy.StringBuilder', 'soy.esc', 'soydata', 'soydata.SanitizedHtml', 'soydata.SanitizedHtmlAttribute', 'soydata.SanitizedJsStrChars', 'soydata.SanitizedUri'], ['goog.asserts', 'goog.dom.DomHelper', 'goog.format', 'goog.i18n.BidiFormatter', 'goog.i18n.bidi', 'goog.soy', 'goog.string', 'goog.string.StringBuffer']);
+goog.addDependency('../../start.js', ['myproject.start'], ['goog.dom', 'myproject.templates']);

data/test/dummy/app/assets/javascripts/my-closure/simple.js.soy

@@ -0,0 +1,14 @@
+{namespace myproject.templates}
+
+/**
+ * Greets a person using "Hello" by default.
+ * @param name The name of the person.
+ * @param? greetingWord Optional greeting word to use instead of "Hello".
+ */
+{template .hello}
+  {if not $greetingWord}
+    Hello {$name}!
+  {else}
+    {$greetingWord} {$name}!
+  {/if}
+{/template}