paloma 1.2.6 → 2.0.0

data/.gitignore

@@ -2,6 +2,5 @@ Gemfile.lock
 *.gem
 /tmp/*
 /spec/tmp/
-/spec/sample_app/tmp/
-/spec/sample_app/log/
-/spec/sample_app/paloma_test
+/spec/test_app/tmp
+/spec/test_app/spec/tmp/*

data/Changelog.md

@@ -1,10 +1,6 @@
 Changelog
 =
 
-Version 1.2.6
--
-* Paloma hook script is not appended on the response when `false` is passed to `js_callback`
-
 Version 1.2.0
 -
 * AddGenerator with multiple actions: `rails g paloma:add namespace/controller action1 action2 action3`

data/README.md

@@ -1,21 +1,23 @@
 Paloma
 ======
-Paloma provides a sexy way to organize javascript files using Rails' asset pipeline. 
-It adds the capability to execute page-specific javascript code after rendering the controller's response.
+Paloma provides a sexy and logical way of organizing Rails javascript files.
+Its core feature is a powerful yet simple way to execute page-specific javascript code. 
+
+But there are more sexy features Paloma has to offer!
 
 Advantages
 -
 * Javascript files are organized per controller just like app/views folder of Rails.
 * Javascript file per controller's action.
-* The ability to choose what specific javascript code to run on a specific action.
+* Choose what specific javascript codes to run per page.
 * Easily make ruby variables available on your javascript files.
 
 Quick Example
 -
-The javascript callback file `app/assets/javascripts/paloma/users/new.js`:
+The javascript callback file `/assets/javascripts/paloma/users/new.js`:
 
 ```javascript
-Paloma.callbacks['users/new'] = function(params){
+Paloma.callbacks['users']['new'] = function(params){
     // This will only run after executing users/new action
     alert('Hello New Sexy User');
 };
@@ -28,6 +30,7 @@ def UsersController < ApplicationController
     def new
         @user = User.new
         # No special function to call, the javascript callback will be executed automatically
+        # just for this specific action.
     end
 end
 ```
@@ -64,27 +67,28 @@ Require `paloma` in your `application.js`:
 //= require paloma
 ```
 
-Directory Structure
+Basic Directory Structure
 -
 `paloma` folder contains the javascript callbacks.
 
 * paloma
-    * [controllers]
+    * [controller]
         * [action].js
         * [other_action].js
-    * [other_controllers]
+    * [other_controller]
         * [action].js
         * [other_action].js
         * [more_action].js
     * [namespace]
-        * [controllers]
+        * [controller]
             * [action].js
      
 Generators
 -
-1. Generate a controller folder containing its required files:   
+
+1. Generate a controller folder containing its required files: 
 ```
-rails g paloma:add [controllers]
+rails g paloma:add [controller]
 ```
     **Example:**
     ```
@@ -98,7 +102,7 @@ rails g paloma:add [controllers]
 
 2. Generate a callback file for a controller's action:
 ```
-rails g paloma:add [controllers] [action]
+rails g paloma:add [controller] [action]
 ```
     **Example:**
     ```
@@ -113,7 +117,7 @@ rails g paloma:add [controllers] [action]
 
 3. Generate multiple callback files:
 ```
-rails g paloma:add [controllers] [action_1] [action_2] ... [action_n]
+rails g paloma:add [controller] [action_1] [action_2] ... [action_n]
 ```
     **Example:**
     ```
@@ -130,7 +134,7 @@ rails g paloma:add [controllers] [action_1] [action_2] ... [action_n]
 
 4. Generate namespaced controller and callbacks:
 ```
-rails g paloma:add [namespace]/[controllers] [action_1] [action_2] ... [action_n]
+rails g paloma:add [namespace]/[controller] [action_1] [action_2] ... [action_n]
 ```
 
     **Example:**
@@ -144,17 +148,19 @@ rails g paloma:add [namespace]/[controllers] [action_1] [action_2] ... [action_n
             * /users
                 * new.js
                 
-**Note:** You can directly run `rails g paloma:add [controllers] [action]` or `rails g paloma:add [namespace]/[controllers] [action]` even the controller folder is not yet 
+**Notes:** 
+
+* You can directly run `rails g paloma:add [controller] [action]` or `rails g paloma:add [namespace]/[controller] [action]` even the controller folder is not yet 
 existing on `paloma` folder. It will be created automatically.
 
+* Controller folder and action javascript files will automatically be created after running `rails g controller` or `rails g scaffold`.
 
 Advanced Callbacks
 -
-By default Paloma will execute the callback that matches the response's current controller and action if it finds one.
-For instance if the current response is from the `new` action of the `Users` controller, then Paloma will execute the callback
-named `users/new`.
+By default Paloma will execute the callback that matches the current controller and action if it finds one.
+For instance, if the current response is from the `new` action of the `Users` controller, then Paloma will try to execute `callbacks['users']['new']` if it exists.
 
-You can manipulate callback behavior by using the `js_callback` command before the `render` or `redirect_to` command in your controllers.
+You can manipulate callback behavior by using the `js` command before the `render` or `redirect_to` command in your controllers.
 
 1. Preventing the Callback to execute.
 
@@ -163,33 +169,33 @@ You can manipulate callback behavior by using the `js_callback` command before t
         user = User.find params[:id]
         user.destroy
         
-        js_callback false
+        js false
     end
     ```
     
-    `[controllers]/destroy` callback will not be executed.
+    `callbacks["controller"]["destroy"]` will not be executed.
 
 2. Using other action's callback from the same controller.
 
     ```ruby
     def edit
         @user = User.find params[:id]
-        js_callback :new
+        js :new
     end
     ```
 
-    This will execute `[controllers]/new` callback instead of `[controllers]/edit`.
+    This will execute `callback["controllers"]["new"]` instead of `callback["controllers"]["edit"]`.
     
 3. Using other action's callback from other controller.
 
     ```ruby
     def index
         @users = User.all
-        js_callback :controller => 'clients', :action => 'index'
+        js :controller => 'clients', :action => 'index'
     end
     ```
 
-    This will execute `clients/index` callback instead of `[controllers]/index`.
+    This will execute `callbacks["clients"]["index"]` instead of `callbacks["controllers"]["index"]`.
 
 
 4. Using other action's callback from a namespaced controller.
@@ -200,17 +206,17 @@ You can manipulate callback behavior by using the `js_callback` command before t
             @user = User.find params[:id]
             @user.destroy
             
-            js_callback :controller => 'admin/users', :action => :destroy
+            js :controller => 'admin/users', :action => :destroy
         end
     end
     ```
 
-    This will execute `admin/users/destroy` callback instead of `users/destroy`.
+    This will execute `callbacks["admin/users"]["destroy"]` instead of `callbacks["users"]["destroy"]`.
 
 
 Passing Parameters
 -
-You can also pass parameters to the callback by passing a `:params` key to `js_callback`. The passed parameters
+You can also pass parameters to the callback by passing a `:params` key to `js`. The passed parameters
 will be available on the callback by the `params` object.
 
 **Example:**
@@ -221,69 +227,202 @@ def destroy
     user = User.find params[:id]
     user.destroy
     
-    js_callback :params => {:user_id => params[:id]}
+    js :params => {:user_id => params[:id]}
 end
 ```
 
 `/paloma/users/destroy.js`
 ```javascript
-Paloma.callbacks['users/destroy'] = function(params){
+Paloma.callbacks['users']['destroy'] = function(params){
     var id = params['user_id'];
     alert('User ' + id + ' deleted.');
 };
 ```
 
-Callback Helpers
--
-Callback helpers are inside Paloma objects in order to prevent conflicts from different functions and variables.
+## Filters
+
+This is almost similar to Rails controller filters. These are functions executed either `before`, `after`, 
+or even `around` (before and after) a Paloma callback is executed.
+
+Filters are defined on `_filters.js` files in Paloma's root folder, namespace folder, or controller folder.
+
+### Syntax
+
+```javascript
+filter.as('filter name').before_all().perform(function(params){
+    alert("I'm a before filter!");
+});
+
+filter.as('another filter').after_all().perform(function(params{
+   alert("I'm an after filter"); 
+});
+```
 
-1. Global
+### Specify Actions To Filter
 
-    Helper functions and variables can be defined in `paloma/paloma.js` inside the `Paloma.g` object.
+1. For all actions.
     
-    **Example:**
     ```javascript
-    Paloma.g = {
-        helper: function(){
-            // do something sexy
-        },
-        
-        helper_variable: 1000
-    };
+    filter.as('name').before_all()
+    filter.as('name').after_all()
+    filter.as('name').around_all()
     ```
 
-3. Namespace's Scope
-
-    Helper functions and variables that is shared inside a namespace can be defined in `paloma/[namespace]/_local.js` inside
-    the `Paloma.[namespace]` object.
+2. Only for specific action/s.
     
-    **Example:**
     ```javascript
-    Paloma.admin = {
-        namespaced_helper: function(){
-            // do something sexy
-        },
-        
-        helper_variable: 1
-    };
+    filter.as('name').before('new', 'edit', 'update')
+    filter.as('name').after('destroy')
+    filter.as('name').around('show')
     ```
 
-2. Controller's Scope
-
-    Helper functions that you will only use for a certain controller can be defined in `paloma/[controllers]/_local.js` inside
-    the `Paloma.[controllers]` object.
+3. Except for specific action/s.
     
-    **Example:**
     ```javascript
-    Paloma.users = {
-        local_helper: function(){
-            // do something sexy
-        },
-        
-        helper_variable: 1
-    };
+    filter.as('name').except_before('new')
+    filter.as('name').except_after('destroy', 'edit')
+    filter.as('name').except_around('show')
     ```
+
+### Filter Inheritance
+
+All `_filters.js` inherit filters defined on the global `_filters.js` file. 
+Controller's `_filters.js` will also inherit filters defined on its namespace `_filters.js` if it exists.
+
+
+### Execution Time
+
+Global filters (on `/paloma/_filters.js`) are executed first, then Namespace filters if any, 
+then Controller filters.
+
+Before filters, as you've guessed, are executed before the callback is called. 
+The order of execution is based on the order of declaration.
+After before filters, around filters are executed then the callback is finally executed.
+After filters are called after the callback is executed, then it will execute the around filters again.
+
+### Shared Variable Between Filter and Callback
+
+Automatically, filters has an access to the `params` object passed via the `js` ruby method. 
+But you can also make a variable visible both on a filter and a callback using the `_x` object.
+
+**Example:**
+
+on `_filters.js`:
+    
+```javascript
+filter.as('filter name').before('new').perform(function(params){
+    _x.sharedVariable = "Sexy Paloma";
+});
+```
+    
+on `new.js`:
+
+```javascript
+Paloma.callbacks['controller']['new'] = function(params){
+    alert(_x.sharedVariable);   // outputs "Sexy Paloma";
+});
+```
+
+##Locals
+
+Locals are variables or methods which can be made locally available within a controller or a namespace. Locals can also be made available throughout the whole Paloma files (globally).
+
+The motivation of Locals is to organize helper methods and helper variables within a namespace or controller.
+
+1. **Application-wide Locals**
+
+    Defined on `paloma/_locals.js`.
+    This contains methods and variables that are intended to be available globally.
+
+
+2. **Namespace-wide Locals**
+
+    Defiend on `paloma/namespace/_locals.js`.
+    This contains methods and variables that are intended to be available on the specific namespace only.
+
+
+3. **Controller-wide Locals**
+
+    Defined on `paloma/controller/_locals.js` or `paloma/namespace/controller/_locals.js`.
+    This contains methods and variables that are intended to be available on the specific controller only.
+    
+
+###Creating Locals
+Locals can be created using the `locals` object inside `_filters.js` file.
+
+**Example:**
+
+```javascript
+locals.helperMethod = function(){
+  return "Hello World";
+};
+
+locals.helperVariable = "WOW!";
+```
+
+###Accessing Locals
+Locals can be accessed in your filter and callback files using the `_l` object.
+
+**Example**
+
+```javascript
+Paloma.callbacks['users']['new'] = function(params){
+    alert("Hello Sexy User");
     
+    _l.helperMethod();
+
+    console.log(_l.helperVariable);
+};
+```
+
+###Accessing Locals From Other Controller/Namespace
+Sometimes there is a need to use other's local methods and variables. 
+You can achieve this by using the `Paloma.locals` object or its alias `_L`.
+
+**Example**
+```javascript
+Paloma.callbacks['users']['new'] = function(params){
+  _L.otherController.helperMethod();  // accessing local helperMethod() of the otherController
+  _L['otherController'].helperVariable;
+}
+```
+
+
+###Locals Inheritance
+`_locals.js` inherits locals from its parent `_locals.js`, either from namespace or application-wide.
+You can also override locals inherited from parents.
+
+**Example**
+
+`paloma/_locals.js` contains:
+```javascript
+locals.globalMethod = function(){ console.log("I'm from Global"); }
+```
+
+`paloma/namespace/_locals.js` contains:
+```javascript
+locals.namespaceMethod = function(){ console.log("I'm from Namespace"); }
+locals.anotherNamespaceMethod = function(){ console.log("I'm also from Namespace"); }
+```
+
+`paloma/namespace/controller/_locals.js` contains:
+```javascript
+locals.controllerMethod = function(){ console.log("I'm from Controller"); }
+locals.anotherNamespacedMethod = function(){ console.log("Override!"); }; // Overrides namespace local
+```
+
+Since `controller` is under the global `_local.js` and namespace `_local.js` it automatically inherits all their locals.
+So you can do something like this inside the controller callback files (or filter files):
+
+```javascript
+Paloma.callbacks['namespace/controller']['action'] = function(params){
+    _l.controllerMethod();          // outputs "I'm from Controller"
+    _l.namespacedMethod();          // outputs "I'm from Namespace"
+    _l.globalMethod();              // outputs "I'm from Global"
+    _l.anotherNamespacedMethod();   // outputs "Override!"
+};
+```
+
 Callback Chains
 -
 Callback chains are created after a redirect action. The chain will continue to increase its length until a render action is detected.

data/app/templates/_filters.js

@@ -0,0 +1,14 @@
+(function(){ 
+  // Initializes the main container for all filters and skippers for this
+  // specific scope.
+  var filter = new Paloma.FilterScope(':scope');
+  
+  // The _x object is also available on callbacks.
+  // You can make a variable visible on callbacks by using _x here.
+  //
+  // Example:
+  // _x.visibleOnCallback = "I'm a shared variable"
+  var _x = Paloma.variableContainer;
+
+  // ~> Start definitions here and remove this line.
+})();