Merge branch 'release/v0.9.6'

Author: ashokgelal

build.gradle

@@ -18,7 +18,7 @@ startScripts {
 mainClassName = 'dev.alpas.alpasdev.StartKt'
 
 group 'dev.alpas.alpasdev'
-version '0.9.5'
+version '0.9.6'
 
 repositories {
     jcenter()

src/main/resources/docs/authentication-scaffolding.md

@@ -2,22 +2,23 @@
 - [Auth Templates](#auth-templates)
 - [Auth Controllers](#auth-controllers)
 
-Authentication is a "must have" feature in most of today's web apps. Almost all the web apps pretty much 
-need the exact set of authentication features — user register, email verification, logging and logging out, reset 
-password etc.
+Authentication is a must-have feature in most of today's web apps. Almost all the web apps pretty much need the exact
+set of authentication features—user registration, email verification, logging and logging out, password resets etc.
 
-It needs a lot of work to wire all the components of an authentication system — controllers, models, views, forms,
-routing, middleware, validation, notifications etc — and make them work. Alpas comes bundled with a `make:auth`
-command that does pretty much everything to add an authentication system to your app. 
+It needs a lot of work to wire all the components of an authentication system—controllers, models, views, forms,
+routing, middleware, validation, notifications etc.—and make them properly work. Alpas comes bundled with a
+`make:auth` command that does pretty much everything to add an authentication system to your app. 
 
-In this section dive deep into some files and classes generated by `alpas make:auth` command and also see how we
-can further customize the authentication system.
+In this section we will dive deep into some files and classes generated by `alpas make:auth` command.
+We will also see how we can further customize the authentication system to meet our custom needs.
 
 <a name="getting-started"></a>
 ### [Getting started](#getting-started)
 
-To get started, run `alpas make:auth` command from your terminal. Once the authentication system is scaffolded,
-call `authRoutes()` from your routes file.
+To get started, run `alpas make:auth` command from your terminal. Once the authentication
+system is scaffolded, call `authRoutes()` from your routes file.
+
+<span class="line-numbers" data-start="6" data-file="routes.kt">
 
 ```kotlin
 
@@ -29,21 +30,23 @@ fun Router.addRoutes() = apply {
 
 ```
 
+</span>
+
 That's it! 
 
-To make sure it actually works, visit http://localhost:8080/register and you should see a nice looking registration 
-form.
+To make sure it actually is working, visit http://localhost:8080/register You should see a nice
+looking registration form.
 
 <a name="auth-templates"></a>
 ### [Auth Templates](#auth-templates)
 
-These are some templates created by `make:auth` command under `resources/templates` folder:
+These are the Pebble templates created by `make:auth` command under `resources/templates` folder:
 
 <div class="sublist">
 
 - `layout/app.peb`
 
-The authentication aware layout file used by all the auth views. It is designed to work for not just auth templates 
+The authentication aware layout file used by all the auth views. It is designed to work for not just auth templates
 but for your other templates as well. We recommend using this layout file for all of your templates.
 
 - `auth/register.peb`
@@ -56,99 +59,105 @@ The login form page.
 
 - `auth/verify.peb`
 
-A page that informs user to verify their email after they successfully register and created a new account.
+A page that informs a user to verify their email address after successfully registering and creating a new account.
 
-The system uses `templates/auth/emails/verify.peb` template to style and render the actual email that gets sent.
+Alpas uses `templates/auth/emails/verify.peb` template to style and render the actual email that gets sent.
 
 - `auth/passwords/reset_email.peb`
 
-If a user forgets their login password, they can request your app to receive an email with password reset 
-instructions. This page is where they would make password reset request by providing an email address.
+If a user forgets their login password, they can request your app to receive an email with password reset
+instructions. This page is where they would make that request by providing an email address.
 
-The system uses `templates/auth/emails/reset.peb` template to style and render the actual email that gets sent.
+Alpas uses `templates/auth/emails/reset.peb` template to style and render the actual email that gets sent.
 
 - `auth/passwords/reset.peb`
 
-After a user receives a password reset request email and click a link to reset, they are taken to this page where
-they will be asked to set a new password and confirm the password.
+After a user receives a password reset request email and clicks a link to reset, they are taken to
+this page where they will be asked to set a new password and confirm the password.
 
 - `home.peb`
 
-An example template that shows what an authenticated page looks like. You can modify this template or completely 
-remove it and its corresponding controller `HomeController.kt` files safely.
+An example template that shows what an authenticated page looks like. You can modify this template or
+safely remove it along with its corresponding controller: `HomeController.kt`.
 
 </div>
 
 <a name="auth-controllers"></a>
 ### [Auth Controllers](#auth-controllers)
 
-All the controllers that are required to make the scaffolded authentication system work are put under
-`controllers/auth` folder. If you open these controllers, you'll notice that every one of them is empty. This is 
-because to make the authentication system work without any further customization, you really don't have to do 
-anything. For most of the apps just default scaffolded behaviour is enough for a function authentication system. 
-These controller files are generated for you only for further customizations.
+All the controllers that are needed to make the scaffolded authentication system work are put under
+`controllers/auth` folder. If you open these controllers, you'll notice that every one of them is
+empty. This is because to make the authentication system work without any further customization,
+you really don't have to do anything!
+
+For most of the apps just default scaffolded behaviour is enough for a functional authentication
+system. These controller files are generated for you only for further customizations.
 
 <div class="sublist">
 
 - `controllers/auth/LoginController.kt`
 
 Handles user login and logout.
 
-`auth/login.peb` template is the default template used for showing the login form. If you want to use a different
-template or want to pass some extra arguments, you need to override `fun showLoginForm(call: HttpCall)` method and
-call `call.render()` method yourself.
+`auth/login.peb` template is the default template used for showing the login form. If you want
+to use a different template or want to pass some extra arguments, you need to override
+`fun showLoginForm(call: HttpCall)` method and call `call.render()` method yourself.
 
-After a successful login, users are redirected to the original 
-[intended route](/docs/http-response#redirects). If there is no intended route, they are redirected to `/home` 
-route. If you want to redirect them to somewhere else override `fun afterLoginRedirectTo(call: HttpCall)` method.
+After a successful login, users are redirected to the original [intended route](/docs/http-response#redirects).
+If there is no intended route, they are redirected to `/home` route. If you want to redirect them to
+somewhere else override `fun afterLoginRedirectTo(call: HttpCall)` method.
 
-Similarly, users are redirected to `/` route after they logout. You can change the redirected route by overriding
-`fun afterLogoutRedirectTo(call: HttpCall)` method.
+Similarly, users are redirected to `/` route after they logout. You can change the redirected route
+by overriding `fun afterLogoutRedirectTo(call: HttpCall)` method.
 
 - `controllers/auth/RegisterController.kt`
 
 Handles user registration.
 
-`auth/rgister.peb` template is used for showing the registration form. If you want to use a different
-template or want to pass some extra arguments, you need to override `fun showRegistrationForm(call: HttpCall)` 
-method and call `call.render()` method yourself.
+`auth/rgister.peb` template is used for showing the registration form. If you want to use
+a different template or want to pass some extra arguments, you need to override
+`fun showRegistrationForm(call: HttpCall)` method and call `call.render()`
+method yourself.
 
-After a successful registration, a new `User` record is inserted in `UsersTable` and the user is redirected 
-to `/login` route. If you want to redirect them to somewhere else override 
+After a successful registration, a new `User` record is inserted in `UsersTable` and the user is
+redirected to `/login` route. If you want to redirect them to somewhere else override 
 `fun afterRegisterRedirectTo(call: HttpCall)` method.
 
 - `controllers/auth/ForgotPasswordController.kt`
 
-Handles password reset requests by asking users for the email address that is associated with the account that they
-want to reset the password for. The template that contains the form is `auth.passwords.reset_email`, which you can 
-override in `fun showResetLinkRequestForm(call: HttpCall)` method.
+Handles password reset requests by asking users for the email address that is associated with the account that
+they would like to reset the password for. The template that contains the form is `auth.passwords.reset_email`,
+which you can override in `fun showResetLinkRequestForm(call: HttpCall)` method.
 
-After verification, a password reset email containing a signed link is sent to the user and are redirected back to
-the same page containing the form with a flashed successful message. If you want to redirect them to somewhere else,
+After verification, a password reset email containing a signed link is sent to the user and are then redirected to the
+same page containing the form but with a flashed successful message. If you want to redirect them to somewhere else,
 override the `fun afterResetLinkSentRedirectTo(call: HttpCall): String?` method and return a different route.
 
 - `controllers/auth/PasswordResetController.kt`
 
-Handles actual password resets by showing a reset form asking the user for a new password. The form is rendered 
-using `auth/passwords/reset` template. `email` and `token` parameters are passed to the template when rendering.
+Handles actual password resets by showing a reset form asking the user for a new password. The form is rendered using
+`auth/passwords/reset` template. Both `email` and `token` parameters are passed to the template when rendering.
 
-After a successful reset, users are **automatically logged** in and then redirected to `/` route. If you want to 
-redirect them to somewhere else override `fun afterResetRedirectTo(call: HttpCall)` method.
+After the successful reset, users are **automatically logged** in and then redirected to `/` route. If you
+want to redirect them to somewhere else override `fun afterResetRedirectTo(call: HttpCall)` method.
 
 - `controllers/auth/EmailVerificationController.kt`
 
 Handles user's email verification process.
 
-If a user's email is already verified, it redirects the user to `/home` route. It also redirects to the same route
-after a successful verification as well as after (re)sending a verification email. Override 
+If a user's email is already verified, it redirects the user to `/home` route. It also redirects to the same
+`/home` route after a successful verification as well as after (re)sending a verification email. Override 
 `fun ifVerifiedRedirectTo(call: HttpCall): String` method if you want to route them to somewhere else.
 
 - `controllers/HomeController.kt`
 
-An example controller that just renders a `home` template. You can also see how a `VerifiedEmailOnlyMiddleware` is
-applied to this controller. This means only verified users can access this route that this controller is associated
-with. If you want to see this controller in action you need to reference it from one of your routes.
+An example controller that just renders a `home` template.
+
+You can also see how a `VerifiedEmailOnlyMiddleware` is applied to this controller. This means only
+verified users can access this controller. If you want to see this controller in action you
+need to reference it from one of [your routes](/docs/routing).
 
-Feel free to modify this controller further or remove it completely; it is not referenced by any routes by default.
+Feel free to modify this controller further or remove it completely; it is not referenced by any
+routes by default.
 
 </div>