-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update README.md code & instructions #29
- Loading branch information
Showing
1 changed file
with
81 additions
and
59 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,8 +15,7 @@ using [**`elixir-auth-github`**](https://github.com/dwyl/elixir-auth-github). | |
|
|
||
| # _Why_? 🤷 | ||
|
|
||
| As developers we are _always learning_ new things. | ||
| When we learn, we love having _detailed docs and **examples**_ | ||
| **We _love_** having _**detailed docs** and **examples**_ | ||
| that explain _exactly_ how to get up-and-running. | ||
| We _write_ examples because we want them for _ourselves_, | ||
| if you find them useful, please ⭐️ the repo to let us know. | ||
|
|
@@ -38,12 +37,13 @@ without the extra steps to configure a whole auth _framework_. | |
|
|
||
| Following all the steps in this example should take around 10 minutes. | ||
| However if you get stuck, please don't suffer in silence! | ||
| Get help by opening an issue: https://github.com/dwyl/elixir-auth-github/issues | ||
| Get help by opening an issue: | ||
| [dwyl/elixir-auth-github/issues](https://github.com/dwyl/elixir-auth-github/issues) | ||
|
|
||
| # _How?_ 💻 | ||
|
|
||
| This example follows the step-by-instructions in the docs | ||
| [github.com/dwyl/elixir-auth-github](https://github.com/dwyl/elixir-auth-github) | ||
| [dwyl/elixir-auth-github](https://github.com/dwyl/elixir-auth-github) | ||
|
|
||
|
|
||
| ## 0. Create a New Phoenix App | ||
|
|
@@ -59,21 +59,23 @@ mix phx.new app | |
| ``` | ||
|
|
||
| > **Note**: In creating this demo app | ||
| > we actually ran the command with the following | ||
| > [flags](https://hexdocs.pm/phoenix/Mix.Tasks.Phx.New.html): | ||
| > we ran the command with the following | ||
| > [**flags**](https://hexdocs.pm/phoenix/Mix.Tasks.Phx.New.html): | ||
| > `mix phx.new app --no-assets --no-dashboard --no-ecto --no-gettext --no-mailer` | ||
| > to keep the project as basic as possible. | ||
| > You may need some or all of the features of `Phoenix`, | ||
| > so check which flags are applicable to you. | ||
| If prompted to install dependencies: | ||
|
|
||
| ``` | ||
| Fetch and install dependencies? [Yn] | ||
| ``` | ||
|
|
||
| Type `y` and hit the `[Enter]` key to install. | ||
|
|
||
| You should see something like this: | ||
|
|
||
| ``` | ||
| * running mix deps.get | ||
| * running mix deps.compile | ||
|
|
@@ -111,7 +113,7 @@ Open your `mix.exs` file and add the following line to your `deps` list: | |
| ```elixir | ||
| def deps do | ||
| [ | ||
| {:elixir_auth_github, "~> 1.6.0"} | ||
| {:elixir_auth_github, "~> 1.6.5"} | ||
| ] | ||
| end | ||
| ``` | ||
|
|
@@ -136,7 +138,7 @@ GITHUB_CLIENT_SECRET=MHxv6-RGF5nheXnxh1b0LNDq | |
| > ⚠️ Don't worry, these keys aren't valid. | ||
| They are just here for illustration purposes. | ||
|
|
||
| ## 3. Create 2 New Files ➕ | ||
| ## 3. Create 3 New Files ➕ | ||
|
|
||
| We need to create two files in order to handle the requests | ||
| to the GitHub OAuth API and display data to people using our app. | ||
|
|
@@ -160,11 +162,10 @@ defmodule AppWeb.GithubAuthController do | |
| """ | ||
| def index(conn, %{"code" => code}) do | ||
| {:ok, profile} = ElixirAuthGithub.github_auth(code) | ||
| conn | ||
| |> put_view(AppWeb.PageView) | ||
| |> render(:welcome, profile: profile) | ||
| render(conn, :welcome, [layout: false, profile: profile]) | ||
| end | ||
| end | ||
|
|
||
| ``` | ||
|
|
||
| This code does 3 things: | ||
|
|
@@ -182,13 +183,17 @@ You are free to organise your code however you prefer. | |
| ### 3.2 Create `welcome` template 📝 | ||
|
|
||
| Create a new file with the following path: | ||
| `lib/app_web/templates/page/welcome.html.eex` | ||
| `lib/app_web/controllers/github_auth_html/welcome.html.heex` | ||
|
|
||
| And type (_or paste_) the following code in it: | ||
| ```html | ||
| <section class="phx-hero"> | ||
| <h1> Welcome <%= @profile.name %>! | ||
| <img width="32px" src="<%= @profile.avatar_url %>" /> | ||
| <script src="https://cdn.tailwindcss.com"></script> | ||
|
|
||
| <section class="flex flex-col items-center justify-center px-6 py-8 mx-auto md:h-screen lg:py-0"> | ||
| <h1 class="text-4xl text-center font-bold leading-tight tracking-tight text-gray-900 md:text-2xl"> | ||
| Welcome <%= @profile.name %>! | ||
| <img class="float-right h-8 w-8 rounded-full" alt="avatar image" width="32px" | ||
| src={@profile.avatar_url} /> | ||
| </h1> | ||
| <p> You are <strong>signed in</strong> | ||
| with your <strong>GitHub Account</strong> <br /> | ||
|
|
@@ -197,65 +202,65 @@ And type (_or paste_) the following code in it: | |
| </section> | ||
| ``` | ||
|
|
||
| > **Note**: There's a fair amount of `TailwindCSS` sprinkled in that template, | ||
| if you're new to `Tailwind` or need a refresher, | ||
| please see: | ||
| [/learn-tailwind](https://github.com/dwyl/learn-tailwind) | ||
|
|
||
|
|
||
| Invoking `ElixirAuthGithub.github_auth(code)` | ||
| in the `GithubAuthController` | ||
| `index` function will | ||
| make an HTTP request to the GitHub Auth API | ||
| and will return `{:ok, profile}` | ||
| where the `profile` | ||
| is the following format: | ||
| where the `profile` data | ||
| has the following format: | ||
|
|
||
| ```elixir | ||
| %{ | ||
| site_admin: false, | ||
| disk_usage: 265154, | ||
| access_token: "8eeb143935d1a505692aaef856db9b4da8245f3c", | ||
| private_gists: 0, | ||
| followers_url: "https://api.github.com/users/nelsonic/followers", | ||
| public_repos: 291, | ||
| gists_url: "https://api.github.com/users/nelsonic/gists{/gist_id}", | ||
| subscriptions_url: "https://api.github.com/users/nelsonic/subscriptions", | ||
| plan: %{ | ||
| "collaborators" => 0, | ||
| "name" => "pro", | ||
| "private_repos" => 9999, | ||
| "space" => 976562499 | ||
| }, | ||
| node_id: "MDQ6VXNlcjE5NDQwMA==", | ||
| created_at: "2010-02-02T08:44:49Z", | ||
| blog: "https://www.dwyl.io/", | ||
| type: "User", | ||
| bio: "Learn something new every day. github.com/dwyl/?q=learn", | ||
| following_url: "https://api.github.com/users/nelsonic/following{/other_user}", | ||
| repos_url: "https://api.github.com/users/nelsonic/repos", | ||
| total_private_repos: 5, | ||
| html_url: "https://github.com/nelsonic", | ||
| public_gists: 29, | ||
| avatar_url: "https://avatars3.githubusercontent.com/u/194400?v=4", | ||
| organizations_url: "https://api.github.com/users/nelsonic/orgs", | ||
| url: "https://api.github.com/users/nelsonic", | ||
| followers: 2778, | ||
| updated_at: "2020-02-01T21:14:20Z", | ||
| location: "London", | ||
| hireable: nil, | ||
| name: "Nelson", | ||
| owned_private_repos: 5, | ||
| company: "@dwyl", | ||
| email: "[email protected]", | ||
| two_factor_authentication: true, | ||
| starred_url: "https://api.github.com/users/nelsonic/starred{/owner}{/repo}", | ||
| id: 194400, | ||
| following: 173, | ||
| login: "nelsonic", | ||
| collaborators: 8 | ||
| collaborators: 28, | ||
| avatar_url: "https://avatars3.githubusercontent.com/u/194400?v=4", | ||
| etc: "you get the idea ..." | ||
| } | ||
| ``` | ||
|
|
||
| More info: https://developer.github.com/v3/users | ||
|
|
||
| You can use this data however you see fit. | ||
| Use this data how you see fit. | ||
| (_obviously treat it with respect, | ||
| only store what you need and keep it secure_) | ||
| only store what you need and keep it secure!_) | ||
|
|
||
| ### 3.3 Create the | ||
|
|
||
| Create a file with the path: | ||
| `lib/app_web/controllers/github_auth_html.ex` | ||
|
|
||
| and add the following code to it: | ||
|
|
||
| ```elixir | ||
| defmodule AppWeb.GithubAuthHTML do | ||
| use AppWeb, :html | ||
|
|
||
| embed_templates "github_auth_html/*" | ||
| end | ||
| ``` | ||
|
|
||
|
|
||
| ## 4. Add the `/auth/github/callback` to `router.ex` | ||
|
|
@@ -284,36 +289,53 @@ and update the `index` function: | |
|
|
||
| From: | ||
| ```elixir | ||
| def index(conn, _params) do | ||
| render(conn, "index.html") | ||
| end | ||
| def home(conn, _params) do | ||
| # The home page is often custom made, | ||
| # so skip the default app layout. | ||
| render(conn, :home, layout: false) | ||
| end | ||
| ``` | ||
|
|
||
| To: | ||
| ```elixir | ||
| def index(conn, _params) do | ||
| def home(conn, _params) do | ||
| oauth_github_url = ElixirAuthGithub.login_url_with_scope(["user:email"]) | ||
| render(conn, "index.html", [oauth_github_url: oauth_github_url]) | ||
| render(conn, :home, [layout: false, oauth_github_url: oauth_github_url]) | ||
| end | ||
| ``` | ||
|
|
||
| ### 5.1 Update the `page/index.html.eex` Template | ||
|
|
||
| Open the `/lib/app_web/templates/page/index.html.eex` file | ||
| Open the `/lib/app_web/controllers/page_html/home.html.heex` file | ||
| and type (_or paste_) the following code: | ||
|
|
||
| > **`TODO`**: create button: https://github.com/dwyl/elixir-auth-github/issues/33 | ||
| ```html | ||
| <section class="phx-hero"> | ||
| <h1>Welcome to Awesome App!</h1> | ||
| <p>To get started, login to your GitHub Account: <p> | ||
| <a href="<%= @oauth_github_url %>"> | ||
| <img src="https://i.imgur.com/qwoHBIZ.png" alt="Sign in with GitHub" /> | ||
| </a> | ||
| <script src="https://cdn.tailwindcss.com"></script> | ||
|
|
||
| <section class=""> | ||
| <div class="flex flex-col items-center justify-center px-6 py-8 mx-auto md:h-screen lg:py-0"> | ||
| <div class="w-full bg-white rounded-lg shadow dark:border md:mt-0 sm:max-w-md xl:p-0 dark:bg-gray-200 dark:border-gray-700"> | ||
| <div class="p-6 space-y-4 md:space-y-6 sm:p-8"> | ||
| <h1 class="text-3xl text-center font-bold leading-tight tracking-tight text-gray-900 md:text-2xl"> | ||
| Welcome to Awesome App! | ||
| </h1> | ||
| <p class="text-center"> | ||
| To get started, login with your GitHub Account: | ||
| </p> | ||
| <a href={ @oauth_github_url } class="py-8 flex items-center justify-center"> | ||
| <img src="https://i.imgur.com/qwoHBIZ.png" alt="Sign in with GitHub" /> | ||
| </a> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| </section> | ||
| ``` | ||
|
|
||
| > **Note**: the login button is an image for brevity. | ||
| > In our production version we use `CSS` and `SVG`, | ||
| > see: | ||
| > [/elixir-auth-github#optimised-svgcss-button](https://github.com/dwyl/elixir-auth-github#optimised-svgcss-button) | ||
| ## 6. _Run_ the App! | ||
|
|
||
| Run the app with the command: | ||
|
|
@@ -327,14 +349,14 @@ where you will see a | |
| "Sign in with GitHub" button: | ||
| http://localhost:4000 | ||
|
|
||
|  | ||
|  | ||
|
|
||
| Once the user authorizes the App, | ||
| they will be redirected | ||
| back to the Phoenix App | ||
| and will see welcome message: | ||
|
|
||
|  | ||
|  | ||
|
|
||
|
|
||
| <br /> | ||
|
|
||