Login.Basic Setup

{toc}

This tutorial catalogs which pages you need to set up and the Snippets that belong on each page. At the end of this tutorial, you will have a setup which will allow users to log in via the front-end of your website, but the {color:red}users must be manually created by an admin in the manager{color}. There is a [separate turorial|Login.Request Membership] for establishing a process where users can request membership themselves.

Even a basic setup of a login portal involves a lot of inter-related parts, and the setup demonstrated here puts pretty much everything on its own page. A cleaner implementation might involve putting some of the functions listed below inside chunks or templates instead of on their own dedicated pages, but this page should give enough information to get a login portal established.

{tip}
All the pages here use a sample *page_id* for reference.
{tip}

----
h2. Create the Required Pages

Before we add all the Snippets that do all the dirty work, let's first add the following *5* pages to your MODx Revo site:

* *Login Page (1)* : the page containing your login form
* *Forgot Password (2)* : the page where users can go when they forgot their password
* *Reset Password Handler (3)* : the hidden page that will actually do the resetting of the password
* *Members Home Page (4)* : the secret clubhouse, available only to valid members
* *Come Again Soon (5)* : the page displayed upon successful logout

Next, you'll want to prepare the necessary rights and permissions for users and resources on your site.

----
h2. Create the Necessary User Groups and Resource Groups

MODx Revolution includes some pretty head-splitting granularity when it comes to [revolution20:Permissions], but here is a basic schema to get you started. (Have a look at [Making Member-Only Pages|revolution20:Making Member-Only Pages] for more detailed explanation.)

{note}
As of MODX 2.2.3, you can skip most of this step by using the *Access Wizard*, which appears when you create a new Resource Group under *Security \-> Resource Groups*. Just use the following settings:

* Name: Members
* Context: web
* Automatically Give Adminstrator Group Access: *checked*
* Create Parallel User Group: *checked*
* Automatically Give Anonymous Access: _UNCHECKED_
* Automatically Give Other User Groups Access: _blank_
{note}

If you are using an older version of MODX or you just want to enhance your understanding of the process, you can follow the manual steps below:

1. *Security \-> Resource Groups* : Create a new Resource Group for all the pages that will be available only to members.

!Create Resource Group.jpg!


2. *Security \-> Access Controls* : Create User Group named "Members". Users in the "Members" group will have access to the "Members Only" resources. Make sense?

!Create User Group.jpg!

3. On that same page (*Security \-> Access Controls*), *Right Click* the newly created "Members" User Group and select "Update User Group".

!Update User Group.jpg!


!Update User Group - Detail.jpg!

Then Add a Resource Group to this User Group. At a minimum, the Resource Group should have the following settings:

* *Resource Group:* Members Only (the one we just created)
* *Mimimum Role:* Member-9999
* *Access Policy:* Load, List and View
* *Context:* web

Then save.


4. *Security \-> Manage Users* : Create a new "member" user so we can test whether or not our login portal works.

Use a simple Username and password that you can remember; the important thing here is to make sure your new user is a member of the "Members" User Group. Head to the "Access Permissions" tab and click "Add User to Group"

!New User as Group Member.jpg!

* *User Group:* Members
* *Role:* Member

This should ensure that your new user can log in with basic permissions to look around the "Members Only" pages.

Now circle back to add the various Snippet (adjust the Snippet calls so they point to the corresponding pages on your system).

----
h2. Add Snippets to the Pages

h3. Login Page (1)

Put the following Snippet call on your login page:

{code}
[[!Login? &loginTpl=`lgnLoginTpl` &logoutTpl=`lgnLogoutTpl` &errTpl=`lgnErrTpl` &loginResourceId=`4` &logoutResourceId=`5`]]
{code}

Then save the page. You'll notice that the Snippet call has a lot of arguments -- many of those arguments reference the names of Chunks. When you installed the Login Add-on, many of these Chunks were already created for you (look under the Elements tab), but sometimes you may want to create your own Chunks and update the Snippet parameters to reference their names. In this example, we are customizing the *lgnLoginTpl* Chunk.

The Chunk that displays the login form should also include a link to the "Forgot Password" page; this is so we only display that link to users who have not logged in yet. Here is an example of the *lgnLoginTpl* Chunk, so either create a Chunk of that name or edit the existing Chunk so it matches the following:

{code}
<div class="loginForm">
<div class="loginMessage">[[+errors]]</div>
<div class="loginLogin">
<form class="loginLoginForm" action="[[~[[*id]]]]" method="post">
<fieldset class="loginLoginFieldset">
<legend class="loginLegend">[[+actionMsg]]</legend>
<label class="loginUsernameLabel">[[%login.username]]
<input class="loginUsername" type="text" name="username" />
</label>

<label class="loginPasswordLabel">[[%login.password]]
<input class="loginPassword" type="password" name="password" />
</label>
<input class="returnUrl" type="hidden" name="returnUrl" value="[[+request_uri]]" />

[[+login.recaptcha_html]]

<input class="loginLoginValue" type="hidden" name="service" value="login" />
<span class="loginLoginButton"><input type="submit" name="Login" value="[[+actionMsg]]" /></span>
</fieldset>
</form>
</div>
</div>

<a href="[[~2]]">Forgot your Password?</a>
{code}

You may choose to put the link to "Forgot your Password" inside your template and keep it out of the Chunk, it's really up to you. As long as your site is clean and organized and you're not putting chunks within chunks within chunks, then you should be Ok.

h3. Forgot Password (2)

* _Probably hidden from most menus_

This page houses the form where users can request that their password be reset. Remember: it displays the form that allows users to say that they've forgotten their password, and the "ResetPassword" Snippet is what actually resets the password.

{code}[[!ForgotPassword? &resetResourceId=`3` &tpl=`lgnForgotPassTpl`]]{code}

Here's what the flow looks like, just so you can follow what we're doing here:


!Password Reset Flow.jpg|align=center!


h3. Reset Password Handler (3)

* _Hidden from menus_

When a user requests that his/her password be reset, they are emailed a link to this page. When a valid incoming link to this page is detected, the password is reset and the user is redirected to the login page.

{code}[[!ResetPassword? &loginResourceId=`1`]]{code}


h3. Members Home Page (4)

This is the page that displays to users who have successfully logged in. This page must have restricted permissions, and the users who log in must have the corresponding permissions to access this page. You can put whatever "private" content you want on it, just make sure you update the permissions on it so that it belongs to the "Members Only" resource group -- just click on the page's "Access Permissions" or "Resource Groups" tab (depending on your version of MODX):


!Setting Access Permissions.jpg!

and check the box for "Members Only".

h3. Come Again Soon (5)

This is the page that people see after a successful logout. It needs only to contain a basic message, or perhaps a link back to the Login page:

{code}<p>Thank you for visiting! Come again soon!</p>{code}


h2. Optional


h3. Logout Page

* _WebLink_

This isn't strictly necessary per-se, but for testing it can be helpful to have a dedicated WebLink that will logout your user.

Weblink: {code}[[~1? &service=`logout`]]{code}

This is effectively the same as adding a Logout link like this to your pages:
{code}<a href="[[~1? &service=`logout`]]" title="Logout">Logout</a>{code}


h2. Possible Errors

Also make sure that your Snippets are called uncached\! Some of them will function cached, but some will not. They should use the exclamation point in front of them:

{code}
[[!Login]]
{code}

and *not*

{code}
[[Login]]
{code}