kotovalexarian-likes-github/paloma
1
0
Fork 0
mirror of https://github.com/kbparagua/paloma synced 2023-03-27 23:21:17 -04:00
Code Releases Activity

Update README

Browse source
This commit is contained in:
kbparagua 2016-03-25 16:30:46 +08:00
parent 320aeb0aae
commit 815d50d52a
1 changed files with 228 additions and 144 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

372
README.md
View file

@ -3,7 +3,6 @@
- check `branches` or `tags` for the latest stable release or specific versions.
# Paloma
Page-specific javascript for Rails done right.
## Advantages
@ -13,35 +12,33 @@ Page-specific javascript for Rails done right.
* No external library dependency.
* Easy to understand (*because it is patterned after Rails' controller module*).
## Minimum Requirement
* Rails 3.1 or higher
## Quick Example
Paloma controller.
Paloma controller:
```javascript
Paloma.controller('Users', {
new: function(){
// Executes when Rails User#new is executed.
// Executes when Rails Users#new is executed.
alert('Hello Sexy User!');
}
});
```
The Rails controller `app/controllers/users_controller.rb`:
Rails controller:
```ruby
def UsersController < ApplicationController
def new
# nothing special
@user = User.new
end
def new
# no special method to call
@user = User.new
end
end
```
That's it! Simply Sexy!
## Minimum Requirements
* Rails 3.1 or higher
## Install
@ -49,16 +46,19 @@ That's it! Simply Sexy!
- Without bundler: `sudo gem install paloma`.
- With bundler, add this to your Gemfile: `gem 'paloma'`
1. Require `paloma` in your `application.js`: `//= require paloma`
1. Require `paloma` in your `application.js`:
```
//= require paloma
```
1. In your layouts insert Paloma's hook.
1. In your layouts insert Paloma's hook. This is responsible for connecting your ruby code to your javascript code.
`application.html.erb`
```html
<html>
<head>
</head>
<body>
<%= yield %>
<%= insert_paloma_hook %>
@ -66,47 +66,41 @@ That's it! Simply Sexy!
</html>
```
1. Start Paloma. *Most of the time this will be inside `document.ready`*.
1. Start Paloma to interpret the hook inserted on your HTML and execute the appropriate Paloma controller and its action. Most of the time this will be inside `document.ready`.
```js
$(document).ready(function(){
// Execute Paloma's callback.
Paloma.start();
});
```
## Controllers
### Controller
Controllers are classes that handle requests made by Rails Controllers. Each Rails Controller's action will be mapped to a specific Paloma Controller's action.
Paloma controllers are just javascript classes that will be mapped with your Rails controller. Basically, both Paloma and Rails controllers will share the same name.
It is created or accessed (if existing), using `Paloma.controller` method.
### Creating a Controller
A Controller constructor is created or accessed (if it already exists), using `Paloma.controller()` method.
```javascript
```js
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.
### Actions
### Handling Actions
To handle specific actions of your Rails controller, simply add methods to your Paloma controller's prototype.
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.
Add actions directly to the constructor's prototype.
```javascript
var Articles = Paloma.controller('Articles');
```js
var ArticlesController = Paloma.controller('Articles');
Articles.prototype.edit = function(){
ArticlesController.prototype.edit = function(){
// Handle edit article
};
```
Or pass the prototype value directly as the 2nd argument of the `controller` method.
Or you can easily pass the prototype value as the 2nd argument of the `Paloma.controller` method.
```js
Paloma.controller('Articles', {
@ -121,6 +115,7 @@ Paloma.controller('Articles', {
Namespaced controller should follow this format: `namespace/controller`.
Rails controller:
```ruby
class Admin::UsersController < ApplicationController
def new
@ -130,6 +125,7 @@ end
```
Paloma controller:
```js
Paloma.controller('Admin/Users', {
new: function(){
@ -140,20 +136,26 @@ Paloma.controller('Admin/Users', {
### Controller Inheritance
It is also possible to create a controller that is a subclass of an existing controller, using the following syntax:
`Controller < ParentController`
Controller inheritance is accomplished using the syntax:
`Controller < ParentController` *(same as ruby's syntax)*
Parent:
```js
Paloma.controller('Application', {
index: function(){
alert('Application: Index');
},
new: function(){
alert('Application: New');
}
});
```
Child:
```js
Paloma.controller('Users < Application', {
// Override Application's new action
new: function(){
@ -166,93 +168,104 @@ Paloma.controller('Users < Application', {
You can manipulate what controller/action should Paloma execute by calling `js` method **before** rendering.
1. Changing controller
1. Changing controller.
```ruby
class UsersController < ApplicationController
def new
@user = User.new
js 'Accounts' # will use Accounts controller instead of Users controller
end
end
```
2. Changing action
You can use the symbol syntax:
```ruby
def new
```ruby
class UsersController < ApplicationController
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
```
# will use Accounts controller instead of Users controller
js 'Accounts'
end
end
```
2. Changing action.
You can use the symbol syntax:
```ruby
def new
@user = User.new
# will execute register method instead of new
js :register
end
```
Or the string syntax:
```ruby
def new
@user = User.new
# will execute register method instead of 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
```
```ruby
def new
@user = User.new
4. Changing controller with namespace.
# will execute Accounts#register instead of Users#new
js 'Accounts#register'
end
```
Paloma supports namespaces using '/' as delimiter.
4. Changing controller (and action) with namespace.
```ruby
def new
@user = User.new
# will use Admin/Accounts instead of Users controller
js `Admin/Accounts`
end
```
```ruby
def new
@user = User.new
# will execute Admin/Accounts#register instead of Users#new
js 'Admin/Accounts#register'
end
```
```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 pass parameters to your Paloma Controller in two ways.
1. Passing a hash. (*parameters only*)
```ruby
def show
user = User.find params[:id]
js :id => user.id
js :id => user.id, :string => 'test'
end
```
2. Passing path and a hash.
2. Passing a path and a hash.
```ruby
def show
user = User.find params[:id]
js 'Admin/Users', :id => user.id
js 'Admin/Users', :id => user.id, :string => 'test'
end
```
Using both ways, you can access the passed params using the `params` property of your Paloma controller.
You can access the passed params using the `params` property of your Paloma controller.
```javascript
```js
Paloma.controller('Users', {
show: function(){
alert("User id: " + this.params.id);
alert("String: " + this.params.string);
}
});
```
@ -260,7 +273,7 @@ Paloma.controller('Users', {
## 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.
If you do not want Paloma to execute in a specific Rails Controller action you pass `false` to the `js` method.
```ruby
def edit
@ -269,43 +282,131 @@ def edit
end
```
## Before Callbacks
## Controller-wide setup
Executing a method before doing an action can be done using the `before` property of any controller.
You can call `js` outside Rails controller actions for global or controller-wide settings.
```js
Paloma.controller('Articles', {
before: ['show -> alert'],
show: function(){
// Handle show Article
},
alert: function(){
alert("You are about to show an article.");
}
});
```
Multiple actions and callbacks should be separated by spaces.
```js
Paloma.controller('Articles', {
before: ['show index -> alert log'],
index: function(){},
show: function(){},
alert: function(){
alert('Before index and show');
},
log: function(){
console.log('Before index and show');
}
});
```
Callback's order of execution is based on their order on the string.
So in this case, `alert` will be executed first before `log`.
### Multiple Before Entries
The order of execution is also based on the order of entries on the `before` array.
```js
Paloma.controller('Articles', {
before: [
'show -> beforeShow',
'index -> beforeIndex',
'show index -> beforeShowAndIndex'
],
beforeShow: function(){ alert('Before Show'); },
beforeShowAndIndex: function(){ alert('Before Show and Index'); }
});
```
When `show` is executed, the following callbacks will be called in this order:
`beforeShow beforeShowAndIndex`
### Before All Actions
`all` is a special string that can be used to indicate a catch-all callback.
```js
Paloma.controller('Articles', {
before: ['all -> initialize'],
initialize: function(){
alert('I will be executed for every action');
}
});
```
## Paloma Execution Details
You can access what `controller` and `action` Paloma is about to execute or already executed,
by accessing the `controller` and `action` property of a Paloma controller.
```js
Paloma.controller('Users', {
before: ['all -> log'],
log: function(){
console.log('Controller: ' + this.controller);
console.log('Action: ' + this.action);
}
})
```
## Controller-wide Setup
You can call `js` outside Rails controller actions for controller-wide settings.
**Example:**
```ruby
class UsersController < ApplicationController
js 'Accounts' # use Accounts controller instead of Users for all actions.
# use Accounts controller instead of Users for all actions.
js 'Accounts'
def new
@user = User.new
end
def new
@user = User.new
end
def show
@user = User.find params[:id]
end
def show
@user = User.find params[:id]
end
end
```
Like `before_filter` you can also pass `only` and `except` options.
Like `before_action` of Rails you can also pass `only` and `except` options.
```ruby
class UsersController < ApplicationController
js 'Admin/Accounts', :except => :destroy # Use Admin/Accounts except for destroy method
# Use Admin/Accounts except for show and destroy method
js 'Admin/Accounts', :except => [:show, :destroy]
end
```
**IMPORTANT NOTE:**
If you are going to pass parameters for Controller-wide settings, put them inside a `:params` hash.
If you are going to pass parameters for Controller-wide settings, pass a hash using the `:params` key.
```ruby
class UsersController < ApplicationController
@ -313,34 +414,37 @@ class UsersController < ApplicationController
end
```
### Overriding Controller-wide setup
### Overriding Controller-wide Setup
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.
If you want to override the controller-wide setup call `js` again inside a controller action. From there you can override the controller/action or pass additional parameters.
```ruby
class UsersController < ApplicationController
js 'Accounts', :params => {:x => 1}
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
def new
@user = User.new
# will execute Accounts#register with params {:x => 1, :y => 2}
js :register, :y => 2
end
end
```
## Hook
`insert_paloma_hook` is a helper method that you can use in your views to insert Paloma's HTML hook.
Inside this HTML hook is where the magic happens. This is the reason why Paloma can magically know what Javascript controller/action to execute. To further understand how Paloma works, you can inspect the HTML hook, by checking the generated HTML (*inspect element*) and locate the `div` element that has the class `js-paloma-hook`.
`insert_paloma_hook` is a helper method that you use in your views to insert Paloma's HTML hook. It is what connects your Ruby code to your javascript code. Basically, it contains a javascript code that has embedded ruby in it. That javascript code will register the Rails controller and action to Paloma's engine, then after that it will remove itself from the DOM.
Ideally, you just need to call `insert_paloma_hook` in your layouts, since the layout will always be included in every rendered view. But if you are rendering a view without a layout, make sure to call `insert_paloma_hook` in that view.
## Starting Paloma
Once Paloma's HTML hook is already executed, you can now start Paloma by calling `Paloma.start()` in your javascript code. First, it will execute the HTML hook if not yet executed, then will initialize the correct Paloma controller, execute any before callbacks, and finally execute the correct action if available.
## AJAX
1. Make sure that the AJAX response contains the html hook. (use `insert_paloma_hook`)
1. Make sure that the AJAX response contains the HTML hook. (use `insert_paloma_hook`)
2. Start Paloma on complete/success.
```js
@ -361,23 +465,3 @@ $(document).on('page:restore', function(){
Paloma.start();
});
```
## Gotchas
* Make sure that the rendered view has the paloma hook (*use `insert_paloma_hook`*) for Paloma to execute.
## 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 anywhere in your application.
Personally, I prefer having a javascript file for each controller.
## Contribute
1. Fork.
2. Do awesome things.
3. Submit Pull-Request to `master` branch.
4. Add short summary of changes on your PR.