paloma 3.0.2 → 4.0.0

data/Changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Version 4.0.0
+* https://github.com/kbparagua/paloma/issues/26 - Paloma requests are not saved on `session`.
+* https://github.com/kbparagua/paloma/issues/26 - Chaining with redirect is removed.
+* Routing from javascript is removed.
+* Routing from Rails controller is added.
+* Ability to have a controller-wide setting.
+* https://github.com/kbparagua/paloma/issues/29 - Disable `console.log` and `console.warn` for non-development environments.
+
 
 ## Version 3.0.2
 * Bug Fix: Converting Rails controller name to singular form.

data/README.md

@@ -1,18 +1,24 @@
 # Paloma
 
-**This README is for Paloma 3 only. 
-For version 2 README please go [here](https://github.com/kbparagua/paloma/blob/2.0/README.md).**
+**This README is for Paloma 4 only.**
 
+**For version 3 README please go [here](https://github.com/kbparagua/paloma/blob/3.0/README.md).**
 
-## What's New?
-Paloma 3 is almost a complete rewrite of the old version.
+**For version 2 README please go [here](https://github.com/kbparagua/paloma/blob/2.0/README.md).**
 
-It is now simpler and more flexible. The old callback thingy paradigm is replaced by a `Router` and `Controller` layer for better abstraction. Generators are also removed, so programmers need not to follow specific directory structure, unlike in the old versions.
+
+## Paloma 4, why so sudden?
+The last major version (v3) of Paloma introduced a major paradigm shift, and it took me a while to realize that some of the major changes introduced are not really that good and needed to be removed.
+
+
+## What's new?
+*(compared to version 2)*
+It is now simpler and more flexible. The old callback thingy paradigm is replaced by a `Controller` layer for better abstraction. Generators are also removed, so programmers need not to follow specific directory structure, unlike in the old versions.
 
 Previously, there are generators that create Paloma files, and these files are written in vanilla javascript. Because of that there are some users who are requesting for coffeescript setup. Now since there are no generated files programmers can write their code either by using vanilla javascript or **coffeescript**. Yay!
 
-### Controller and Router
-The new paradigm is patterned after Rails Controller and Routes, so it is easier to grasp than the old callback paradigm. Basically, you have a Paloma Controller that is responsible for processing requests made from Rails Controller. While the Router is responsible for telling what Paloma Controller handles what Rails Controller, or what Paloma Controller's action handles what Rails Controller's action. 
+### Controller
+The new paradigm is patterned after Rails Controller, so it is easier to grasp than the old callback paradigm. Basically, you have a Paloma Controller counterpart for every Rails Controller.
 
 
 ### How about Model and View?
@@ -70,7 +76,7 @@ Controllers are just classes that handle requests made by Rails Controllers. Eac
 
 ### Creating a Controller
 
-A Controller constructor is created or accessed, if it already exists, using `Paloma.controller()` method.
+A Controller constructor is created or accessed (if it already exists), using `Paloma.controller()` method.
 
 ```javascript
 var ArticlesController = Paloma.controller('Articles');
@@ -78,10 +84,12 @@ var ArticlesController = Paloma.controller('Articles');
 
 It will return the constructor function of your controller.
 
+Note: Using `Paloma.controller` method, you can access the same controller constructor across different files.
+
 
 ### Handling Actions
 
-Every time a request to Paloma is made (A Rails Controller action is executed), an instance of a Paloma controller is created and a method responsible for the request will be invoked.
+Every time a request to Paloma is made (A Rails Controller action is executed), an instance of a Paloma controller is created and the method responsible for the request will be invoked.
  
 ```javascript
 var ArticlesController = Paloma.controller('Articles');
@@ -95,32 +103,107 @@ ArticlesController.prototype.edit = function(){
 };
 ```
 
-## Passing Parameters
 
-You can also pass parameters to a Paloma Controller by calling `js` **before** render in your Rails controller. You can access the parameters on your Paloma Controller using `this.params` object.
+## Advanced Usage
 
-**Example:**
+You can manipulate what controller/action should Paloma execute by calling `js` method **before** rendering.
 
-`users_controller.rb`
-```ruby
-def destroy
-    user = User.find params[:id]
-    user.destroy
-    
-    js :id => user.id
-end
-```
+1. Changing controller
 
-Paloma controller.
+   ```ruby
+   class UsersController < ApplicationController
+      def new
+         @user = User.new
+         js 'Accounts' # will use Accounts controller instead of Users controller
+      end
+   end
+   ```
 
-```javascript
-var UsersController = Paloma.controller('Users');
+2. Changing action
 
-UsersController.prototype.destroy = function(){
-  alert('User ' + this.params['id'] + ' is deleted.');
-};
-```
+   You can use the symbol syntax:
+   ```ruby
+   def new
+      @user = User.new
+      js :register # will execute register method instead of new
+   end
+   ```
+   
+   Or the string syntax:
+   ```ruby
+   def new
+      @user = User.new
+      js '#register'
+   end
+   ```
+
+3. Changing controller and action.
+
+   ```ruby
+   def new
+     @user = User.new
+     js 'Accounts#register' # will execute Accounts#register instead of Users#new
+   end
+   ```
+
+4. Changing controller with namespace.
+
+   Paloma supports namespaces using '/' as delimiter.
+
+   ```ruby
+   def new
+      @user = User.new
+      js `Admin/Accounts` # will use Admin/Accounts controller instead of Users controller
+   end
+   ```
+   
+   ```ruby
+   def new
+      @user = User.new
+      js 'Admin/Accounts#register' # will execute Admin/Accounts#register instead of Users#new
+   end
+   ```
+   
 
+## Passing Parameters
+
+You can access the parameters on your Paloma Controller using `this.params` object.
+
+
+1. Parameters only.
+ 
+   `users_controller.rb`
+   ```ruby
+   def destroy
+       user = User.find params[:id]
+       user.destroy
+       
+       js :id => user.id
+   end
+   ```
+
+   Paloma controller.
+
+   ```javascript
+   var UsersController = Paloma.controller('Users');
+   
+   UsersController.prototype.destroy = function(){
+     alert('User ' + this.params['id'] + ' is deleted.');
+   };
+   ```
+
+2. Path with parameters.
+
+   ```ruby
+   def destroy
+      user = User.find params[:id]
+      user.destroy
+      
+      js 'Accounts#delete', :id => user.id
+   end
+   ```
+   
+   
 ## Preventing Paloma Execution
 
 If you want to Paloma not to execute in a specific Rails Controller action you need to pass `false` as the Paloma parameter.
@@ -132,60 +215,65 @@ def edit
 end
 ```
 
-## Execution Chains
 
-A Paloma request is created every time a Rails Controller action is executed. All requests will be recorded until a render action is triggered, and all Paloma requests will be processed following FIFO (First In, First Out) method.
+## Controller-wide setup
+
+You can call `js` outside Rails controller actions for global or controller-wide settings.
+
 
 **Example:**
 
 ```ruby
-def first_action
-    # Paloma request will be created
-    redirect_to second_action_path
-end
+class UsersController < ApplicationController
+   js 'Accounts' # use Accounts controller instead of Users for all actions.
 
-def second_action
-    # Paloma request will be created
-    redirect_to third_action_path
-end
 
-def third_action
-    # Paloma request will be created
-    render :template => 'third_action_view'
+   def new
+      @user = User.new
+   end
+   
+   def show
+      @user = User.find params[:id]
+   end
 end
 ```
 
-When the `third_action` renders its response, Paloma will process all the request starting from `first_action` up to `third_action`. So, Paloma Controller actions responsible for those 3 Rails actions will be executed.
-
-## Router
+Like `before_filter` you can also pass `only` and `except` options.
 
-Router is responsible for mapping Rails Controller/action to its equivalent Paloma Controller/action.
 
-By default all Rails Controller will be mapped with a Paloma Controller with the same resource name (controller name without the `Controller` suffix).
+```ruby
+class UsersController < ApplicationController
 
-Example:
-* Requests from `UsersController#new` will be mapped to Paloma Controller named `Users` with its `new` method.
+   js 'Admin/Accounts', :except => :destroy # Use Admin/Accounts except for destroy method
 
-If you have no problem with the default behavior, you don't need to write Router stuff in your code.
+end
+```
 
-### Changing Controller
 
-If you want to use a different Paloma Controller for a specific Rails Controller, you can do the following:
+**IMPORTANT NOTE:**
+If you are going to pass parameters for Controller-wide settings, put them inside a `:params` hash.
 
-```javascript
-// Instead of mapping Rails UsersController to Paloma Users Controller
-// it will be mapped to AdminUsers.
-Paloma.router.resource('Users', {controller: 'AdminUsers'});
+```ruby
+class UsersController < ApplicationController
+  js 'Accounts', :params => {:x => 1, :y => 2, :z => 3}, :only => :show
+end
 ```
 
-### Redirecting
+### Overriding Controller-wide setup
 
-You can also redirect an action if you want it to be handled by a different method.
+If you want to override the controller-wide setup, just call `js` again inside a controller action. From there you can override the controller/action or pass additional parameters.
 
-```javascript
-// Instead of executing Paloma's `Users#new` it will execute
-// `Registrations#signUp`.
-Paloma.router.redirect('Users#new', {to: 'Registrations#signUp');
+```ruby
+class UsersController < ApplicationController
+
+   js 'Accounts', :params => {:x => 1}
+   
+   
+   def new
+      @user = User.new
+      js :register, :y => 2 # will execute Accounts#register with params {:x => 1, :y => 2}
+   end
+end
 ```
 
 ## Gotchas
@@ -198,6 +286,6 @@ For example: `render "something.js.erb"`
 ## Where to put code?
 
 Again, Paloma is now flexible and doesn't force developers to follow specific directory structure.
-You have the freedom to create controllers and routes anywhere in your application.
+You have the freedom to create controllers anywhere in your application.
 
-Personally, I prefer having a `routes.js` file to contain all the route declarations, and a javascript file for each controller.
+Personally, I prefer having a javascript file for each controller.

data/app/views/paloma/_hook.html.erb

@@ -10,21 +10,19 @@
         return true;
       }
 
+      Paloma.env = '<%= Rails.env %>';
+
       // Remove any callback details if any
       $('.js-paloma-hook[data-id!=' + <%= id %> + ']').remove();
 
-      var requests = <%= requests.to_json.html_safe %>;
-
-      for (var i = 0, len = requests.length; i < len; i++){
-        var request = requests[i];
-
-        Paloma.engine.request(request['resource'],
-                              request['action'],
-                              request['params']);
-      }
-
+      var request = <%= request.to_json.html_safe %>;
 
-      $(document).ready(function(){ Paloma.engine.start(); });
+      $(document).ready(function(){
+        Paloma.engine.request(
+          request['resource'],
+          request['action'],
+          request['params']);
+      });
 
     })();
   </script>

data/lib/paloma.rb

@@ -7,5 +7,7 @@ end
 # TODO: Rails version checking
 
 require 'action_controller/railtie'
+require 'paloma/controller'
+require 'paloma/utilities'
 require 'paloma/action_controller_extension'
 require 'paloma/rails/engine'

data/lib/paloma/action_controller_extension.rb

@@ -5,6 +5,8 @@ module Paloma
 
     def self.included base
       base.send :include, InstanceMethods
+      base.send :extend, ClassMethods
+
 
       base.module_eval do
         prepend_view_path "#{Paloma.root}/app/views/"
@@ -18,14 +20,78 @@ module Paloma
 
 
 
+    module ClassMethods
+
+      #
+      # Controller wide setting for Paloma.
+      #
+
+      def js path_or_options, options = {}
+        options ||= {}
+
+        scope = {}
+        scope[:only] = options[:only] if options[:only]
+        scope[:except] = options[:except] if options[:except]
+
+        self.before_filter(
+          Proc.new {
+            self.js path_or_options, options[:params]
+          },
+          scope)
+      end
+    end
+
+
+
+
+
     module InstanceMethods
 
       #
-      # Use on controllers to pass variables to Paloma controller.
       #
-      def js params = {}
-        return session[:paloma_requests].pop if !params
-        session[:paloma_requests].last[:params] = params
+      # Specify the behavior of Paloma. Call this manually to override the
+      # default Paloma controller/action to be executed.
+      #
+      # Can call a different Controller or execute a different action, and
+      # pass parameters.
+      #
+      # Usage:
+      #
+      #   js 'Controller', {params}
+      #   js 'Controller#action', {params}
+      #   js 'Namespace/Controller', {params}
+      #   js 'Namespace/Controller#action', {params}
+      #   js '#action', {params}
+      #   js :action, {params}
+      #   js :param_1 => 1, :param_2 => 2
+      #
+      #
+      def js path_or_options, params = {}
+        return self.paloma.clear_request if !path_or_options
+
+        self.paloma.params.merge! params || {}
+
+        #
+        # 'Controller'
+        # 'Controller#action'
+        # 'Namespace/Controller'
+        # 'Namespace/Controller#action'
+        # '#action'
+        #
+        if path_or_options.is_a? String
+          route = ::Paloma::Utilities.interpret_route path_or_options
+          self.paloma.resource = route[:resource] unless route[:resource].blank?
+          self.paloma.action = route[:action] unless route[:action].blank?
+
+        # :action
+        elsif path_or_options.is_a? Symbol
+          self.paloma.action = path_or_options
+
+        # :param_1 => 1, :param_2 => 2
+        elsif path_or_options.is_a? Hash
+          self.paloma.params.merge! path_or_options || {}
+
+        end
       end
 
 
@@ -35,13 +101,8 @@ module Paloma
       # Keeps track of what Rails controller/action is executed.
       #
       def track_paloma_request
-        resource = controller_path.split('/').map(&:titleize).join('/').gsub(' ', '')
-
-        paloma_request = {:resource => resource,
-                          :action => self.action_name}
-
-        session[:paloma_requests] ||= []
-        session[:paloma_requests].push paloma_request
+        self.paloma.resource ||= ::Paloma::Utilities.get_resource controller_path
+        self.paloma.action ||= self.action_name
       end
 
 
@@ -53,11 +114,11 @@ module Paloma
       # will execute the tracked Paloma requests.
       #
       def append_paloma_hook
-        return true if session[:paloma_requests].empty?
+        return true if self.paloma.has_no_request?
 
         hook = view_context.render(
                   :partial => 'paloma/hook',
-                  :locals => {:requests => session[:paloma_requests]})
+                  :locals => {:request => self.paloma.request})
 
         before_body_end_index = response_body[0].rindex('</body>')
 
@@ -72,7 +133,7 @@ module Paloma
           response.body += hook
         end
 
-        session[:paloma_requests] = nil
+        self.paloma.clear_request
       end
     end
 
@@ -88,11 +149,19 @@ module Paloma
     #
     def render options = nil, extra_options = {}, &block
       [:json, :js, :xml, :file].each do |format|
-        js false if options.has_key?(format)
+        self.paloma.clear_request if options.has_key?(format)
       end if options.is_a?(Hash)
 
       super
     end
+
+
+  protected
+
+    def paloma
+      @paloma ||= ::Paloma::Controller.new
+    end
+
   end