extjs-mvc 0.3.10 → 0.4.0.a

data/lib/extjs-mvc/builders/plugin_builder.rb

@@ -0,0 +1,53 @@
+module ExtJS
+  module MVC
+    class PluginBuilder < Builder
+      # returns an array of PluginBuilder instances based on input from the command line.
+      # The sole argument should be an array, where the first element will usually be a plugin name, or 'all'
+      def self.instances(args = [])
+        name = args[0] || 'all'
+      
+        if name == 'all'
+          self.all_plugin_names.collect {|name| ExtMVC::PluginBuilder.new(name)}
+        else
+          [ExtMVC::PluginBuilder.new(name)]
+        end
+      end
+    
+      attr_accessor :name
+    
+      def initialize(name)
+        @name = name
+      end
+    
+      def output_filename
+        "#{directory_name}/#{name}-all.js"
+      end
+    
+      def message
+        "Built the #{name} plugin"
+      end
+    
+      def description
+        "The #{name} plugin (#{directory_name})"
+      end
+    
+      def directory_name
+        "#{ExtMVC::PluginBuilder.plugins_directory}/#{@name}"
+      end
+    
+      # The plugins directory, relative to the directory the build command is run from
+      def self.plugins_directory
+        "vendor/plugins"
+      end
+    
+      private
+    
+      #Gets the name of each plugin directory inside vendor/plugins and calls self.plugin with it
+      def self.all_plugin_names
+        Dir.entries(self.plugins_directory).select {|fileName| 
+          File.directory?("#{self.plugins_directory}/#{fileName}") && (fileName =~ /^\./) != 0
+        }
+      end
+    end
+  end
+end

data/lib/extjs-mvc/cli.rb

@@ -0,0 +1,52 @@
+require 'thor'
+
+require 'jammit-core'
+require 'jammit-core/cli'
+  
+module ExtJS
+  module MVC
+    class CLI < Thor
+      ARGV = ::ARGV.dup
+      
+      desc "generate", "Generate model, controller, view or app"
+      def generate(which, *params)
+        ExtJS::MVC.ensure_in_app unless which == 'app'
+        ExtJS::MVC::Generator.dispatch(which, *params)  
+      end
+      
+      desc "build", "Build stuff"
+      def build(name = :all, *params)
+        ExtJS::MVC.ensure_in_app
+        ExtJS::MVC::BuilderManager.dispatch(name, *params)
+      end
+      
+      desc "plugin", "Manage plugins"
+      def plugin
+        ExtJS::MVC.ensure_in_app
+        ExtJS::MVC::Plugin.new('Frak')
+      end
+      
+      desc "stats", "View code statistics"
+      def stats
+        ExtJS::MVC.ensure_in_app
+        #ExtJS::MVC::Stats.new('Frak')
+      end
+      
+      desc "namespace", "Change the application's namespace"
+      def namespace(name)
+        ExtJS::MVC.ensure_in_app
+        ExtJS::MVC::Generator.dispatch("namespace", name)
+      end
+      
+      def initialize(args=ARGV, config={}, options={})
+        
+        ExtJS::MVC.ui = UI::Shell.new(shell)
+        
+        super
+      end
+      
+      private
+    
+    end
+  end
+end

data/lib/extjs-mvc/generator.rb

@@ -0,0 +1,79 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'hpricot'
+require 'generators/base'
+require 'generators/app'
+require 'generators/model'
+require 'generators/view'
+require 'generators/controller'
+require 'generators/scaffold'
+
+module ExtJS
+  module MVC
+    module Generator
+    
+      @@generators = %w(app model controller scaffold view namespace)
+      def self.dispatch(generator, *params)
+        
+        unless @@generators.include?(generator)
+          raise ArgumentError.new("Must use one of the following: " + @@generators.join(", ").downcase)
+        end
+        
+        name = params.shift
+        
+        case generator
+          when "app"
+            App.new(name).generate!
+          when "model"
+            fields = params.select {|arg| arg != "--force"}.collect {|f| f.split(":")}
+            Model.new(name, fields).generate!
+          when "controller"
+            actions = params.select {|arg| arg != "--force"}
+            Controller.new(name, actions).generate!
+          when "scaffold"
+            fields = params.select {|arg| arg != "--force"}.collect {|f| f.split(":")}
+            Scaffold.new(name, fields).generate!
+          when "view"
+            package = name
+            name = params.shift
+            View.new(package, name).generate!
+          when "namespace"
+            self.namespace(name)
+            
+        end
+      end
+      
+       # overwrites all instances of 'MyApp' with the namespace provided
+      def self.namespace(namespace)
+        current = ExtJS::MVC.namespace
+        
+        configs = %w(
+          config/settings.yml
+          config/application.js
+        )
+        Dir["app/controllers/*.js"].each do |f|
+          write_namespace(f, current, namespace)
+        end
+        Dir["app/views/*/*.js"].each do |f|
+          write_namespace(f, current, namespace)
+        end
+        configs.each {|f| 
+          write_namespace(f, current, namespace)
+        }
+      end
+
+      private
+      
+      def self.write_namespace(f, current, namespace)
+        ExtJS::MVC.ui.confirm(" namespacing #{f}")
+        gsub_file(f, current, namespace)
+      end
+        
+      #find/replace in a file.  Stolen/adapted from Rails
+      def self.gsub_file(filename, regexp, *args, &block)
+        content = File.read(filename).gsub(regexp, *args, &block)
+        File.open(filename, 'wb') { |file| file.write(content) }
+      end  
+    end
+  end
+end

data/lib/extjs-mvc/generators/app.rb

@@ -0,0 +1,57 @@
+module ExtJS
+  module MVC
+    module Generator
+      class App < Base
+      
+        def initialize(name, namespace=nil)
+          
+          @name = name
+          @namespace = namespace || Extlib::Inflection.camelize(name)
+        end
+  
+        def generate!    
+          if File.exists?(@name)
+            raise ExtJS::MVC::AppAlreadyExists.new("An app named #{@name} already exists")
+          end
+          FileUtils.mkdir(@name)
+          Dir["#{TEMPLATE_PATH}/app/*"].each do |f|
+            FileUtils.cp_r(f, @name)
+          end
+          
+          FileUtils.cp_r("#{ExtJS::MVC::ROOT}/js", "#{@name}/vendor")
+          FileUtils.mv("#{@name}/vendor/js", "#{@name}/vendor/mvc")
+          
+          show_files
+          
+          # Build assets.
+          ExtJS::MVC::BuilderManager.dispatch(:setup, {
+            :asset_root => File.expand_path('.', @name)
+          })
+        end
+  
+        private
+        
+        def notify(f)
+          @re ||= Regexp.new("#{@name}\/(.*)")
+          ExtJS::MVC.ui.confirm(" create #{f.match(@re)[1]}")
+        end
+        
+        def show_files
+          Dir["#{@name}/*"].reject {|dir| 
+            dir.match(/public|vendor/) ? true : false
+          }.each do |dir|
+            Dir["#{dir}/**/*.*"].each do |f|
+              notify(f)
+            end
+          end
+          Dir["#{@name}/vendor/*"].each do |f|
+            notify(f)
+          end
+          Dir["#{@name}/public/*"].each do |f|
+            notify(f)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/extjs-mvc/generators/base.rb

@@ -0,0 +1,53 @@
+module ExtJS
+  module MVC
+    module Generator
+      class Base
+        
+        TEMPLATE_PATH = "#{File.dirname(__FILE__)}/templates"
+                                
+        def initialize *args
+          @gsubs ||= {}
+          @gsubs['namespace']  = ExtJS::MVC.environment['namespace']
+        end
+
+        protected
+        def ensure_directories_present! *args
+          args.each do |a|
+            Dir.mkdir(a) unless File.exists?(a)
+          end
+        end
+
+        def ensure_no_overwrite! *args
+          args.each do |a|
+            if File.exists?(a) && !ARGV.include?("--force")
+              raise ExtJS::MVC::FileExists.new("File already exists: #{a}")
+            end
+          end
+        end
+
+        def template(template_filename, destination_filename)
+          #write the file
+          File.open(destination_filename, 'w') {|f| f.puts(render_template(template_filename))}
+  
+          ExtJS::MVC.ui.confirm(" Created #{destination_filename}")
+        end
+
+        def render_template(template_filename, gsubs = @gsubs)
+          #grab the template file text
+          template_text = IO.read("#{TEMPLATE_PATH}/#{template_filename}")
+  
+          #translate the template file text
+          gsubs.each_pair do |key, value|
+            template_text.gsub!(Regexp.new("<%= @#{key} %>"), value)
+          end
+  
+          template_text
+        end
+
+        def include_script html_filename, script_filename, dom_id
+  
+        end
+      end
+    end
+  end
+end

data/lib/extjs-mvc/generators/controller.rb

@@ -0,0 +1,41 @@
+module ExtJS
+  module MVC
+    module Generator
+      class Controller < Base
+        def initialize(name, actions = [])
+          super
+  
+          @name    = name
+          @actions = actions
+          @package = name.downcase
+  
+          @gsubs.merge!({
+            'controller_name' => "#{name.capitalize}Controller",
+            'short_name'      => @package,
+            'actions'         => generate_actions
+          })
+  
+          @controller_filename = "app/controllers/#{@gsubs['controller_name']}.js"
+        end
+
+        def generate!
+          ensure_no_overwrite!        @controller_filename
+          ensure_directories_present! "app", "app/controllers"
+  
+          template "Controller.js", @controller_filename
+  
+          generate_views!
+        end
+
+        private
+        def generate_actions
+          @actions.collect {|act| render_template("_Action.js", {'action_name' => act})}.join("")
+        end
+
+        def generate_views!
+          @actions.each {|a| View.new(@package, a).generate!}
+        end
+      end
+    end
+  end
+end

data/lib/extjs-mvc/generators/model.rb

@@ -0,0 +1,41 @@
+module ExtJS
+  module MVC
+    module Generator
+      class Model < Base
+        def initialize(name, fields = [])
+          super
+  
+          @fields = fields
+  
+          @gsubs['name']       = name.capitalize
+          @gsubs['model_name'] = name
+          @gsubs['inst_name']  = name.downcase
+          @gsubs['fields']     = fields.collect {|f| field_template(f[0], f[1])}.join(",\n")
+  
+          @model_filename = "app/models/#{@gsubs['name']}.js"
+          @spec_filename  = "spec/models/#{@gsubs['name']}.spec.js"
+        end
+
+        def generate!
+          ensure_no_overwrite! @model_filename, @spec_filename
+  
+          ensure_directories_present! "app",  "app/models"
+          ensure_directories_present! "spec", "spec/models"
+          
+          template "Model.js",     @model_filename
+          template "ModelSpec.js", @spec_filename
+        end
+
+        private
+        def field_template(name, type)
+          padding = longest_field_length - name.length
+          "    {name: '#{name}', #{" " * padding}type: '#{type}'}"
+        end
+
+        def longest_field_length
+          @fields.collect {|f| f[0].length}.max
+        end
+      end
+    end
+  end
+end

data/lib/extjs-mvc/generators/scaffold.rb

@@ -0,0 +1,17 @@
+module ExtJS
+  module MVC
+    module Generator
+      class Scaffold < Base
+        def initialize(name, fields = [])
+          super
+          @fields = fields
+          @name = name
+        end
+
+        def generate!
+          Model.new(@name, @fields).generate!
+        end
+      end
+    end
+  end
+end

data/lib/extjs-mvc/generators/templates/Controller.js

@@ -0,0 +1,17 @@
+/**
+ * @class <%= @namespace %>.controllers.<%= @controller_name %>
+ * @extends ExtMVC.Controller
+ */
+<%= @namespace %>.controllers.<%= @controller_name %> = Ext.extend(ExtMVC.Controller, {
+  constructor: function() {
+    //super
+    <%= @namespace %>.controllers.<%= @controller_name %>.superclass.constructor.call(this, {
+      viewsPackage: <%= @namespace %>.views.<%= @short_name %>
+    });
+<%= @actions %>
+  }
+});
+
+ExtMVC.OS.getOS().registerController('<%= @short_name %>', <%= @namespace %>.controllers.<%= @controller_name %>);
+
+Ext.ns('<%= @namespace %>.views.<%= @short_name %>');

data/lib/extjs-mvc/generators/templates/Model.js

@@ -0,0 +1,9 @@
+/**
+ * @class <%= @name %>
+ * @extends ExtMVC.model.Base
+ */
+ExtMVC.model.define("<%= @name %>", {
+  fields:    [
+<%= @fields %>
+  ]
+});

data/lib/extjs-mvc/generators/templates/ModelSpec.js

@@ -0,0 +1,12 @@
+Screw.Unit(function() {
+  describe("The <%= @name %> class", function() {
+    var <%= @inst_name %>;
+    before(function() {
+      <%= @inst_name %> = new <%= @namespace %>.models.<%= @name %>({
+        //set fields for this model here
+      });
+    });
+    
+    //create your unit tests here
+  });
+});

data/lib/extjs-mvc/generators/templates/View.js

@@ -0,0 +1,16 @@
+/**
+ * @class <%= @namespace %>.views.<%= @view_namespace %>.<%= @name %>
+ * @extends Ext.Panel
+ * A default generated view
+ */
+<%= @namespace %>.views.<%= @view_namespace %>.<%= @name %> = Ext.extend(Ext.Panel, {
+
+  initComponent: function() {
+    Ext.applyIf(this, {
+      title: "<%= @name %> Template",
+      html:  "Find me in <%= @filename %>"
+    });
+    
+    <%= @namespace %>.views.<%= @view_namespace %>.<%= @name %>.superclass.initComponent.apply(this, arguments);
+  }
+});

data/lib/extjs-mvc/generators/templates/_Action.js

@@ -0,0 +1,7 @@
+
+    /**
+     * @action <%= @action_name %> 
+     */
+    this.registerAction('<%= @action_name %>', function() {
+      this.renderView('<%= @action_name %>');
+    });

data/lib/extjs-mvc/generators/templates/app/README.rdoc

@@ -0,0 +1,152 @@
+= ExtJS MVC Base App
+
+Ext MVC Application structure for any new MVC application.  Structure inspired by Ruby on Rails.
+
+== Installation
+
+Clone this as the starting point for your apps.  Place your cloned directory somewhere apache can serve it, then head to index.html:
+
+http://localhost/myDirectory/index.html
+
+You should see a default application set up and ready to go.
+
+== Prerequisites
+
+Most prerequisites are installed for you inside the vendor directory:
+
+* vendor/ext            - contains a copy of ExtJS v2.2.1 (debug version, production copy by defaults comes off the cachefly CDN)
+* vendor/mvc            - contains a copy of the latest stable version of Ext MVC (debug and minified versions)
+* vendor/screw-unit     - contains a copy of ScrewUnit, a BDD testing framework for JavaScipt
+* vendor/yui-compressor - contains a copy of the YUI compressor, which is used in the automatic build process
+
+Although is is not strictly a prerequisite, you are *strongly* advised to install Ruby and Rubygems as the scripts below will automate a lot of things 
+for you and save you a lot of time.  If you're running OSX you probably already have these, if you're on Windows it's a very simple install process.
+Take a look at http://rubyonrails.org/download for instructions (just the Ruby and RubyGems sections).
+
+If you don't intend to use the Ruby automation scripts, you can safely delete the script, vendor/mvc/scripts and vendor/yui-compressor folders.
+
+== Getting Started
+
+The only thing you need to change is the namespace your application will be using.  Choose a meaningful namespace for your application - e.g. for
+a blog application you might choose BlogApp, or something similar.  All of your code will sit under that namespace, like this:
+
+* BlogApp.models.Post                 // reference to a Post model constructor
+* BlogApp.controllers.IndexController // reference to a controller constructor
+* BlogApp.views.posts.New             // reference to a view constructor, usually an Ext.Panel subclass
+
+It doesn't matter if you don't know what those do yet, the important thing is that you don't pollute the global namespace.  The whole of Ext MVC is
+build around this idea.
+
+Once you've chosen your namespace, just run the following command:
+
+ruby script/setup MyAppNamespace
+
+This will update all files with the default namespace ('MyApp') with the namespace you specify.
+
+If you can't run the script, you can easily perform the setup yourself - just change the references from the default 'MyApp' namespace to your own 
+namespace in the following files:
+
+* app/OS.js
+* app/controllers/IndexController.js
+* app/views/index/Index.js
+* config/initialize.js
+* config/settings.yml
+
+Just use a simple find/replace all.
+
+== Build tools
+
+You need to ensure you have Ruby installed to use the build tools, and also the rake and hpricot gems (sudo gem install rake hpricot).
+
+Ext MVC will automatically build (concatenate and minify) your javascript and CSS files.  Just run the following command from the base directory:
+
+ruby script/build all
+
+This will inspect the javascript and css include tags inside index.html and compress them into a single JS file and a single CSS file.  It will minify
+the javascript if the YUI Compressor is installed in vendor/yui-compressor and create the following files:
+
+* public/application-all.js
+* public/application-all-min.js
+* public/stylesheets/application-all.css
+
+== Generators:
+
+Ext MVC comes with some built-in generators to automate some aspects of application development.  Run the generators
+described below from within the main directory of your Ext MVC application.
+
+Be sure that you have updated your config/settings.yml file before running these, otherwise everything will be namespaced
+to 'MyApp' (see above).
+
+=== Model
+
+ruby script/generate model User first_name:string last_name:string balance:int is_admin:boolean
+
+Will generate the following files:
+
+in app/models/User.js:
+/**
+ * @class MyApp.models.MyModel
+ * @extends ExtMVC.Model
+ */
+ExtMVC.Model.define("MyApp.models.User", {
+  modelName: 'user',
+  fields:    [
+    {name: 'first_name', type: 'string'},
+    {name: 'last_name',  type: 'string'},
+    {name: 'balance',    type: 'int'},
+    {name: 'is_admin',   type: 'boolean'}
+  ]
+});
+
+in spec/models/User.spec.js:
+Screw.Unit(function() {
+  describe("The User class", function() {
+    var user;
+    before(function() {
+      user = new MyApp.models.User({
+        //set fields for this model here
+      });
+    });
+    
+    //create your unit tests here
+  });
+});
+
+It will also add the following line to your index.html file:
+
+<script type="text/javascript" src="app/models/User.js"></script>
+
+And the following to your spec/index.html file:
+
+<script type="text/javascript" src="../app/models/User.js"></script>
+<script type="text/javascript" src="models/User.spec.js"></script>
+
+
+== Deployment
+
+Once you've built your app, upload only the 'public' folder to your web server.  Nothing else is required to run the app.
+
+== Directory Structure:
+
+* app             - a directory to contain your models, views and controllers
+* app/controllers - contains all of your controllers
+* app/models      - contains all modesl
+* app/views       - contains all view files, usually in subdirectories (e.g. app/views/users/Index.js)
+* config          - contains application configuration files (see below)
+* lib             - contains any library files which are not suited to being plugins
+* public          - the directory you will set as document root on your web server.  Place any public-facing assets in here.  Note that all javascript and stylesheet files will be concatenated automatically into here when you deploy, so these can exist outside of this folder.  Images and other assets will need to be placed here though.
+* script          - contains scripts to automate site build and minification
+* spec            - a directory to place your unit tests or specs
+* vendor          - holds any third-party code
+* vendor/ext      - contains the required version of ExtJS.  ExtJS 2.2 comes pre-installed here, with the Ext adapter.
+* vendor/mvc      - contains the required version of Ext MVC.  Most recent stable version installed by default.  Obtain latest version from http://github.com/extmvc/extmvc/tree
+* vendor/plugins  - contains any MVC-compatible plugins (such as viewport builders, model extensions etc)
+
+== Important Files:
+
+* config/routes.js     - set up any Ext.History related routing required (see file for help)
+* config/initialize.js - any app-wide config code, such as setting up location of s.gif, booting your app, etc
+* config/database.js   - define which data adapter your app uses (RESTful adapter, Gears adapter, your own concoction etc)
+
+* index.html           - Development version of the site, including one file at a time and using ext-all-debug
+* public/index.html    - Production version of the site referencing concatenated and minified files

data/lib/extjs-mvc/generators/templates/app/app/App.js

@@ -0,0 +1,64 @@
+/**
+ * @class MyApp.App
+ * @extends ExtMVC.App
+ * The MyApp application.
+ */
+
+ExtMVC.App.define({
+  name       : "MyApp",
+  
+  /**
+   * Sets up the application's Viewport
+   */
+  launch: function() {
+    
+    Ext.QuickTips.init();
+    
+    this.menu = ExtMVC.buildView('layout', 'menu', {
+      region   : 'west',
+      split: true,
+      width    : 240,
+      listeners: {
+        scope: this,
+        click: function(node) {
+          var attrs = node.attributes;
+          
+          if (attrs.controller != undefined) {
+            ExtMVC.dispatch({controller: attrs.controller, action: attrs.action});
+          }          
+        }
+      }
+    });
+    
+    /**
+     * @property main
+     * @type Ext.Panel
+     * A container into which views are rendered
+     */
+    this.main = new Ext.TabPanel({
+      region: 'center',
+      border: false,
+      cls   : 'mainPanel',
+      activeTab: 0
+    });
+    
+    this.viewport = new Ext.Viewport({
+      layout: 'border',
+      items:  [{
+        xtype: 'box',
+        region: 'north',
+        height: 30
+      },this.menu, this.main
+      ]
+    });
+    
+    this.fireEvent('launched');
+    
+    ExtMVC.dispatch('home', 'index');
+    
+    Ext.get('loading').remove();  
+    Ext.get('loading-mask').fadeOut({remove:true});  
+  }
+});
+
+