README.md

# HR (department for your application.)

[![Build Status](https://travis-ci.org/Zensavona/hr.svg?branch=master)](https://travis-ci.org/Zensavona/hr) [![Inline docs](http://inch-ci.org/github/zensavona/hr.svg?branch=master)](http://inch-ci.org/github/zensavona/hr) [![Coverage Status](https://coveralls.io/repos/Zensavona/hr/badge.svg?branch=master&service=github)](https://coveralls.io/github/Zensavona/hr?branch=master) [![hex.pm version](https://img.shields.io/hexpm/v/hr.svg)](https://hex.pm/packages/hr) [![hex.pm downloads](https://img.shields.io/hexpm/dt/hr.svg)](https://hex.pm/packages/hr) [![License](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)

### [Read the docs](https://hexdocs.pm/hr)

A feature rich and highly customisable user account and authorisation library for Phoenix Framework, heavily inspired by Devise for Rails.


## Installation

HR comes with some generators for installing configuration and creating HR preconfigured models (you can have as many models which represent 'users' as you like). This guide assumes you're creating a new model, but there's a [wiki page](todo...) about adding HR to an existing model. For the purpose of this example, our model will be called User, but it can be called whatever you like. The routes and helpers will match what you name the model.

First, add HR to your `mix.exs` deps section with `{:hr, "~> 0.1.3"}` and add `:hr` to the list of `applications`.

Next, run `mix deps.get` to pull down HR and it's dependencies, then `mix hr.gen.model User users` (this builds on `phoenix.gen.model`, and accepts the same options), and `mix ecto.migrate`. Now we have two new models and migrations: User, and UserIdentities. UserIdentities takes care of credentials and information about a User which is not their email and password (an example of this is OAuth tokens).

Let's take a quick look at the User model:

````
defmodule HrExample.User do
  use HrExample.Web, :model
  use Hr.Behaviours, [:registerable, :database_authenticatable, :recoverable, :confirmable]
  # optionally add :oauthable to authenticate users with the oauth providers you specify in config/hr.exs

  schema "users" do

    field :password, :string, virtual: :true
    field :email, :string
    field :unconfirmed_email, :string
    field :password_hash, :string
    field :confirmation_token, :string
    field :confirmed_at, Ecto.DateTime
    field :confirmation_sent_at, Ecto.DateTime
    field :password_reset_token, :string
    field :reset_password_sent_at, Ecto.DateTime
    field :failed_attempts, :integer, default: 0
    field :locked_at, Ecto.DateTime
    has_many :user_identities, Phoenixgram.UserIdentity

    timestamps
  end
````

Looks just like a regular Phoenix model, except for the `use Hr.Behaviours`. You can remove any of these to disable the corresponding feature, and add `:oauthable` to allow this model to be authenticatable with OAuth. You can set the OAuth providers in `config/hr.exs`. Right now only GitHub is supported, but I'm in the process of adding Facebook, Instagram, Twitter and Google.

Ok, next up, we need to run `mix hr.install`, which adds `config/hr.exs`, `web/templates/hr_email` and `web/hr_i18n.ex`.

You should get some instructions in your terminal to add the line `import_config "hr.exs"` to the end of your `config/config.exs`, so go ahead and do that.

Now, the last step: we need to tell our router to use HR's authentication logic and routes, and where to put them.

Change your router so it looks like the one below, we'll go over what each change does and how to customise things in a moment.

````
defmodule HrExample.Router do
  use HrExample.Web, :router
  use Hr.RouterHelper

  pipeline :browser do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_flash
    plug :protect_from_forgery
    plug :put_secure_browser_headers
  end

  pipeline :api do
    plug :accepts, ["json"]
  end

  pipeline :users do
    plug :hr_for, :user
  end

  scope "/" do
    pipe_through [:browser, :users]
    hr_routes_for :user

    get "/", HrExample.PageController, :index
  end
end
````

The first addition, `use Hr.RouterHelper`, provides us with a plug and a macro for configuring HR routes and helpers.

```
pipeline :users do
  plug :hr_for, :user
end
```

Adding a pipeline containing the `hr_for` plug for our model is a neat way to be able to add cookie handling and authentication to the plug pipeline easily. The name `:users` has no particular significance and if you prefer, you can just add `plug :hr_for, :user` to your existing pipeline.

`hr_routes_for :user` creates routes and helpers for the `User` model within the `/` scope. Note that we've also changed `scope "/", HrExample` to `scope "/" do` and changed `get "/", PageController, :index` to `get "/", HrExample.PageController, :index`. This is because by default Phoenix assumes all code running inside this scope will begin with the `HrExample` namespace.


** WIP **