= {<img src="http://i50.tinypic.com/wag4d4.png">}[http://github.com/zamith/citygate] {<img src="https://secure.travis-ci.org/zamith/citygate.png" />}[http://travis-ci.org/zamith/citygate]

Citygate is a rails engine that provides your application with user authentication (on the site or through OAuth) using Devise and authorization using CanCan.

It also provides a customizable backend for administrating all your users, using turbolinks making your website as fast and responsive as you ever wanted it to be.

Citygate aims to provide this functionalities in a hassle free way, thus it requires very little to no configuration in order to have everything up and running. It achieves this at the cost of not being super flexible and configurable, for that you can use gems as sorcery[https://github.com/NoamB/sorcery] or clearance[https://github.com/thoughtbot/clearance], or even hack into devise[https://github.com/plataformatec/devise] or cancan[https://github.com/ryanb/cancan] yourself.

== Instalation

First add the gem to your Gemfile to get the latest stable version

  gem "citygate"

or go on the edge with

  gem "citygate", :git => "https://zamith@github.com/zamith/citygate.git"

== Database Configuration

In order to get the database ready to run citygate you will need to fetch the migrations

  rake citygate:install:migrations

and run them

  rake db:migrate

then drop this line at your +db/seeds.rb+ file in order to be able to populate the db with the needed records

  Citygate::Engine.load_seed

and finally run the seeds command to actually populate the db

  rake db:seed

== Routes Configuration

To get all the citygate routes working you just need to mount them by adding the following line to your +config/routes.rb+ file

  mount Citygate::Engine => "/"

== Environment Configuration

Since citygate will send confirmation emails to any user that signs up, you will need to have your email configured.

In case of development add this to +config/environments/development.rb+

  config.action_mailer.default_url_options = { :host => 'localhost:3000' }

== Helper Configuration

In order to get the helper methods citygate exposes you'll have to include them in your +app/controllers/application_controller.rb+ like so:

  class ApplicationController < ActionController::Base
    helper Citygate::Engine.helpers
  end

The exposed methods are:

role_changer:: a select for changing roles (only available when logged in and in development)
citygate_nav_links:: the default +nav+ for citygate with sign in, log out and admin links

== OmniAuth Configuration

Citygate needs your facebook apps identifiers which are loaded from a file you must create called +config/accounts.yml+ and has the following format:

  facebook:
    app_id: "your app id from https://developers.facebook.com/apps"
    app_secret: "your app secret from https://developers.facebook.com/apps"

This file is not required for the application to run, but without it the facebook login will not work.

In case you are wondering, the reason it is not required for you to add your google OAuth identifier is because it is the same for everyone. It then redirects you to a authentication service within google servers.

== Loading Assets

In order to have the javascript added by Citygate you need to include it in your manifest file, like so:

  //= require citygate

== Citygate Options

You can change citygate's defaults by editing your +config/application.rb+ file like so

  Citygate::Engine.configure do
    config.option = value
  end

=== Options

The available options are:

will_paginate_options:: an hash with any option supported by paginate[https://github.com/mislav/will_paginate/wiki]
mount_path:: if you mount the engine in any other path than "/", must define it here as well so that omniauth can be aware of it
no_of_users:: limit the number of users allowed in your system

== Authorization

Citygate load CanCan and uses it internally, but since it cannot know which roles and permissions you need it leaves it up to you to define an Ability class following the CanCan format[https://github.com/ryanb/cancan/wiki/Defining-Abilities]. 

Citygate checks for authorization on most of its views, you can generate a default ability class by running:

  rails generate ability 

== Running Citygate

Users in citygate will not be able to login with their google account if you use WEBrick, due to its url length limitation. Therefore run your server in development with <tt>rails s thin</tt>, to run the thin server.

---

*Note:* Do not forget to check the routes made available to you by Citygate with <tt>rake routes</tt> and to take a look at the doc at RubyDoc[http://rubydoc.info/github/zamith/citygate/master/frames]