paloma 2.0.6 → 3.0.0

data/Changelog.md

@@ -1,76 +1,4 @@
-Changelog
-=
+# Changelog
 
-Version 2.0.6
--
-* Pull #15: Handling flash on redirect.
-
-Version 2.0.5
--
-* Bug Fix: Stupid typo on `_callback_hook.html.erb`.
-
-Version 2.0.4
--
-* Bug Fix: Issue #4 - Passing json string on params.
-
-Version 2.0.3
--
-* Bug Fix: prevent javascript error when callback doesn't exist.
-
-Version 2.0.2
--
-* 'js(false)' will prevent Paloma from appending _callback_hook on the response.
-
-Version 2.0.1
--
-* Bug Fix: `params` is not passed when calling filters.
-
-Version 2.0.0
--
-* Change `js_callback` to `js` only.
-* Request and Callback details are automatically included on `params` (example: controller, action, namespace, controller_path, etc...)
-* Hooks for Rails controller and scaffold generators.
-* Change `Paloma.callbacks['namespace/controller/action']` to `Paloma.callbacks['namespace/controller']['action']`.
-* `paloma.js` file removed.
-* `_callbacks.js` renamed to `_manifest.js`.
-* `_local.js` renamed to `_locals.js`.
-* Filters are now available (before_filter, after_filter, and around_filter).
-* Skip filters are now available (skip_before_filter, skip_after_filter, skip_around_filter).
-* Locals can now be easily accessible using the `_l` object.
-* Issue javascript warning instead of javascript error when Paloma is not included on `application.js`.
-* Codes are now inside closures, to prevent variable clashes.
-
-Version 1.2.0
--
-* AddGenerator with multiple actions: `rails g paloma:add namespace/controller action1 action2 action3`
-
-Version 1.1.0
--
-* Handle namespaced controllers: `rails g paloma:add namespace/controller action`
-
-Version 1.0.0
--
-* `AddGenerator` changed from `rails g paloma:add controller/action` to `rails g paloma:add controller action`
-
-Version 0.0.8
--
-* Bug Fix: _callback.js cannot find _local.js
-
-Version 0.0.7
--
-* Fix A Major Bug that copies the _local.js template instead of _callbacks.js
-
-Version 0.0.6
--
-* `SetupGenerator` moved from `paloma_generator.rb` to `paloma/generators/setup_generator.rb`
-* `AddGenerator` moved from `paloma_generator` to `paloma/generators/add_generator.rb`
-* Refactored both generators
-* Test for both generators
-
-Version 0.0.5
--
-* Callbacks are executed after the DOM is ready
-
-Version 0.0.4
--
-* First release
+## Version 3.0.0
+* Rewrite Initial Release

data/README.md

@@ -1,25 +1,30 @@
-Paloma
-======
-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. 
+# Paloma
 
-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.
-* Choose what specific javascript codes to run per page.
+## What's New?
+Paloma (version 3) is almost a complete rewrite of the old version.
+
+It is now simpler and it also gives more flexibility to the developers. Simplicity and flexibility are achieved by replacing the old callback thingy paradigm by a combination of `Router` and `Controller` components.
+
+All the generator shits are also gone. So developers need not to follow specific folder structure or file name. And since there's no generated files or whatsoever, you can now code in vanilla javascript or **coffescript**! Yay!
+
+**Basically, Paloma now provides a Controller for your javascript!**
+
+## Advantages
+* Choose what specific javascript code to run per page.
 * Easily make ruby variables available on your javascript files.
 
-Quick Example
--
-The javascript callback file `/assets/javascripts/paloma/users/new.js`:
+
+## Quick Example
+
+Paloma controller.
 
 ```javascript
-Paloma.callbacks['users']['new'] = function(params){
-    // This will only run after executing users/new action
-    alert('Hello New Sexy User');
+var UsersController = Paloma.controller('Users');
+
+// Executes when Rails User#new is rendered.
+UsersController.prototype.new = function(){
+   alert('Hello Sexy User!' );
 };
 ```
  
@@ -28,9 +33,7 @@ The Rails controller `app/controllers/users_controller.rb`:
 ```ruby
 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.
+      @user = User.new
     end
 end
 ```
@@ -43,8 +46,8 @@ Minimum Requirements
 * Rails 3.1 or higher
 
 
-Install
--
+## Install
+
 Without bundler:
 ```
 sudo gem install paloma
@@ -55,169 +58,77 @@ With bundler, add this to your Gemfile:
 gem 'paloma'
 ```
 
-Setup
--
-On setup, the `paloma` folder will be generated in `app/assets/javascripts/` containing its required files. Run:
-``` 
-rails g paloma:setup
-```
 
 Require `paloma` in your `application.js`:
 ```
 //= require paloma
 ```
 
-Basic Directory Structure
--
-`paloma` folder contains the javascript callbacks.
-
-* paloma
-    * [controller]
-        * [action].js
-        * [other_action].js
-    * [other_controller]
-        * [action].js
-        * [other_action].js
-        * [more_action].js
-    * [namespace]
-        * [controller]
-            * [action].js
-     
-Generators
--
 
-1. Generate a controller folder containing its required files: 
-```
-rails g paloma:add [controller]
-```
-    **Example:**
-    ```
-    rails g paloma:add users
-    ```
+## Router
 
-    **Generates:**
-    * /paloma
-        * /users
+Router is responsible for mapping Rails controller/action to its equivalent Paloma controller/action.
 
+By default all Rails controller/action will be mapped with a Paloma controller/action with the same resource name (controller name without the `Controller` suffix).
 
-2. Generate a callback file for a controller's action:
-```
-rails g paloma:add [controller] [action]
-```
-    **Example:**
-    ```
-    rails g paloma:add users new
-    ```
+Example:
+* Response from `UsersController#new` will be mapped to `Users` Paloma controller and execute its `new` method.
 
-    **Generates:**
-    * /paloma
-        * /users
-            * new.js
+### Changing Controller
 
+If you want to use a different Paloma Controller for a specific Rails controller, you can do the following:
 
-3. Generate multiple callback files:
-```
-rails g paloma:add [controller] [action_1] [action_2] ... [action_n]
-```
-    **Example:**
-    ```
-    rails g paloma:add users new create edit update
-    ```
-
-    **Generates:**
-    * /paloma
-        * /users
-            * new.js
-            * create.js
-            * edit.js
-            * update.js
-
-4. Generate namespaced controller and callbacks:
-```
-rails g paloma:add [namespace]/[controller] [action_1] [action_2] ... [action_n]
+```javascript
+// Instead of mapping Rails UsersController to Paloma Users
+// it will be mapped to AdminUsers.
+Paloma.router.resource('Users', {controller: 'AdminUsers'});
 ```
 
-    **Example:**
-    ```
-    rails g paloma:add admin/users new
-    ```
+### Redirecting
 
-    **Generates:**
-    * /paloma
-        * /admin
-            * /users
-                * new.js
-                
-**Notes:** 
+You can also redirect an action if you want it to be handled by a different method.
 
-* 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.
+```javascript
+// Instead of executing Paloma's `Users#new` it will execute
+// `Registrations#signUp`.
+Paloma.router.redirect('Users#new', {to: 'Registrations#signUp');
+```
 
-* Controller folder and action javascript files will automatically be created after running `rails g controller` or `rails g scaffold`.
+## Controller
 
-Advanced Callbacks
--
-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.
+Controller handles responses from Rails. A new controller instance is created by Paloma for every Rails controller/action that is executed.
 
-You can manipulate callback behavior by using the `js` command before the `render` or `redirect_to` command in your controllers.
+### Creating Controller
 
-1. Preventing the Callback to execute.
+A Controller is created or accessed (if already existing) using:
 
-    ```ruby
-    def destroy
-        user = User.find params[:id]
-        user.destroy
-        
-        js false
-    end
-    ```
-    
-    `callbacks["controller"]["destroy"]` will not be executed.
-
-2. Using other action's callback from the same controller.
+```javascript
+Paloma.controller('ControllerName');
+``` 
 
-    ```ruby
-    def edit
-        @user = User.find params[:id]
-        js :new
-    end
-    ```
+It returns the constructor of your controller. It is just a normal constructor so you can do your OOP stuff.
 
-    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 :controller => 'clients', :action => 'index'
-    end
-    ```
+### Creating actions
 
-    This will execute `callbacks["clients"]["index"]` instead of `callbacks["controllers"]["index"]`.
+Add instance methods to you Controller constructor to handle actions.
 
+```javascript
+var ArticlesController = Paloma.controller('ArticlesController');
 
-4. Using other action's callback from a namespaced controller.
+ArticlesController.prototype.new = function(){
+  // Handle new articles
+};
 
-    ```ruby
-    class UsersController < ApplicationController
-        def destroy
-            @user = User.find params[:id]
-            @user.destroy
-            
-            js :controller => 'admin/users', :action => :destroy
-        end
-    end
-    ```
 
-    This will execute `callbacks["admin/users"]["destroy"]` instead of `callbacks["users"]["destroy"]`.
+ArticlesController.prototype.edit = function(){
+  // Handle edit articles
+};
+```
 
+## Passing Parameters
 
-Passing 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.
+You can also pass parameters to Paloma by calling `js` before render in your Rails controller. You can access the parameters on your Paloma controller using `this.params` object.
 
 **Example:**
 
@@ -227,235 +138,35 @@ def destroy
     user = User.find params[:id]
     user.destroy
     
-    js :params => {:user_id => params[:id]}
+    js :id => user.id
 end
 ```
 
-`/paloma/users/destroy.js`
-```javascript
-Paloma.callbacks['users']['destroy'] = function(params){
-    var id = params['user_id'];
-    alert('User ' + id + ' deleted.');
-};
-```
-
-
-Default Parameters
--
-`params['controller']` - controller name without its namespace.
-
-`params['namespace']` - controller's namespace name.
-
-`params['action']` - controller's action that triggers the filter or callback.
-
-`params['controller_path']` - controller name with its namespace.
-
-`params['callback_controller']` - callback's controller name without its namespace.
-
-`params['callback_namespace']` - callback's namespace name.
-
-`params['callback_action']` - callback's action name.
-
-`params['callback_controller_path']` - callback's controller with its namespace.
-
-## 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
+Paloma controller.
 
 ```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"); 
-});
-```
-
-### Specify Actions To Filter
-
-1. For all actions.
-    
-    ```javascript
-    filter.as('name').before_all()
-    filter.as('name').after_all()
-    filter.as('name').around_all()
-    ```
-
-2. Only for specific action/s.
-    
-    ```javascript
-    filter.as('name').before('new', 'edit', 'update')
-    filter.as('name').after('destroy')
-    filter.as('name').around('show')
-    ```
-
-3. Except for specific action/s.
-    
-    ```javascript
-    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
+var UsersController = Paloma.controller('Users');
 
-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";
-});
-```
-
-### Skipping Filters
-
-You can skip filters using the `skip_*_filter` or `skip_*_filters` command.
-You can also specify which action or actions the filter skip is applicable using `only` or `except` command.
-
-```javascript
-filter.skip_before_filter('filter A');  // skip 'filter A' for all actions
-filter.skip_after_filters('filter A', 'filter B').only('new', 'edit');  // skip 'filter A' and 'filter B' for 'new' and 'edit' actions.
-filter.skip_around_filter('filter A').except('destroy');    // skip 'filter A' for all actions except for 'destroy'.
-```
-
-##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);
+UsersController.prototype.destroy = function(){
+  alert('User ' + this.params['id'] + ' is deleted.');
 };
 ```
 
-###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"); }
-```
+## Preventing Paloma
 
-`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"); }
-```
+If you want to prevent Paloma from executing in a certain Rails controller action you can do it by passing `false` to `js` command.
 
-`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
+```ruby
+def edit
+  @user = User.find params[:id]
+  js false
+end
 ```
 
-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):
+## Execution Chains
 
-```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.
+Chains are created after a redirect action. The chain will continue to increase its length until a render action is detected.
 
 **Example:**
 
@@ -473,17 +184,19 @@ def third_action
 end
 ```
 
-A request for `first_action` will lead to 2 redirects until it reaches the `third_action` and renders a result on the browser. When the `third_action` renders its response, Paloma will execute the callbacks for all the 3 actions.
+A request for `first_action` will lead to 2 redirects until it reaches the `third_action` and renders a result on the browser. When the `third_action` renders its response, Paloma will process all the request starting from `first_action` up to `third_action`.
 
-The order of execution will be `[controllers]/first_action` first, then `[controllers]/second_action`, and finally `[controllers]/third_action`.
 
+## Gotchas
 
-Gotchas
--
-* Callbacks will not be executed if the response is `js`, `json`, `xml` or any other format except `html`.
-This will not work: `render "something.js.erb"`
+* Paloma  will not execute if the response is `js`, `json`, `xml` or any other format except `html`.
 
-Credits
--
-* [Karl Bryan Paragua](http://www.daftcoder.com "Daftcoder.com")
-* Bianca Camille Esmero
+For example: `render "something.js.erb"`
+
+
+## Where to put code?
+
+Again, Paloma is now flexible and doesn't force developers to follow specific folder structure.
+You have the freedom to create controllers and routes anywhere in your javascript code. 
+
+Personally, I prefer having a `routes.js` file to contain all the route declaration, and a javascript file for each controller.