imported>Jason.nicholls: 1 revision

2015-04-30T10:59:33Z

1 revision

← Older revision	Revision as of 10:59, 30 April 2015
(No difference)

imported>Jason.nicholls: /* Examples */

2015-02-26T05:31:20Z

Examples

New page

{{DISPLAYTITLE:Custom Login Page Examples}}
[[Category:AppBoard 2.6]]
== Overview ==

This document provides some examples of modifying and producing completely custom login pages for AppBoard. For more general information about login pages and how to configure the system login page, refer to the [[appboard/2.6/builder/system_administration/login_page|Login Page]] documentation.

By default the different login page styles shipped with AppBoard are simple HTML forms that allow the user to enter the required information, and then <tt>POST</tt> it to the server so the server can authenticate and establish a session.

Typical customizations are:

* simply changing the logo graphic
* various styling changes (colours, fonts, etc...)
* addition of notices or terms & conditions
* hiding the Domain field for single-domain implementations
* making the Domain field a drop-down

== Required Fields and Submission ==

The following fields are required to log into AppBoard:

* '''login''': set to ''yes''. Typically this is a hidden field
* '''userid''': This would be a visible field to allow a user to enter their user name.
* '''password''': This would be a visible password field to allow a user to enter their password.
* '''domainSelect''': Another text input to allow a user to enter their domain.

The form is then <tt>POST</tt>ed to: <tt>/enportal/servlet/pd</tt>. Using <tt>GET</tt> is also possible but not recommended as all all requests are logged and get requests include all parameters, which means user passwords would also get logged.

== Included Login Pages ==

The login pages shipped with AppBoard all follow the same structure. A main <tt>login.jsp</tt> Java Server Page which performs browser version checking, auto-fills previous values, handles error responses, presents a HTML form for the user to complete. Along with the JSP there will be other supporting images and CSS resources.

=== Browser Type Checking ===

If a client does not meed the minimum browser requirements the login page will redirect the client to <tt>/enportal/enPortalInvalidBrowser.jsp</tt>.

This works in three parts with the default login pages. The first is to load the Edge JspConfigBean:

<jsp:useBean id="JspConfigBean" scope="application" class="com.edgetech.util.config.JspConfig">
<% config.getServletContext().setAttribute("JspConfigBean", JspConfigBean); %>
</jsp:useBean>

Then the default minimum versions are retrieved by the JSP:

// get minimum versions from the Portal server
float minIEVersion = JspConfigBean.getMinIEVersion();
float minNetscapeVersion = JspConfigBean.getMinNetscapeVersion();
float minChromeVersion = JspConfigBean.getMinChromeVersion();

And finally a check is performed to determine whether to redirect:

if ( ! ((isChrome && version < <%=minChromeVersion%>) || (isNav && version < <%=minNetscapeVersion%>) || (isIE && version < <%=minIEVersion%>)) ) {
...
} else {
// The user is trying to use an unsupported version of IE or netscape.
rootWindow.location.replace("<%=JSPUtilities.out(URLUtil.getPortalContext(), true)%>/enPortalInvalidBrowser.jsp");
}

Depending on the deployment it may be useful to remove this check, or make this check more explicit due to standard operating environment and/or applications used within the organization.

=== Auto-fill ''User Name'' and ''Domain'' Fields ===

{{Note|1=Modern browsers often will auto-fill forms on behalf of the user already making this section redundant. Also realize that even if the JSP auto-fill code is disabled the browser may still auto-fill forms. In the case of the browser auto-filling form fields it is necessary to modify the form inputs and specify the <tt>autocomplete="off"</tt> attribute.}}

If a user has previously logged into AppBoard then it's possible for the server to retrieve the users ''User Name'' and ''Domain'' last used via cookies stored in the browser. This is implemented in the default JSP pages by first loading some utilities:

<%@ page import="com.edgetech.eportal.util.*" %>
<%@ page import="com.edgetech.eportal.dispatch.DispatchUtilities" %>
<%@ page import="com.edgetech.eportal.web.JSPUtilities" %>

Then doing some lookups and setting default values for the user and domain:

// Lookup the UserID/Domain values from the cookie to pre-fill the login form
String user = DispatchUtilities.getRequestAccessor().getUserName(request);
String domain = DispatchUtilities.getRequestAccessor().getDomainName(request);
if ( (domain == null) || domain.equals("null") ) {
domain = "";
}
if ( (user == null) || user.equals("null") ) {
user = "";
}

user = JSPUtilities.toHTMLString(user);
domain = JSPUtilities.toHTMLString(domain);

=== Handling Errors ===

In the event of an un-successful login attempt it should be indicated to the user. The JSP handles this by checking for error conditions on loading:

String error_Text = request.getParameter("error");
if (error_Text == null)
{
error_Text = (String) request.getAttribute("error");
}
if (error_Text == null)
{
error_Text = "";
}

Once the page loads there is a javascript call made to <tt>error_checks</tt>. This actually performs a number of checks including the minimum browser checks. If anything is in error then <tt>setErrorState</tt> is called to modify the style of the page to indicate an error condition.

== Examples ==

{{Note|Do not modify the login pages shipped with AppBoard, refer to [[appboard/2.6/builder/system_administration/login_page#Modifying_Login_Pages|Modifying Login Pages]] for more information.}}

=== Custom Logo ===

Replacing the logo but otherwise using the shipped login pages is the easiest and most common login page customization.

# Make a copy of a shipped login page directory as mentioned in [[appboard/2.6/builder/system_administration/login_page#Modifying_Login_Pages|Modifying Login Pages]].
# The logo image for all shipped themes will be in this location: <tt>.../images/logo.png</tt>
# The default logo size is 340 x 200 for the classic login pages, and 340 x 133 for the CSS3 and Flat styles.
# The simplest approach is to create a new logo that matches the dimensions of the existing logo to avoid any layout issues. Replace the logo.png file with your new logo.
# Set the system default login page to use the new login page, refer to the [[appboard/2.6/builder/system_administration/login_page|Login Page]] documentation for more information.

=== Minimal Login Page ===

The most basic login page is a HTML form without using JSP, javascript, or images and styling. Of course this doesn't handle error checking or browser detection etc... but serves as an example of the minimum needed to write a completely custom login page:

<code>[html,N]
<html>
<head>
<title>Minimal Login Page</title>
</head>
<body>
<h1>Minimal Login Page</h1>

<form name="loginForm" method=post action="/enportal/servlet/pd">
<input name="login" type="hidden" value="yes">

<table>
<tr><td>User Name:</td> <td><input type="text" name="userid" size="28" maxlength="80"></td></tr>
<tr><td>Password:</td> <td><input type="password" name="password" size="28" maxlength="80"></td></tr>
<tr><td>Domain:</td> <td> <input type="text" name="domainSelect" size="28" maxlength="80"></td></tr>
<tr><td colspan="2" align="center"> <input type="submit" value=”login”></td></tr>
</table>
</form>
</body>
</html>
</code>

=== Setting a Default Domain ===

For implementations with a single Domain for all users the Domain field may add confusion so can be set to a particular value and even hidden.

# First make a new copy of an existing login page to start modifying.
# Edit <tt>login.jsp</tt>
## find the line line with: <tt><input type="text" id="domain" ...</tt>
## modify the <tt>value</tt> from a JSP variable to the desired value, such as:
##: <tt><input type="text" id="domain" value="'''myDomain'''" ...</tt>
# Set the system login page to use your new login page.

In addition, if this field should be completely hidden then change the <tt>type</tt> attribute from <tt>text</tt> to <tt>hidden</tt>. In this case though some additional HTML and/or CSS changes may be necessary to improve the aesthetic of the form.

Appboard/2.6/builder/system administration/login page/custom - Revision history

imported>Jason.nicholls: 1 revision

imported>Jason.nicholls: /* Examples */