| Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Ensemble 10g Release 3 (10.3.0.1.0) E14115-02 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Ensemble 10g Release 3 (10.3.0.1.0) E14115-02 |
|
Previous |
Next |
To display custom pages to the user at different steps during Oracle WebCenter Ensemble login and logout, you can customize a range of steps in the login process.
You can create custom login, logout, error and interstitial pages and configure Oracle WebCenter Ensemble to display them at specific points in the login/logout process. (An interstitial page is a page that appears before the expected content page.) Custom pages are hosted on a proxied application server, called the login resource. For details, see the following sections:
The pre-login page is an interstitial page displayed before the login form.
The pre-login page could display an important message about availability or new functionality. The pre-login page can also be used to display a custom message to users who are part of an experience definition that is blocked from accessing the requested resource. In the example below, the pre-login page (preinterstitialpage.jsp) displays a message about server maintenance. This page uses the pt:common.error tag to display any errors within the page, and the pt:core.html tag to display the submit button.
<%@page contentType="text/html;charset=UTF-8"%> <HTML> <BODY> <SPAN xlmns:pt='http://www.plumtree.com/xmlschemas/ptui/'> <FORM action="./processpreinterstitialpage.jsp" method="POST"> <P> <TABLE> <TR><TD> <CENTER><B>Maintenance Updates</B></CENTER> </TD></TR> <TR><TD> This server will be going down for maintenance on 5/28/07 at 6:37PM and 24 seconds.<BR> <pt:common.error> <P><B><FONT color="red"><pt:logic.value pt:value="$#10.ptmsgs_login"/></FONT>:</B> <pt:common.errortext/> </P> </pt:common.error> </TD></TR> <TR><TD> <CENTER> <pt:core.html pt:tag="input" type="submit" value="$#2.ptmsgs_samples"/> </CENTER> </TD></TR> </TABLE> </FORM> </SPAN> </BODY> </HTML>
When the user clicks the submit button, the processing page shown below (processpreinterstitialpage.jsp) sets the runner_pre_interstitial_complete header to true, which directs the browser to the login page. It also provides error text for the error page in case processing fails.
<%@page contentType="text/html;charset=UTF-8"%> <HTML> <BODY> <% out.println( "<P>Ensemble pre-login interstitial page processing login completion error. Contact your system administrator.</P>"); response.addHeader( "runner_pre_interstitial_complete", "true") %> </BODY> </HTML>
The login page allows you to customize the Oracle WebCenter Ensemble login form display and functionality.
The pt:ensemble.authsourcedata tag provides a collection of the authentication sources available for the resource. The data is stored as a collection, and each item in the collection is a data object containing information about the authentication source (prefix, name, description) accessible through the data object dot notation ($authsource.name). You can use additional adaptive tags to iterate through the collection and allow the user to select the appropriate choice, as shown in the example that follows.
The example below (loginpage.jsp) displays a banner and a login form. The login form posts back to the page, which sets the appropriate headers to authenticate with the resource (runner_username, runner_password, runner_authentication_provider, and runner_portal_authentication_source). This page uses the pt:ensemble.authsourcedata tag, as well as several other adaptive tags to handle logic and display. For details on adaptive tags, see Adaptive Tags.
<%@ page import="java.net.*"%>
<%@page contentType="text/html;charset=UTF-8"%>
<%
String username = request.getParameter( "username" );
String password = request.getParameter( "password" );
if(username != null && password != null)
{
response.addHeader( "runner_username", username);
response.addHeader( "runner_password", password);
}
String authsource = request.getParameter( "authsource" );
if ( authsource != null
{
response.addHeader( "runner_authentication_provider", "portal");
response.addHeader( "runner_portal_authentication_source", authsource );
}
%>
<html>
<head>
<link rel='stylesheet' type='text/css' href='css/main.css'/>
</head>
<body>
<span xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'>
<table class="banner" cellpadding="0" cellspacing="0">
<tr>
<td class="appLogo"></htm:td>
<td class="liquid"></htm:td>
</tr>
</table>
<br/>
<!-- Welcome message: -->
<font face="arial" size=2> <pt:logic.value pt:value="$#3.ptmsgs_login"/><br> <pt:logic.value pt:value="$#7.ptmsgs_login"/> </font>
<br/>
<%
String errorValue = request.getHeader("runner_error_last_error_message" );
if(errorValue != null)
{
out.println("<br>");
out.println("<font face=\"arial\" color=\"0000AA\" size=2>");
out.println("<pt:logic.value pt:value=\"$#8.ptmsgs_login\"/><br>");
out.println("</font>");
out.println("<font face=\"arial\" color=\"AA0000\" size=2>");
out.println("<b>");
out.println(errorValue);
out.println("</b>");
out.println("</font>");
out.println("<br>");
}
%>
<br/>
<pt:common.error>
<P><B><FONT color="red"><pt:logic.value pt:value="$#10.ptmsgs_login"/></FONT>:</B>
<pt:common.errortext/>
</pt:common.error>
<!-- Login form: -->
<FORM name="loginform" action="loginpage.jsp" method="POST">
<table>
<tr><!-- Username -->
<td align="right"><font face="arial" size=2>
<pt:logic.value pt:value="$#0.ptmsgs_login"/>
</font></td>
<td align="left"><font face="arial" size=2>
<!-- inputs and password inputs are of slightly different length in IE. This can be fixed with CSS.-->
<pt:core.html pt:tag="input" type="text" name="username" alt="$#0.ptmsgs_login" size="30" value="${param["username"]}"/>
</font> </td> </tr>
<tr><!-- Password -->
<td align="right"><font face="arial" size=2>
<pt:logic.value pt:value="$#1.ptmsgs_login"/>
</font></td>
<td align="left"><font face="arial" size=2>
<pt:core.html pt:tag="input" onkeypress="return submitform(event)" type="password"
name="password" size="30" alt="$#1.ptmsgs_login" value="${param["password"]}"/>
</font> </td> </tr>
<!-- Auth sources -->
<pt:ensemble.authsourcedata pt:key="authsources"/>
<pt:logic.collectionlength pt:data="authsources" pt:key="authsourceslength"/>
<pt:logic.intexpr pt:expr="($authsourceslength)>0" pt:key="hasvalues"/>
<pt:logic.if pt:expr="$hasvalues">
<pt:logic.iftrue>
<pt:logic.intexpr pt:expr="($authsourceslength)>1" pt:key="hasmultvalues"/>
<pt:logic.if pt:expr="$hasmultvalues">
<pt:logic.iftrue>
<tr><!--Authentication Source:-->
<td align="right" width="40%" colspan="1"><font face="arial" size=2>
<pt:logic.value pt:value="$#5.ptmsgs_login"/>
</font></td>
<td align="left" width="40%" colspan="1"><font face="arial" size=2>
<select name="authsource" onkeypress="return submitform(event)" lang="en">
<pt:logic.foreach pt:data="authsources" pt:var="auth">
<pt:core.html pt:tag="option" value="$auth.prefix" alt="$auth.description"> <pt:logic.value pt:value="$auth.name"/></pt:core.html>
</pt:logic.foreach>
</select>
</td> </tr>
</pt:logic.iftrue>
<pt:logic.iffalse>
<!-- Hidden input for single auth source. -->
<pt:logic.foreach pt:data="authsources" pt:var="auth">
<pt:core.html pt:tag="input" type="hidden" name="authsource" alt="" value="$auth.prefix"/>
</pt:logic.foreach>
</pt:logic.iffalse>
</pt:logic.if>
</pt:logic.iftrue>
<pt:logic.iffalse><!-- Otherwise no auth sources for this resource. --></pt:logic.iffalse>
</pt:logic.if>
<tr><!-- Login -->
<td align="right"></td>
<td align="left">
<pt:core.html pt:tag="input" type="submit" value="$#2.ptmsgs_login"/>
</td>
</tr></table>
</FORM>
<br>
<SCRIPT language="JavaScript">
function submitform(evt)
{
evt = (evt) ? evt : event;
var charCode = (evt.charCode) ? evt.charCode : ((evt.which) ? evt.which : evt.keyCode);
if (charCode == 13 || charCode == 3)
{
document.loginform.submit();
}
return true;
}
</SCRIPT
The login page can use the pt:ensemble.loginlink tag to retrieve the external URL prefix defined for the resource. For example, if the external URL prefix of the resource is http://www.ensemble.com/app/ and the desired page after login is http://www.ensemble.com/app/pages/mainpage.html, then the full login link would be made by adding pages/mainpage.html to the login link prefix as shown in the sample code below.
<pt:ensemble.loginlink pt:level="4" pt:key="loginurlprefix"/> var loginLink = "<pt:logic.value pt:value="$loginurlprefix"/>" + "pages/mainpage.html";
A custom error page can be displayed if there is an error in the Oracle WebCenter Ensemble login process.
The pt:common.error, errortext and errorcodes tags allow you to insert Oracle WebCenter Ensemble error information into a custom error page.
|
Note: If these tags are included on a page, errors will no longer be displayed in the normal error location and will not be available after the page has been displayed. |
By itself, the pt:common.errortext tag displays only the first error message, or the custom error message defined in the pt:text attribute. Other errors, as well as exception stack traces and extended error messages, will be ignored. Combined with the pt:common.errorcodes tag and pt:logic tags, the pt:common.errortext tag can be used to display all error codes in memory. (If the errors have already been displayed, no error codes will be available.)
The example below (errorpage.jsp) illustrates how to retrieve and display a collection of errors and how to replace system errors with a custom error message. This example uses pt:logic tags to display the error collection. For details on adaptive tags, see Adaptive Tags.
<%@page contentType="text/html;charset=UTF-8"%> <HTML> <head> <link rel='stylesheet' type='text/css' href='css/main.css'/> </head> <BODY> <SPAN xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'> <table class="banner" cellpadding="0" cellspacing="0"> <tr> <td class="appLogo"></htm:td> <td class="liquid"></htm:td> </tr> </table> <br/> <P><pt:logic.value pt:value="$#11.ptmsgs_login"/> </P> <P> <pt:common.errorcode pt:key="errorcodes"/> <pt:logic.foreach pt:data="errorcodes" pt:var="code"> <pt:common.errortext/> <br> <pt:logic.value pt:value="$#12.ptmsgs_login"/><pt:logic.value pt:value="$code"/> <br> <!-- This is how you would override a specific error with a new message. --> <!-- <pt:logic.intexpr pt:expr="($code)==2010" pt:key="isrequestedresource"/> <pt:logic.if pt:expr="$isrequestedresource"> <pt:logic.iftrue> <pt:common.errortext pt:text="The requested resource is not in the resource map. This is a custom error message."/> </pt:logic.iftrue> <pt:logic.iffalse> <pt:common.errortext/> </pt:logic.iffalse> </pt:logic.if> --> </pt:logic.foreach> </P> <P><pt:logic.value pt:value="$#13.ptmsgs_login"/></P> </SPAN> </BODY> </HTML>
The post-login page is an interstitial page that can be used to display messages or gather input from the user after the login form is submitted.
The example below (interstitialpage.jsp) displays a user agreement that requires approval. This page uses adaptive tags to display errors and form elements. For details on adaptive tags, see Adaptive Tags.
<%@page contentType="text/html;charset=UTF-8"%>
<HTML>
<BODY>
<SPAN xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'>
<FORM action="./processinterstitialpage.jsp" method="POST">
<P>
<TABLE>
<TR>
<TD><CENTER><B><pt:logic.value pt:value="$#3.ptmsgs_samples"/></B></CENTER>
</TD></TR>
<TR>
<TD>
<TEXTAREA name="thetext" rows="15" cols="80">
Owner: This web site belongs to Sample Company United States, Inc. Sample Company may change or terminate this web site or any parts thereof.
Agreement: Your use of this web site constitutes your agreement with Sample Company to operate under the auspices of, and to act in
concordance with, these Terms and Conditions of use. By clicking "Agree" below, you are confirming your agreement, which will also be confirmed
by merely accessing this web site beyond this page.
Continuing Agreement: Sample Company may modify or alter these Usage Terms at any time. Further usage of this web site after the terms have
been modified confirms your agreement with the modified Usage Terms.
Use of Materials: Sample Company owns all of the data on this web site or has secured permission from a third party to use the material. Usage of
this material in any way outside this web site is strictly prohibited.
</TEXTAREA>
<pt:common.error>
<P>
<B><FONT color="red"><pt:logic.value pt:value="$#10.ptmsgs_login"/></FONT>:</B>
<pt:common.errortext/>
</P>
</pt:common.error>
<P>
<pt:core.html pt:tag="input" type="checkbox" name="agreement" alt="$#0.ptmsgs_samples" value="agree"/>
<pt:logic.value pt:value="$#1.ptmsgs_samples"/>
<pt:core.html pt:tag="input" type="submit" value="$#2.ptmsgs_samples"/>
</P>
</TD>
</TR>
</TABLE></SPAN></BODY></HTML>
When the user clicks the submit button, the processing page (processinterstitialpage.jsp) sets the runner_post_interstitial_complete header to true, which directs the browser to the resource. If the user did not select Accept on the post-login page, a message is displayed including a link back to the agreement. This file also provides error text for the error page in case processing fails.
<%@page contentType="text/html;charset=UTF-8"%>
<HTML>
<BODY>
<SPAN xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'>
<pt:common.error>
<P>
<B><FONT color="red"><pt:logic.value pt:value="$#10.ptmsgs_login"/></FONT>:</B>
<pt:common.errortext/>
</P>
</pt:common.error>
<%
if (request.getParameter( "agreement" ) != null)
{
out.println( "<P>Ensemble post-login interstitial page processing login completion error.
Contact your system administrator.</P>");
response.addHeader( "runner_post_interstitial_complete", "true");
session.invalidate();
}
else
{
out.println( "<P>If you do not consent to the web site usage agreement, you will not be able to access any content.</P>");
out.println( "<P>Click <A href=\"./interstitialpage.jsp\">here</a> to view the usage agreement again, or ");
out.println( "you can use <A href=\"http://www.google.com\">Google</a> to find another web site.</P>");
}
%>
</SPAN></BODY></HTML>
The post-logout page is displayed when a user logs out of the resource.
In most cases, this page simply displays a message that informs users that they have been logged out of the system. The pt:ensemble.ssologout tag can be added to any proxied page to display a link that logs out of all resources and directs the browser to the post-logout page associated with the user's experience definition. For details on adaptive tags, see Adaptive Tags.
Custom login resources and pages are configured through the associated experience definition.
To define the login resource, create a resource and select Is login resource on the General tab. (If the application server is already registered as a resource in Oracle WebCenter Ensemble, confirm that the login resource setting is enabled.) To deploy custom pages in Oracle WebCenter Ensemble, edit the associated experience definition. On the Log In Settings page, define the login resource and any of the following custom pages:
| Custom Page | Description |
|---|---|
| Pre-login page | Displayed before attempting to authenticate the user. |
| Login page | Displayed only when form authentication is being used; provides the form for login. |
| Post-login page | Displayed to the user after successful authentication and before the resource is accessed. |
| Error page | Displayed if there is an error in the login process. |
| Post-logout page | Displayed after the user logs out of the resource. |
|
Note: The settings in the experience definition are used regardless of the authenticator used to access a resource. If the required authenticator uses a login page and there is no login page configured in the experience definition, the user will be presented with a blank page and will be unable to authenticate. For details, see the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Ensemble Chapter 8, 'Experience Definitions'. |
Communication between login resource pages and Oracle WebCenter Ensemble is done using HTTP headers
The following table describes the available headers, including how and when they are used. Error and Post-logout pages are considered terminal pages and do not communicate with Oracle WebCenter Ensemble using headers.
Table 3-1 Oracle WebCenter Ensemble Login Headers
| Property Type | Property Value | Property Description |
|---|---|---|
|
Pre-login |
runner_pre_interstitial_complete |
true indicates that the pre-login page has completed successfully. Oracle WebCenter Ensemble proceeds to the login page. false (or no header) means the page has not completed successfully. The pre-login page is displayed again. |
|
Login |
runner_username |
The user name used to authenticate the user. |
|
Login |
runner_password |
The password used to authenticate the user. |
|
Login |
runner_authentication_provider |
The provider for authentication. The only valid value is portal. If the header is not present, the provider defaults to portal. |
|
Login |
runner_portal_authentication_source |
The authentication source against which to authenticate the user. This is the same as the authentication source the user would use to log in to Oracle WebCenter Ensemble. |
|
Post-login |
runner_post_interstitial_complete |
true indicates that the post-login page has completed successfully. Oracle WebCenter Ensemble proceeds to the resource. false (or no header) means the page has not completed successfully. The post-login page is displayed again. |
