Creating a Sign-In Form

NOTE  This section only applies when Workplace is configured for application-managed authentication. For container-managed authentication where single sign-on will not be used and the FORM auth method is configured, the ContainerLogin.jsp file is displayed as the login page. You can modify presentation elements of this page to meet your custom application requirements, as long as the form field names and form action name, as dictated by Servlet 2.3 specification, remain unchanged. In addition, the ContainerError.jsp file is used to trigger the addition of an sign-in error message to the presentation of ContainerLogin.jsp. This logic must remain intact if user feedback is desired when the user enters the wrong password.

This topic explains how to use the Toolkit to generate an HTML-based sign-in form that's rendered by a Java™Server Pages (JSP) page. The bulk of the sign-in functionality is handled by WcmSignInModule, which includes the sign-in event handler. Its superclass, WcmUiModule, provides methods for configuring and initiating JSP-based rendering.

The following steps and diagram show one implementation for generating a sign-in form using JSP-based rendering. When a user makes the initial request for the Web application, the controller calls an implemented method (getSignInPage) to get the name of the event sign-in page, then loads it. At this point, the following steps occur:

  1. In the event JSP page, the WcmSignInModule subclass is instantiated, and the controller's handleEvent( ) method is called.
  2. The controller calls WcmSignInModule.initialize( ).
  3. WcmSignInModule.initialize( ) calls the setJSP(...) method, derived from WcmUiModule. This method sets the JSP page that will render the sign-in form.
  4. The controller does a server-side redirect to the UI JSP page that initiates rendering of the sign-in page.
  5. WcmSignIn.jsp calls WcmUI.render(...).
  6. WcmUI.render(...) detects that a JSP page has been set and calls WcmUiModule.renderJSP( ).
  7. WcmUiModule passes the path of the rendering JSP to the controller's serverSideInclude( ) method.
  8. The JSP is loaded, rendering the sign-in form, using the FORM tag and other static HTML tags that define the appearance of the form. The rendering JSP also calls get accessor methods on the com.filenet.wcm.toolkit.server.ui.WcmSignInModule object, and retrieves localized UI strings from the WcmString object.

sign-in form

To create a sign-in form using JSP-based rendering:

  1. Subclass com.filenet.wcm.toolkit.server.ui.WcmSignInModule, and override the initialize( ) method similarly to the code snippet below. Note that the setJSP(...) method, derived from WcmUiModule, is called, specifying the custom JSP page that renders the sign-in form.
    package com.filenet.cus.apps.server.ui;
    ...

    public class CusSignInModule extends
             com.filenet.wcm.toolkit.server.ui.WcmSignInModule
    {
       public void initialize() throws Exception
       {
          super.initialize();
          setJSP("apps.server.ui/CusSignInModule.jsp");
       }

       ...
    }
  2. Create a JSP page that renders the HTML-based sign-in form. This JSP page is specified in the setJSP(...) call in your WcmSignInModule subclass.

    NOTE  This JSP page works in conjunction with the UI JSP page that initiates rendering, described below.

    Use code similar to the following example. In the page directive and in the WcmJSPModule.getCurrentModule(...) statement, specify the CusSignInModule subclass that you created in the previous step.

    <%@ page import="com.filenet.cus.apps.server.ui.CusSignInModule,
       com.filenet.wcm.toolkit.server.ui.*,
       com.filenet.wcm.toolkit.util.*,
       com.filenet.wcm.toolkit.server.base.*" %>
    <%
       CusSignInModule m = (CusSignInModule)WcmJSPModule.getCurrentModule(request);
       String errorMessage = m.getErrorMessage();
       String sOnKeyDown = "";
       String formAction = m.getEventUrl("SignIn");
       String formName = m.getFormName();
       String lastUser = m.getLastUser();
       WcmString name = new WcmString("server.WcmSignInModule_jsp.name", "name");
       WcmString password = new WcmString("server.WcmSignInModule_jsp.password", "password");
       if ( lastUser == null ) lastUser="";
    %>

    <form action='<%=formAction%>' method='POST' name='<%=formName%>'>
       <table align='center' cellSpacing='0' cellPadding='0' width='475' border='0' height='315'>
          <tbody>
             <tr>
                <td class='wcmFormText' background='images/web/common/BrightspireSplash.gif' width='475' height='315'>
                   <input type='image' src='images/web/common/Spacer.gif' border='0' height='0' width='0' style='height: 0; width: 0; '><br>
                   <input onkeydown='<%=sOnKeyDown%>' class='wcmFormInput' type='text' id='userId' name='userId' value='<%=lastUser%>' size='30'><br>
                   <b><%=name.toString()%></b%><br>
                   <input onkeydown='<%=sOnKeyDown%>' class='wcmFormInput' type='password' name='password' size='30' autocomplete='off'><br>
                   <b><%=password.toString()%></b>
                   <br><br>
                   <a class='wcmLink' href='javascript:document.loginForm.submit()'><b><%=m.SUBMIT_LABEL%></b></a>
                   | <a class='wcmLink' href='<%=m.getEventUrl("Reset")%>' <b><%=m.RESET_LABEL%></b></a>
                </td>
             </tr>
          </tbody>
       </table>
    </form>
  3. Create an event JSP page.

    In the jsp:useBean action, specify your WcmSignInModule subclass. For example:

    ...
    <%-- UI Beans --%>
    <jsp:useBean
       id="signInModule"
       class="com.filenet.cus.apps.server.ui.CusSignInModule"
       scope="request"/>
       <jsp:setProperty name="signInModule" property="name" value="signInModule" />
    ...
    <%
       controller.configurePage(application, request);
       controller.registerModule(signInModule);
       controller.handleEvent(application, request, response, true);
    %>
    ...
  4. Create a UI JSP page that initiates rendering of the SignIn page.

    In the WcmUi.render statement, specify the variable that you used in the event JSP page (signInModule). For example:

    ...
    <html>
       <head>
       <%
          WcmString heading = new WcmString("server.WcmSignIn_jsp.heading", "Sign In");
          WcmWorkplaceUi.renderHeaders(request, out, false, heading, null);
       %>
       </head>

       <body class="wcmBody" bgcolor="white">
          <% WcmUi.render(request, "signInModule", out); %>
       </body>
    </html>

    Give this page the same name as its corresponding event JSP page.

  5. In your controller implementation (Step 2: Configure ConfigurableController), set a sign-in page property and include a getSignInPage( ) accessor method.

    ...
    private static final String SIGNIN_URL = "CusSignIn.jsp";
    ...

    public String getSignInPage()
    {
       return(SIGNIN_URL);
    }

    ...