sudojs-rails 0.1.7

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sudojs-rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 robrobbins
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+# Sudojs::Rails
+
+More than just making the currently released versions of sudo.js and sudo-x.js
+available to your application, sudojs-rails is about a development pattern. A pattern that is
+enforced, and made covenient, through the use of generators.
+
+This highly opinionated workflow creates a global-level namespace for your code, a convenient 
+namespace-level observable model, and expects that you want new javascript class objects placed
+into either the `app/assets/javascripts/application/` directory or, preferably, into an
+`app/assets/javascripts/views/<controller_name>/` directory (more below).
+
+Along with this, it is expected you will want a 'manifest' file created (or appended to if existing)
+for the newly created Class Object. Manifests will named for controller actions (or the global `application`)
+and should be loaded either globally (in the `application` case) or per controller (more on this below). This
+allows for a degree of freedom when differentiating assets.
+
+New Class Objects that you create can inherit from sudo.js defined types, or your own custom classes, and 
+be written in .js or .coffee
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'sudojs-rails'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sudojs-rails
+
+## Usage
+
+### Prepare Your Project
+
+Before use, a few steps need to be followed to prepare your project for our preferred workflow.
+
++ We place manifest files into an `app/assets/javascripts/manifests` directory. This means that your
+  `app/views/layouts/application.html.*` file needs to be adjusted to account for this:
+    
+      <%= javascript_include_tag 'manifests/application.js' %>
+
+  Preferably, you will **not** place this in your `head` tag
+
++ We assume that any Class Object not used more than once (i.e. is unique to a particular controller#action)
+  will not go into `application.js` but be placed into its own manifest for that controller. For this to function,
+  a helper method can be constructed:
+
+      # in app/helpers/application_helper.rb
+      def controller_javascript
+        controller_manifest = File.join('manifests', "#{self.controller_name}.js")
+        return '' if Rails.application.assets.find_asset(controller_manifest).nil?
+
+        return javascript_include_tag(controller_manifest)
+      end
+
+  This allows the following, combined with the previous include tag:
+
+      <%= javascript_include_tag 'manifests/application.js' %>
+      <%= controller_javascript %>
+
++ When concatonating for `staging` and `production` environments the following code needs to have been inserted 
+  into your `config/environments/staging` and `config/environments/production` .rb files:
+      
+      # Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)
+      config.assets.precompile += %w( manifests/* )
+
+### In Practice
+
+running the command `rails g` would reveal that a single `sudojs:install` command can be made. Execute the command 
+`rails g sudojs:install -h` to see the USAGE directives. Running `rails g sudojs:install Spam` will install the correct files 
+and directories (with your shiny new `Spam` namespace).
+
+After installing a second generator becomes available, run `rails g` again and `sudojs:class` should now be an option.
+The reason for this is that `:class` depends on a yaml file to be placed in `config/` to function. Execute the command
+`rails g sudojs:class -h` for the directives there.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,28 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'bundler/gem_tasks'
+
+namespace :sudojs do
+  desc "Download the latest released versions sudo.js"
+  task :download_latest do
+    files = {
+      'sudo.js'=>'https://raw.github.com/robrobbins/sudo-js/jquery/build/debug/sudo.js',
+      'sudo-x.js' => 'https://raw.github.com/robrobbins/sudo-js/jquery/build/debug/sudo-x.js'
+    }
+    
+    vendor_dir = "vendor/assets/javascripts"
+
+    require 'open-uri'
+    files.each do |local,remote|
+      puts "Downloading #{local}"
+      File.open "#{vendor_dir}/#{local}", 'w' do |f|
+        f.write open(remote).read
+      end
+    end
+  end
+end

data/lib/generators/sudojs/class/USAGE

@@ -0,0 +1,47 @@
+Description:
+    Create a skeletal sudo.js Class and place the files correctly for a given controller#name.
+
+Example:
+    `rails g sudojs:class View foo#baz`
+
+    Where `View` is a Class Object that this new Object will inherit from. Sudo.js itself
+    will recognize 5 types:
+
+      1. 'Base'
+      2. 'Container'
+      3. 'View'
+      4. 'ViewController'
+      5. 'Dataview'
+
+    The inheritance for any of these will be set as `_.<Name>` as we assume sudo has taken the 
+    global `_` char as an alias. If the argument is any other string we assume you are inheriting
+    from a custom class and pass it through as is.
+
+
+    Where `foo#baz` *can* match a controller#action (like `home#show`) it does not
+    have to. The controller argument (`foo`) allows the generator to place the file correctly and 
+    create/modify the correct manifest file. The name argument will be the proper name of the 
+    Class Object itself
+
+    If a corresponding views/controller/name.html.* is found, a skeletal instantiation of the newly 
+    created View will be placed there
+
+    This will create:
+      app/
+        assests/
+          javascripts/
+            manifests/
+              foo.js
+            views/
+              foo/
+                baz.js
+
+    And modify (if found):
+      app/
+        views/
+          foo/
+            baz.html.*
+
+Note:
+    If the `route` is application level (application#baz) the file will be placed
+    in the application level directory and the manifests/application file will be modified

data/lib/generators/sudojs/class/class_generator.rb

@@ -0,0 +1,107 @@
+require 'generators/sudojs/helpers.rb'
+
+module Sudojs
+  module Generators
+    class ClassGenerator < Rails::Generators::NamedBase
+      include Sudojs::Generators::Helpers
+      source_root File.expand_path('../templates', __FILE__)
+      
+      # not really a route but passed in the form controller#name
+      argument :route, :type =>:string, :default => 'foo#bar'
+
+      def set_vars
+        # recognized sudo.js class objects. unrecognized names will
+        # be considered 'custom' classes
+        @class_names = {
+          'Base' => '_.Base',
+          'Container' => '_.Container',
+          'DataView' => '_.DataView',
+          'View' => '_.View',
+          'ViewController' => '_.ViewController'
+        }
+        ary = route.split('#')
+        @c_name = ary[0]
+        @c_camel = camelize(@c_name)
+        # is this an application level object?
+        @is_application = @c_name == 'application'
+        # 'action' name not always applicable but thats ok
+        @a_name = ary[1]
+        @a_camel = camelize(@a_name)
+        # class invocations with `new` should always use a proper name
+        @a_pascal = @a_camel.capitalize
+        # either inherits from a sudo.js class or a custom one
+        @parent = @class_names[name] || name
+        # the arguments vary in the templates for class types
+        if @parent
+          if @parent == '_.Base' || @parent == '_.Container'
+            @args = 'data'
+          else 
+            @args = 'el, data'
+          end
+        else
+          # cannot guess the args to a custom class
+          @args = '/* args */'
+        end
+      end
+
+      # expand the template to <destination>
+      def copy_class_template
+        if @is_application
+          path = "app/assets/javascripts/application"
+          @path_to_object = namespace
+        else
+          path = "app/assets/javascripts/views/#{@c_name}"
+          @path_to_object = [namespace, '.', @c_camel].join('')
+          # make sure the directory is present (create if not)
+          ensure_cname_dir(path)
+        end
+
+        if use_coffee?
+          template 'class.coffee.erb', "#{path}/#{@a_name}.js.coffee"
+        else
+          template 'class.js.erb', "#{path}/#{@a_name}.js"
+        end
+      end
+
+      def create_or_modify_manifest
+        filename = "app/assets/javascripts/manifests/#{@c_name}.js"
+        if @is_application
+          line = "//= require application/#{@a_name}"
+        else
+          line = "//= require views/#{@c_name}/#{@a_name}"
+        end
+
+        if File.exist? filename
+          # inject_into_file not needed here unless you were using a require tree
+          append_to_file filename, line
+        else
+          template 'manifest.js.erb', filename
+        end
+      end
+
+      def modify_view_if_exists
+        filename = "app/views/#{@c_name}/#{@a_name}.html.#{which_markup}"
+        if File.exist? filename
+          if use_coffee?
+            comment = '#'
+          else
+            comment = '//'
+          end
+          note = "#{comment} Optional invocation of your new Class.\n#{comment} Place this into a jQuery document ready block."
+          content = "\n#{note}\n#{comment} #{@path_to_object}.#{@a_camel} = new #{@path_to_object}.#{@a_pascal}(#{@args});"
+          append_to_file filename, content
+        end
+      end
+
+      private
+
+      def ensure_cname_dir(path)
+        # if exists we will assume a directory
+        unless File.exist? path
+          empty_directory(path)
+        end
+      end 
+
+    end
+  end
+end

data/lib/generators/sudojs/class/templates/class.coffee.erb

@@ -0,0 +1,13 @@
+_.namespace '<%= @path_to_object %>'
+
+class <%= @path_to_object %>.<%= @a_pascal %> extends <%= @parent %>
+  # the constructor can be deleted if not used (most actions can be done in the init)
+  # an obvious choice is when you need to do something `pre-constructor`
+  constructor: (<%= @args %>) ->
+    # perform any actions needed `pre-super` here
+    super <%= @args %>
+
+  # optional init for your new viewController, delete if unused
+  init: ->
+    # do stuff
+

data/lib/generators/sudojs/class/templates/class.js.erb

@@ -0,0 +1,14 @@
+_.namespace('<%= @path_to_object %>');
+
+<%= @path_to_object %>.<%= @a_pascal %> = function(<%= @args %>) {
+  // perform any actions needed `pre-super` here
+  this.construct(<%= @args %>);
+  // perform any `post-super` actions here
+  // remember `init` will also be called `post-super` if present
+};
+
+<%= @path_to_object %>.<%= @a_pascal %>.prototype = Object.create(<%= @parent %>.prototype);
+
+// optional init method for your new viewController, delete if unused
+<%= @path_to_object %>.<%= @a_pascal %>.prototype.init = function init() {};
+

data/lib/generators/sudojs/class/templates/manifest.js.erb

@@ -0,0 +1,5 @@
+<% if @is_application %>
+//= require application/<%= @a_name %>
+<% else %>
+//= require views/<%= @c_name %>/<%= @a_name %>
+<% end %>

data/lib/generators/sudojs/helpers.rb

@@ -0,0 +1,44 @@
+require 'yaml'
+
+module Sudojs
+  module Generators
+    module Helpers
+
+      CFG = YAML.load_file('config/sudo_js.yml') unless defined? CFG
+
+      def namespace
+        CFG['js_namespace']
+      end
+      
+      def which_sudo
+        CFG['which_sudo']
+      end
+
+      def which_markup
+        CFG['which_markup']
+      end
+
+      def use_coffee?
+        CFG['use_coffee']
+      end
+
+      def camelize(what)
+        if what.include? '_'
+          ary = what.split '_'
+          ary.each_with_index {|val, i|
+            val.capitalize! if i > 0
+          }
+          ary.join('')
+        else
+          what
+        end
+      end
+
+      def pascalize(what)
+        n = camelize(what)
+        n.capitalize
+      end
+
+    end
+  end
+end

data/lib/generators/sudojs/install/USAGE

@@ -0,0 +1,27 @@
+Description:
+    Install sudo.js along with it's particular directory hierarchy.
+
+Example:
+    rails g sudojs:install namespace [which_sudo] [which_markup] [use_coffee]
+
+    The only mandatory argument is the initial `namespace`.
+
+    The install generator uses these optional arguments to expand the values in the sudo_js.yml file:
+      1. `which_sudo` => which version of sudo.js are you loading? As sudo.js can be rebuilt into any number
+         of custom configurations, indicate here what name should be placed into the application manifest.
+         Defaults to 'sudo-x' if omitted.
+      2. `which_markup` => defaults to `erb`.
+      3. `use_coffee` => defaults to `false` pass `true` if you are of the coffee persuasion.
+
+    This will create:
+    app/
+      assets/
+        javascripts/
+          application/
+            yourNamespace.js
+            model.js
+          manifests/
+            application.js
+          views/
+    config/
+      sudo_js.yml

data/lib/generators/sudojs/install/install_generator.rb

@@ -0,0 +1,34 @@
+module Sudojs
+  module Generators
+    class InstallGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+
+      argument :which_sudo_arg, :type => :string, :default => 'sudo-x'
+      argument :which_markup_arg, :type => :string, :default => 'erb'
+      argument :use_coffee_arg, :type => :string, :default => 'false'
+
+      def create_yaml
+        template 'sudo_js.erb.yml', 'config/sudo_js.yml'
+      end
+
+      def create_dir_structure
+        %W{application manifests views}.each do |dir|
+          empty_directory "app/assets/javascripts/#{dir}" 
+        end
+      end
+
+      def place_install_files
+        template 'app_manifest.js.erb', 'app/assets/javascripts/manifests/application.js'
+        
+        unless use_coffee_arg == 'false'
+          template 'namespace.coffee.erb', "app/assets/javascripts/application/#{name}.js.coffee"
+          template 'model.coffee.erb', 'app/assets/javascripts/application/model.js.coffee'
+        else
+          template 'namespace.js.erb', "app/assets/javascripts/application/#{name}.js"
+          template 'model.js.erb', 'app/assets/javascripts/application/model.js'
+        end
+      end
+
+    end
+  end
+end