The ProfileForm class has a set of submit handler methods for working with profiles. Each of these methods performs a specific form handling task, such as logging in a user. When a handler performs its task, it can perform several additional actions, including preprocessing and post-processing steps, and redirecting the user to the appropriate page depending on whether or not it encountered errors.
The following table summarizes the main handler methods of the ProfileForm class. Each of these methods is then explained in greater detail.
Method | Function |
|---|---|
| Creates a new permanent profile and sets the profile attributes to the values entered in the form. |
| Modifies the attributes of the current profile. |
| Uses the |
| Changes the password attribute of the profile to the new value entered by the user. |
| Resets the profile to a new anonymous profile and optionally expires the current session. |
handleCreate
The handleCreate method calls three other methods that you can override to add to or modify the default functionality. The preCreateUser and postCreateUser methods are protected methods with no functionality. They exist as stubs for subclasses to insert application logic before and after a persistent user is registered in the profile repository. After the preCreateUser method is called, the handler invokes the checkFormError method. This checks for errors in the form and stops processing if it finds any. The createUser method takes all the form values submitted by the user and attempts to register the user.
The first step in registering a user is verifying that the user has supplied all the required form parameters. By default, the only required form parameter is the confirmation password parameter. The checkForRequiredParameters method is invoked if the ProfileForm component’s checkForRequiredParameters property is set to true. In addition, if the ProfileForm component’s confirmPassword property is set to true, the handler requires the user to submit the form with an additional parameter that is not part of the profile definition. This parameter is the confirmation password parameter, which is used to verify the password profile attribute value supplied.
After this first pass for verification, the system checks to see if a user already exists with the given login name, and then uses the createProfileItem method to construct a MutableRepositoryItem that represents the new user. At this point, the user’s profile exists as an object, but is not yet stored in the database.
After the MutableRepositoryItem is created, it is updated to contain all the attributes the user supplies. Next, if the ProfileForm component’s checkForRequiredProperties property is set to true, the form calls the checkForRequiredProperties method to see if any of the profile attributes are required. If any profile attributes are required, it checks whether the value of any of the required profile attributes is null.
Finally, the createUser method transforms the RAM-based profile into a persistent profile stored in the profile database by invoking the addUser method. After the createUser method is finished, the handleCreate method takes the new persistent MutableRepositoryItem and updates the form handler to use that as the current profile. At this point, the session-scoped Profile object’s dataSource property is updated so that it also references the new persistent user data structure. As a final step, the postCreateUser method is called, by which time the user will be a fully registered member. As noted above, the postCreateUser does not do anything; it exists as a stub that you can override if you subclass ProfileForm.
handleLogin
The handleLogin method is similar to the handleCreate method. It, too, provides three significant methods that you can override: preLoginUser, findUser and postLoginUser. For each of the handleX methods, the preprocessing and post-processing methods have no implementation. They are stubs that you can override in subclasses. The findUser method is called after the preLoginUser method. It attempts to locate the correct user based on the login and password information that the user supplies, invoking the /atg/dynamo/security/IdentityManager to perform the verification of the login. If a user is not found with a matching login name and password, the method then attempts to find a user based on only the login name. If this process finds a user, then it is evident that the password supplied was invalid and the form indicates that in an appropriate form exception. If no user is found with a matching login, then the form indicates that the login name supplied was incorrect.
You can specify that certain properties should be copied upon login from the anonymous profile to the registered user’s account. This is useful if anonymous visitors to your site accumulate profile information that you do not want to lose when they log in. The method copyPropertiesOnLogin implements this functionality. Specify which profile attributes you want copied to the persistent profile with the propertiesToCopyOnLogin property of the ProfileForm component.
After the user has been identified by login and password and any desired properties are copied, the data structures for the form handler and session-scoped Profile object are updated to reference the registered user’s RepositoryItem.
For more information on login verification, see Managing User Logins.
handleLogout
The handleLogout method allows users to log out of their authenticated sessions. Like the other handleX methods, you can subclass ProfileForm to use the preLogoutUser and postLogoutUser methods. The ProfileForm property expireSessionOnLogout defines the default behavior of the handleLogout operation. The user’s session is invalidated when the handleLogout method is called if the expiresSessionOnLogout property is set to true, which is the default value. After logout, a subsequent request from the same user creates a new anonymous RAM profile.
If you do not wish to expire the session when you perform the logout, set the expireSessionOnLogout property to false. With this setting, the form handler and session-scoped Profile objects are reset to use a new anonymous RAM profile, but maintain the same session. When the user is redirected after a successful logout operation, the Personalization module adds an extra query argument labeled DPSLogout to the session ID information The default value of DPSLogout is true. The parameter name is defined by the constant atg.userprofiling.ProfileRequestServlet.LOGOUT_PARAM. The ProfileRequestServlet recognizes this query parameter and disables auto-login for the life of the session by setting a parameter AutoLogin in the user’s session to Boolean.FALSE. Otherwise, if you have configured the Personalization module to use auto-login, the persistent cookie or Basic Authentication information automatically attempts to reload the user profile even though the user logged out. See the Tracking Users section of this chapter for more information.
handleDelete
The handleDelete method permanently removes a user from the profile repository. The preDeleteUser and postDeleteUser methods are available for performing actions before and after the process of actually removing the user profile. The removeUser method performs the function of deleting the user profile. This method uses the current value of the repositoryId property of ProfileForm when invoking the MutableRepository.removeItem method.
handleUpdate
The handleUpdate method takes values entered into a profile form and explicitly updates the user’s profile with new attribute settings. Processing can occur before and after the update procedure by overriding the preUpdateUser and postUpdateUser methods. The updateUser method modifies the user’s profile with the values submitted in the form. This method checks for required parameters in a process similar to the handleCreate method.
The updateUser method calls the updateProfileAttributes method before committing the changes by calling the MutableRepository.updateItem method. All the parameters that are managed by the form handler are stored in a Dictionary through the ProfileForm component’s value property. These values are stored in the Dictionary for all form submissions, including operations for handling the registration and login of users. The updateProfileAttributes method iterates through all the submitted parameters and looks for an associated attribute in the user profile.
Once the updateProfileAttributes method finds a profile attribute, the same method checks the value of the profile attribute’s RepositoryPropertyDescriptorwritable property to determine whether the attribute can be updated. If this value is true, then the value stored in the Dictionary is parsed into the correct data type for the profile attribute. Additional transformations may occur, depending on the property to be updated. For example, for the password property, in the default configuration, the plain-text password value is turned into a hash representation and updated in the profile.
By default, the login and email attributes are trimmed to remove trailing and leading spaces. The list of properties to trim is defined by the trimProperties property. The protected method isTrimProperty is used to test if the specific property should be trimmed. The current implementation iterates over the list of properties specified by the trimProperties property and returns true if a match is found.
The MutableRepositoryItem for the profile is updated with all the form changes. After the update, the same verification for required profile attributes occurs as in the handleCreate process. If there are no errors, all updates are committed in one transaction. If there are any errors, no changes are made.
handleChangePassword
The handleChangePassword method allows users to update their password profile attribute. This specific handler is available because it allows the form to check that the user changing the password knows the original password value. Optionally, you can ask for a confirmation password value to verify that the user did not mistype the new password entry. This handler also contains the standard preprocessing and post-processing methods. The changePassword method compares the old password value with the confirm password value. The generatePassword method of the PropertyManager is used to transform the user’s password value (using a one-way hash) into the value that is stored in the database.
