Login forms and pages

2019-10-07 15:08:00.0
Developers

By default kademi has two login forms:

  • a small drop down login form accessed from the menu
  • a login page which is displayed whenever the user attempts to access a protected resource which they cant access, either because they're not logged in or because they are but dont have access rights

Login forms

To create your own login forms you should do the following

  1. include theme/js/jquery.user.js in your page or template (please check for later version updates)
  2. create a html form with two inputs with names email and password, and a submit button. Note that the form attributes, layout and ID attributes dont matter, its only the input names which are referenced.
  3. initialise the user plugin for the form, setting appropriate values for callbacks, next url, etc

 

Note that initialising the user plugin isnt just for login. It also initialises javascript variables from cookies, applies user state classes to make things visible or hidden depending on whether there is a user logged in, and provides a logout function.

 

Step 1 - Include jquery.user.js

		

So far so good...

 

Step 2 - Create the form

Here's a simple bootstrap form:

		

 

Step 3 - Initialise the jquery.user plugin

		

 

Logout

The plugin has the default logout selector of ".logout", which is configured in the logoutSelector property. Whenever a matching element is clicked the doLogout function is called:

		$(config.logoutSelector).click(function() {
		doLogout();
		});

 

Logging in with ajax

If you dont want to use the jquery.user plugin, you can create an ajax request to login as follows:

URL: /.dologin
Method: POST

Parameters:

_loginPassword YYY
_loginUserName XXX

 

The response is JSON like this. Be sure to check the status property

		{"data":{
		"name":"XXX",
		"href":"/users/XXX/public",
		"userName":"XXX",
		"userId":99999,
		"photoHash": "0f672c686fdf25f1957fca84e4b1f5c944b5cadf"},
		"fieldMessages":[],
		"messages":[],
		"nextHref":"",
		"status":true
		}

 

Response properties

Property Meaning
name The publicly viewable name of this user, like a nickname
href Path to the publicly accessible profile page
userName The unique identifier for this user
userId The internal unique identifier
photoHash The hash of the user's profile photo. Can be loaded from /_hashes/files/XXX
fieldMessages Any login validation messages specific to fields, ie username or password. Standard property of JsonResult
messages Any validation messages not specific to a field, standard property of JsonResult
nextHref The next page to go to if there is a server side page workflow in progress, standard property of JsonResult
status True if the login was successful

 

Login template

Whenever a user attempts to access a secure resource and is not authorised the login template is rendered. The template is /theme/apps/login/login.html and you can see the default bootstrap 3.2 login template here

Since the login template is rendered in places of the actual page, bookmarks are accessible without redirects to a specific login page. To prevent caching of the login template the response is returned with 400 HTTP status code.

Recommendations on login pages and redirects

A common pattern is to redirect users away from a page when they are not authorised to access it. We recommend against this practise in Kademi.

Instead we recommend having an explicit login and/or registration process (eg on a landing page) and also have a login template which is displayed on access to a secure resource.

The advantage of a login template is that it can display an appropriate message when there is a logged in user who is being denied access, versus the situation where the user simply has not logged in. Even if you have an "all or nothing" permission strategy this is preferable because it will help you diagnose incorrect permissions. And in most cases websites evolve from all-or-nothing to have at least a few role dependent resources over time.