README.md in goma-0.0.1.alpha vs README.md in goma-0.0.1.beta
- old
+ new
@@ -2,17 +2,23 @@
An authentication solution for Rails 4.
Currently supports ActiveRecord only.
The API is almost same as [Sorcery](https://github.com/NoamB/sorcery) \[[LICENSE](https://raw.githubusercontent.com/NoamB/sorcery/master/LICENSE.txt)\].
-Lots of code are borrowed or shamelessly copied from \[[Devise](https://github.com/plataformatec/devise) [LICENSE](https://raw.githubusercontent.com/plataformatec/devise/master/MIT-LICENSE)\].
-Thank maintainers, committers and contributers to above two gems.
+Lots of code are borrowed or shamelessly copied from [Devise](https://github.com/plataformatec/devise) \[[LICENSE](https://raw.githubusercontent.com/plataformatec/devise/master/MIT-LICENSE)\].
-Currently, Goma is under development.
-Because I am not good at English, writing documents, corrections, and suggesting better module, class, variable or method names are welcome.
+Thank maintainers, committers and contributers of above two gems.
+Currently, Goma is in early development phase. There must be bugs and lack of functionalities so that it should not be used for production for a while. I will improve my code and write documents as soon as possible.
+
+All sorts of contributions are welcome.
+
+Because I am not good at English, writing documents, corrections, and suggesting better module, class, variable or method names are also welcome.
+
+
+## About
Goma is an authentication solution for Rails 4 based on Warden. It:
- allows you to use almost same as Sorcery
- supports authentication in routes
- allows you to have multiple models signed in at the same time
@@ -42,35 +48,70 @@
```console
rails generate goma:install
```
-The generator will install an initializer which describes ALL Goma's configuration options and you MUST take a look at it and change options to fit your needs. When you are done, you are ready to add Goma model to any of your models using the generator.
+The generator will install an initializer which describes ALL Goma's configuration options and you MUST take a look at it and change options to fit your needs.
+When you are done, you are ready to scaffold an entire resource for authentication, from model and migration to controller and views. (but, I'm sorry, working test suites are not included)
+
+```console
+rails generate goma:scaffold NAME
```
-rails generate goma:model MODEL
+
+Replace NAME by the class name used for the applications users, it's frequently `user` but could also be anything you want. This will create a model with a migration, controllers, views, and mailers (that are configured based on the initializer file which is created by `rails generate goma:install`).
+
+Please note that this scaffold generator is just a "better than nothing' thing. It does not include tests and there must be bugs. But if you see the code which is generated by this scaffold, you can see how to use this gem roughly. If you find bugs, please create an issue or send a pull request.
+
+
+You can also use the following generators.
+
```
+ goma:mailer
+ goma:model
+ goma:model:oauth
+ goma:scaffold:confirmation # Confirmable
+ goma:scaffold:oauth # Omniauthable
+ goma:scaffold:password # Recoverable
+ goma:scaffold:session # PasswordAuthenticatable
+ goma:scaffold:unlock # Lockable
+ goma:scaffold:user
+ goma:scaffold_controller
+```
-Replace MODEL by the class name used for the applications users, it's frequently `user` but could also be anything you want. This will create a model (if one does not exist) with a migration (which is configured based on the initializer file which is created by `rails generate goma:install`).
+For example, you can add a Goma model as follows:
+```console
+rails generate goma:model MODEL
+```
+
## API summary
```
+ # in routes
+ current_user # If you have an :admin scope, you can use current_admin
+ user_logged_in? # you can specify scope
+
+ # in controllers
require_login # this is a before filter (default scope)
require_user_login # ditto. You can specify a scope.
- login(identifier, password, remember_me=false) # You can use multiple identifiers such as username and email
+ login(identifier, password, remember_me=false) # You can use multiple identifiers in a field, such as username or email.
force_login(user) # Login without credentials (same as auto_login in Sorcery gem)
logout(scope=Goma.config.default_scope) # Logout. you can specify a scope.
user_logout # ditto
logged_in? # Available in view
user_logged_in? # ditto. You can specify a scope.
current_user # Available in view. If you have an :admin scope, you can use current_admin
- remember_me!
- forget_me!
+ # Password authenticatable
+ find_by_identifier # You can find user by authentication key
+ # Rememberable
+ remember_me! # Goma call this automatically so that, usually, You don't have to call this manually.
+ forget_me! # ditto
+
# Confirmable
User.load_from_activation_token(token)
User#activate!
User.load_from_email_confirmation_token(token)
User#confirm_email!
@@ -89,6 +130,37 @@
# Omniauthable
User.create_with_omniauth!(omniauth)
User#fill_with_omniauth # This method is called when creating user object with OmniAuth
Authentication#fill_with_omniauth # This method is called when creating authentication object with OmniAuth
+```
+
+
+## Authentication in routes
+You can use API for routes as follows
+
+```ruby
+YourApp::Application.routes.draw do
+ constraints current_user do
+ root to: 'dashboard#index' # root for login users
+ end
+
+ root to: 'home#index' # root for public
+end
+```
+
+You can also specify criteria as follows:
+
+```ruby
+YourApp::Application.routes.draw do
+ constraints current_user { |u| u && u.role == 'admin' } do
+ # for admin users
+ # The block parameter is current_user, which is nil when user is not logged in.
+ end
+
+ constraints current_user { role == 'admin' } do
+ # for admin users
+ # this is a shortcut of the above.
+ # In this case, when user is not logged in, the block is not executed.
+ end
+end
```