Customising The Login Page

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Web Client Customization

Table of Contents

• 1 Introduction


• 2 Custom Login Page


• 3 Custom I18N String


• 4 Overriding JSF configuration


• 5 Custom Managed Bean


• 6 Packaging and deploying

Introduction

This example shows how the login page and backing bean can be customised using features since Alfresco 1.3.

We will customise the login.jsp itself by adding the version number under the login credentials panel and the custom managed bean will log who logged in and out and when.

This example is also included as the CustomLogin sample in the SDK.

Custom Login Page

The first step is to copy the default login page to your jsp/extension folder. If the 'extension' folder does not exist in tomcat/webapps/alfresco/jsp/, just create it.

We need to pull in the properties file holding the version numbers and also the custom properties file which will hold our custom version label.

To do this, add the following to the top of your login.jsp (but after the taglib definition for the f prefix). A good place is probably right after the body tag.

<f:loadBundle basename='alfresco.version' var='version'/>
<f:loadBundle basename='alfresco.extension.webclient' var='customMsg'/>

Next locate the div element with an id of 'no-cookies' and paste the following code just above it.

   <h:outputText value='#{customMsg.current_version}' />: 
   <h:outputText value='#{version['version.edition']} - v#{version['version.major']}.#{version['version.minor']}.#{version['version.revision']}' />  
   <h:outputText rendered='#{version['version.label'] != ''}' value='(#{version['version.label']})'/>        

This will output the following string (at the time of writing):

Current Version: Community Network - v1.3.0 (dev)

Custom I18N String

Create a webclient.properties file in the alfresco.extension package and save it with the following contents.

current_version=Current Version

Overriding JSF configuration

To use the custom login page we just created there are a few places we have to configure to make sure the custom page gets picked up.

Firstly, the login-page element in web-client-config.xml has to be overridden. To do this add the following config to your web-client-config-custom.xml

<config>
   <client>
      <login-page>/jsp/extension/login.jsp</login-page>
   </client>
</config>

There are also two JSF navigation rules to override, failure to change these will make the application go back to the original login page.

One rule defines where to go to after a user logs out and the other defines where to go when a user has successfully logged in. Create a file named faces-config.xml (in the webapps/alfresco/META-INF/ folder) and populate it with the following.

<faces-config>

   <navigation-rule>
      <from-view-id>/jsp/*</from-view-id>
      <navigation-case>
         <from-outcome>logout</from-outcome>
         <to-view-id>/jsp/extension/login.jsp</to-view-id>
      </navigation-case>
   </navigation-rule>
   
   <navigation-rule>
      <from-view-id>/jsp/extension/login.jsp</from-view-id>
      <navigation-case>
         <from-outcome>success</from-outcome>
         <to-view-id>/jsp/browse/browse.jsp</to-view-id>
      </navigation-case>
   </navigation-rule>

</faces-config>

Note that if you are using Alfresco 3.x, the from-outcome from org.alfresco.web.bean.LoginBean#login() is 'myalfresco' by default. If you set your 'Start Location' in user preferences to any value other than 'My Alfresco,' then the from-outcome will be 'success.' You may need to add a third navigation rule to capture both the 'myalfresco' and 'success' outcomes.

A note about the faces-config.xml file. In this case we're overriding Alfresco's JSF navigation rules, which requires that the above configuration be put into META-INF/face-config.xml file. If we were overriding an an Alfresco JSF component declaration we would have made the change to WEB-INF/faces-config-custom.xml. (See [http://klungvik.com/index.php/2009/alfresco-the-first-lessons-learned/])

You may also override the navigation by changing the default setting in the alfresco/WEB-INF/faces-config-navigation.xml using the example above as well. Note that this will change it for all users and is a change to the default behavior.  If you upgrade or reinstall Alfresco this change maybe overwritten.

Custom Managed Bean

The final step is to implement and register the custom managed bean.

Create a Java class named 'CustomLoginBean' which extends the default Login bean and place it in the org.alfresco.sample package.

Override the login() and logout() methods and add logging calls to show who has just logged in or out. The body of your CustomLoginBean.java file should look like similar to the example below.

public class CustomLoginBean extends LoginBean
{
   private static final Log logger = LogFactory.getLog(CustomLoginBean.class);

   @Override
   public String login()
   {
      String outcome = super.login();
      
      // log to the console who logged in and when
      String username = this.getUsername();
      if (username == null)
      {
         username = 'Guest';
      }
      
      logger.info(username + ' has logged in at ' + new Date());
      
      return outcome;
   }

   @Override
   public String logout()
   {
      String outcome = super.logout();
      
      // log to the console who logged out and when
      String username = this.getUsername();
      if (username == null)
      {
         username = 'Guest';
      }
      
      logger.info(username + ' logged out at ' + new Date());
      
      return outcome;
   }
}

In the previous section we left all the value binding expressions for LoginBean unchanged i.e. #{LoginBean.username}. In order for our custom bean to get called and perform the logging we need to override the managed bean definition for LoginBean.

To do this we need to supply a faces-config-custom.xml file and place it in the WEB-INF folder of the web application. Copy the LoginBean definition from faces-config-beans.xml, paste it into your faces-config-custom.xml and update the managed-bean-class.

When you're done your faces-config-custom.xml should look like the following:

<faces-config>

   <managed-bean>
      <description>
         The bean that backs up the Login screen
      </description>
      <managed-bean-name>LoginBean</managed-bean-name>
      <managed-bean-class>org.alfresco.sample.CustomLoginBean</managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
      <managed-property>
         <property-name>nodeService</property-name>
         <value>#{NodeService}</value>
      </managed-property>
      <managed-property>
         <property-name>authenticationService</property-name>
         <value>#{AuthenticationService}</value>
      </managed-property>
      <managed-property>
         <property-name>personService</property-name>
         <value>#{PersonService}</value>
      </managed-property>
      <managed-property>
         <property-name>navigator</property-name>
         <value>#{NavigationBean}</value>
      </managed-property>
      <managed-property>
         <property-name>browseBean</property-name>
         <value>#{BrowseBean}</value>
      </managed-property>
      <managed-property>
         <property-name>userPreferencesBean</property-name>
         <value>#{UserPreferencesBean}</value>
      </managed-property>
   </managed-bean>
   
</faces-config>

Packaging and deploying

Refer to the Packaging And Deploying Extensions guide for instructions on packaging and deploying your extension.

Alternatively, you can download the SDK from sourceforge or get the latest code from SVN where you'll find a prepared CustomLogin sample.
--Jean 03:21, 3 March 2008 (UTC)