ninjs 0.9.1 → 0.9.2

data/README.textile

@@ -97,7 +97,7 @@ We can see what this module does by simply glancing at the actions method. From
 
 h2. Create module elements
 
-Another common best practice that Ninjs encourages is cacheing your element selectors. For example, when using jQuery to select a DOM element, it's best practice to assign the result of the selection to a variable incase you need it again. Here's what it looks like in practice:
+Another common best practice that Ninjs encourages is cacheing your element selectors. For example, when using jQuery to select a DOM element, it's best practice to assign the result of the selection to a variable in case you need it again. Here's what it looks like in practice:
 
 <pre name="code" class="brush: js;">
 	// Bad no-caching
@@ -112,7 +112,7 @@ Another common best practice that Ninjs encourages is cacheing your element sele
 
 When we cache our selections, we only have to search the DOM once, improving performance.
 
-The only problem with this is that we tend to manipulate a lot of selections and our code can become littered with them. At worst, they're strewn about the file where ever they are first used, making it easy to "re-cache" them. At best all our selections are cached in one pace and easy to see to prevent us from accidentally caching them twice. Ninjs goes a step further by separating these cached selectors to their own file in the elements folder.
+The only problem with this is that we tend to manipulate a lot of selections and our code can become littered with them. At worst, they're strewn about the file wherever they are first used, making it easy to accidentally "re-cache" them. At best, all selections are cached in one place and easy to see, which prevents us from accidentally caching them twice. Ninjs goes a step further by putting these cached selectors in their own file in the elements folder.
 
 Elements belong to a module and can be added using the elements method. To add elements to the hello module, let's add a hello.elements.js file in the elements folder. Next add the elements to the module with the elements method:
 
@@ -129,26 +129,7 @@ And that's it for the elements code. We've added a cached element with the id of
 	
 	//= require '../elements/hello.elements.js'
 	
-	MyApplication.hello.actions = function() {
-		this.define_properties();
-		this.say_hello();
-	};
-	
-	MyApplication.hello.define_properties() = function() {
-		this.greeting = 'Hello';
-		this.name = 'World';
-	}
-	
-	MyApplication.hello.say_hello = function() {
-		var message = this.greeting_string();
-		alert(message);
-	};
-	
-	MyApplication.hello.greeting_string = function() {
-		return this.greeting + ' ' + this.name + '!';
-	};
-	
-	MyApplication.hello.run();
+	...
 </pre>
 
 Be sure to require the elements file after the "add_module" method is called. Now all elements defined in the elements method will be available to the module. Let's take our hello example and instead of alerting the greeting, let's put it in the message_box element (assuming an html page with this element):
@@ -164,8 +145,88 @@ Be sure to require the elements file after the "add_module" method is called. No
 	...
 </pre>
 
-Again, this pattern keeps the logic very clear and our code very concise. It's easy to read, test, and refactor. Be careful when naming your cached elements, be sure you're not overwriting another property. With time you'll develop your own naming conventions and standards. The important thing is to focus on good semantic names that accurately describe the properties and behavior of your application.
+Again, this pattern keeps the logic very clear and our code very concise. It's easy to read, test, and refactor. Be careful when naming your cached elements, be sure you're not overwriting another property of the module. With time you'll develop your own naming conventions and standards. The important thing is to focus on good semantic names that accurately describe the properties and behavior of your application.
+
+Most modules will be exactly like the one we just created, only with more methods. However, there is one more piece that helps you achieve greater modularity, which is Ninjs models.
+
+h2. Create a Ninjs model
+
+Ninjs models are simply files in the models directory that define a data structure. By convention models are simply object literals that are usefull for reusing inside your modules and throughout your application. There is no one way to create or use a model but I'll describe the common use case.
 
-Most modules will be exactly like the one we just created, with more methods. However, there is one more piece that helps you achieve greater modularity, which is Ninjs models.
+Let's suppose I have multiple "jQueryUI dialog windows":http://jqueryui.com/demos/dialog/ that I want to share a certain default configuration. Instead of creating an options object each time I call dialog on an element, I can use a model.  Let's see how this might look in our hello example. Let's create the model in /models/hello.model.js:
+
+<pre name="code" class="brush: js;">
+	MyApplication.hello.dialog_settings = {
+		width: 300,
+		height: 150,
+		autoOpen: false
+	}
+</pre>
+
+Next we include the model in the module:
+
+<pre name="code" class="brush: js;">
+	MyApplication.add_module('hello');
+	
+	//= require '../elements/hello.model.js'
+	//= require '../elements/hello.elements.js'
+	
+	...
+</pre>
+
+Now whenever I create a dialog in my module, I can use the MyApplication.hello.dialog_settings object:
+
+<pre name="code" class="brush: js;">
+	// assumes we have elements "error_dialog" and "notice_dialog"
+	// defined in the elements file
+	
+	MyApplciation.hello.create_dialogs = function() {
+		this.error_dialog.dialog(this.dialog_settings);
+		this.notice_dialog.dialog(this.dialog_settings);
+	}
+</pre>
+
+This way we don't have to keep redefining the same properties each time we call dialog. If we want to modify the defaults, we can use jquery's merge method
+
+<pre name="code" class="brush: js;">
+	// assumes we have elements "error_dialog" and "notice_dialog"
+	// defined in the elements file
+	
+	MyApplciation.hello.create_dialogs = function() {
+		this.error_dialog.dialog(this.dialog_settings);
+		this.notice_dialog.dialog($.extend(MyApplication.hello.dialog_settings, {
+			height: 300,
+			autoOpen: true
+		}));
+	}
+</pre>
+
+The model provides a default base that we can build from, helping use to keep our code DRY. There's also an opportunithy here to illustrate the utility of the "ninja" aliases. Notice that inside the dialog function we are unable to use the this.dialog_settings shorthand. This is because this is refering to the dialog and not the module. That's why Ninjs defines the double underscore variable to refer to the current module. The previous example can be rewritten more succinclty like so:
+
+<pre name="code" class="brush: js;">
+	MyApplciation.hello.create_dialogs = function() {
+		this.error_dialog.dialog(this.dialog_settings);
+		this.notice_dialog.dialog($.extend(__.dialog_settings, {
+			height: 300,
+			autoOpen: true
+		}));
+	}
+</pre>
+
+Using "this" in Javascript can be a bit tricky so if your not sure what "this" refers to in any given context, your safe using the "_" (application alias) and "__" (module alias) aliases in Ninjs.
+
+h1. Compiling our application
+
+Now that we have a complete module including elements and a model, we need to compile these files into one coherent file to use in our html.  To do so we have 2 options.  Open a terminal window (command prompt) and navigate to the root of your Ninjs application. We can compile our application with one of 2 commands. The first choice is the compile command. From the root of your Ninjs application type:
+
+<pre name="code" class="brush: bash;">
+	$ ninjs compile
+</pre>
+
+This will compile all the files in the modules folder, resolving all dependencies using the Sprockets engine, and finally outputting them into the application directory with the .module suffix removed.  Our hello example module would compile into the application folder as hello.js. Now we can include the hello.js file (along with the myapplication.js) in our html document. Since running compile every time we make a change to any one of our module source files would quickly become a tedious chore, Ninjs also provides a watch command which will watch your root directory for changes and automatically compile when a file is changed. This speeds up development considerably and frankly makes Ninjs usable in a daily development context. To watch a Ninjs project simply navigate to the project root and issue the watch command:
+
+<pre name="code" class="brush: bash;">
+	$ ninjs watch
+</pre>
 
-h2. Create a Ninjs model
+That's the basics of creating a Ninjs application!

data/lib/ninjs.rb

@@ -0,0 +1,35 @@
+module Ninjs
+end
+
+module Ninjs
+  def version
+    '0.9.4'
+  end
+  
+  def base_directory
+    File.expand_path(File.join(File.dirname(__FILE__), '..'))
+  end
+  
+  def lib_directory
+    File.expand_path(File.join(File.dirname(__FILE__)))
+  end
+  
+  def root_directory
+    Dir.getwd
+  end
+  
+  def repository_root
+    base_directory + '/repository/'
+  end
+  
+  module_function :version,
+                  :base_directory,
+                  :lib_directory,
+                  :root_directory,
+                  :repository_root
+end
+
+
+%w(dependencies configuration helpers manifest project command).each do |lib|
+  require "#{Ninjs.lib_directory}/ninjs/#{lib}"
+end

data/lib/ninjs/command.rb

@@ -0,0 +1,146 @@
+module Ninjs
+  module Command
+    def watch
+      require "fssm"
+      project_path = Dir.getwd << '/'
+      raise "ninjs.conf was not located in #{project_path}" unless File.exists? "#{project_path}ninjs.conf"
+      color_start = "\e[33m"
+      color_end = "\e[0m"
+      puts "\e[32m>>>#{color_end} Ninjs are watching for changes. Press Ctrl-C to stop."
+      project = Ninjs::Project.init_with_config(project_path)
+      project.update
+	  
+      FSSM.monitor do
+        path "#{project_path}elements" do
+          glob "**/*.js"
+
+          update do |base, relative|
+            puts "#{color_start}<<<#{color_end} change detected in #{relative}"
+            project.update
+          end
+
+          create do |base, relative|
+            puts "#{relative} created"
+            project.update
+          end
+        end
+        
+        path "#{project_path}models" do
+          glob "**/*.js"
+
+          update do |base, relative|
+            puts "#{@color_start}<<<#{@color_end} change detected in #{relative}"
+            project.update
+          end
+
+          create do |base, relative|
+            puts "#{relative} created"
+            project.update
+          end
+        end
+        
+        path "#{project_path}modules" do
+          glob "**/*.js"
+
+          update do |base, relative|
+            puts "#{color_start}<<<#{color_end} change detected in #{relative}"
+            project.update
+          end
+
+          create do |base, relative|
+            puts "#{relative} created"
+            project.update
+          end
+        end
+
+        path "#{project_path}lib" do
+          glob "**/*.js"
+
+          update do |base, relative|
+            puts "#{color_start}<<<#{color_end} change detected in #{relative}"
+            project.config.read
+            project.update_application_file
+            project.update
+          end
+
+          create do |base, relative|
+            puts "+++ created #{relative}"
+            project.update
+          end
+        end
+        
+        path "#{project_path}plugins" do
+          glob "**/*.js"
+
+          update do |base, relative|
+            puts "#{color_start}<<<#{color_end} change detected in #{relative}"
+            project.config.read
+            project.update_application_file
+            project.update
+          end
+
+          create do |base, relative|
+            puts "+++ created #{relative}"
+            project.update
+          end
+        end
+        
+        path "#{project_path}" do
+          glob "**/*.conf"
+          
+          update do |base, relative|
+            puts "#{color_start}<<<#{color_end} change detected in #{relative}"
+            project.config.read
+            project.update_application_file
+            project.update
+          end
+        end
+        
+      end
+      
+    end
+
+    def create(name, directory = false)
+      raise 'you must specify a project name: ninjs create ProjectName' if name.nil?
+      project = directory ? Ninjs::Project.new(name, directory) : Ninjs::Project.new(name)
+      project.create
+    end
+    
+    def compile
+      project_path = Dir.getwd << '/'
+      raise "ninjs.conf was not located in #{project_path}" unless File.exists? "#{project_path}/ninjs.conf"
+      project = Ninjs::Project.init_with_config(project_path)
+      project.update
+    end
+    
+    def import(package)
+      Ninjs::PackageManager.import(package)
+    end
+
+    def help
+      puts <<-DOC
+      
+Description: 
+The ninjs command line tool will compile your ninjs application into modules.
+To compile your ninjs application into module files:
+
+Usage: ninjs [action] [options]
+  
+Actions:
+  compile  Compiles the ninjs project in the current working directory
+  watch    Watches the current working directory for 
+           file changes and compiles when files change
+  create   Generates ninjs application architecture and files  
+           Options:
+             -p, --directory  Optional install directory for a new ninjs project
+                              (creates the folder if it does not exist)
+  
+Example:
+  ninjs create MyApplication
+  ninjs watch
+      DOC
+    end
+
+    module_function :create, :watch, :compile, :help, :import
+  end
+end

data/lib/ninjs/configuration.rb

@@ -0,0 +1,84 @@
+module Ninjs
+    class Configuration
+      
+      attr_reader :name,
+                  :project_path,
+                  :app_filename,
+                  :directory,
+                  :output,
+                  :dependencies,
+                  :autoload,
+                  :config_path,
+                  :asset_root
+                  
+      def initialize(project_path, name = 'NinjsApplication')
+        @defaults = {
+          :name => name,
+          :project_path => project_path,
+          :asset_root => project_path,
+          :output => 'expanded',
+          :dependencies => ['<jquery/latest>'],
+          :autoload => ['<ninjs/utilities/all>']
+        }
+
+        @defaults.each do |label, setting|
+          instance_variable_set("@#{label}", setting)
+        end
+      end
+      
+      def create
+        default_content = conf_content @defaults
+        create_conf_file default_content
+      end
+      
+      def conf_content(options)
+        content = <<-CONF
+name: #{options[:name]}
+project_path: #{options[:project_path]}
+asset_root: #{options[:project_path]}
+output: #{options[:output]}
+dependencies: [#{options[:dependencies].join(', ')}]
+autoload: [#{options[:autoload].join(', ')}]
+        CONF
+      end
+      
+      def create_conf_file(content)
+        File.open("#{@project_path}ninjs.conf", "w+") do |conf_file|
+          conf_file << conf_content(@defaults)
+        end
+        
+        puts "ninjs.conf created"
+      end
+      
+      def update
+        content = conf_content({
+          :name => @name,
+          :project_path => @project_path,
+          :asset_root => @project_path,
+          :output => @output,
+          :dependencies => @dependencies,
+          :autoload => @autoload
+        })
+        create_conf_file content
+      end
+      
+      def read
+        begin
+          raise IOError, "#{@project_path}ninjs.conf does not exist", caller unless File.exists? "#{@project_path}ninjs.conf"
+          config = YAML.load_file("#{@project_path}ninjs.conf")
+          
+          @project_path = config['project_path']
+          @asset_root = config['asset_root']
+          @name = config['name']
+          @app_filename = config['name'].downcase
+          @output = config['output']
+          @dependencies = config['dependencies'] || Array.new
+          @autoload = config['autoload'] || Array.new
+        rescue IOError => e
+          puts e.message
+          puts e.backtrace.inspect
+        end
+      end
+      
+    end
+end

data/lib/ninjs/dependencies.rb

@@ -0,0 +1,16 @@
+begin
+  require 'yaml'
+  require 'jsmin'
+  require 'tempfile'
+  require 'sprockets'
+  require 'ftools'
+  require 'time'
+rescue LoadError
+  require 'rubygems'
+  require 'yaml'
+  require 'jsmin'
+  require 'tempfile'
+  require 'sprockets'
+  require 'ftools'
+  require 'time'
+end

data/lib/ninjs/helpers.rb

@@ -0,0 +1,16 @@
+module Ninjs
+  module Helpers
+    
+    def create_module_filename(module_name)
+      split = module_name.split(/[\.\-\s]/)
+      module_filename = String.new
+      split.each do |piece|
+        module_filename << piece unless piece.match(/^module$|^js$/i)
+      end
+      module_filename
+    end
+    
+    module_function :create_module_filename
+    
+  end
+end

data/lib/ninjs/manifest.rb

@@ -0,0 +1,9 @@
+module Ninjs
+  module Manifest
+    def directories
+      %w(application elements lib models modules plugins tests)
+    end
+    
+    module_function :directories
+  end
+end