Events associated with layouts

LayoutInitialized

This event occurs once immediately after the IPFGrid FDF has initialized itself with a display layout. This initialization occurs each time a page is loaded.

For layouts that host a collection of data, the schema of the collection is usually specified by the properties and unbound components from the IPFGrid FDF. Unbound components that are not in the header area, if any, become unbound components in the collection. If a property is not found in the underlying data source, the property is automatically unbound. The only way an unbound property can receive data is through scripting.

At the time of the LayoutInitialized event, the schema has been pre-initialized from the display layout. You can now add more properties that are part of the collection but that are not displayed.

Additional properties cannot be added for a layout that is not bound to a collection.

You can also change header component attributes at this time.

FilterChanged

This event occurs with either of these scenarios:

• The page containing the FDF is loaded (that is, the user navigates to the page with the FDF) and the FDF is about to fetch data. The filter that is received comes from the URL.
• The FDF has received a new filter and is about to fetch or re-fetch its data.

The new filter criteria are available in the parameters. If your script loads the data manually, for example through a custom load method, this is the event at which the load should occur.

ItemLoaded

This event occurs once for each record after a record is loaded from the data source. Details about the record are found in the parameters. Use this event to specify display attributes or to otherwise initialize the record after it has been loaded into the collection.

ItemValidating

This event occurs once for each record that is saved to the data source. Validations can be performed here, and associated messages can be returned. Data values cannot be changed here, but they can be marked as invalid. During processing of the saved data, records that are marked as invalid will be skipped.

Click

This event occurs when a user clicks on a clickable component. The component name is available in the parameters. Component names are unique across a display layout, so the name can be used to determine what was clicked on. If the component is not in a header area, the record associated with the component is also available in the parameters.

DropdownLoading

This event occurs during the population of a drop-down list. If your script manually loads the drop-down list, this is this event at which the load should take place.

Options for handling this event depend on the collection type used in the drop-down list. These are the options:

• If a DropdownCollection is specified, this event is called before the data is loaded. The script can modify the Where clause, or the script can load the data and set a flag that tells the portal system not to perform the load (for example, if you must use the InvokeMethod API instead).
• If an InlineCollection is specified, this event is called after the in-line data is read from the XML, and the script can modify the loaded data.

In either case, the script cannot change the structure of the drop-down list.

Alert

This event occurs as the result of one of the Alert API calls that are available to the scripts. For example, the script can call AlertComponent() to alert an embedded layout to a new situation. In this case, the named embedded layout receives the Alert event. See the list of available Alert APIs in Generating custom events.

UserAuthenticated

Available in:

Session script

Description:

This event occurs when a user is successfully authenticated for the portal. Handlers for this event can initialize a user session. The user ID and the name of the authentication provider are available in the parameters. The portal system looks at the AccessDenied indicator during the authentication. If your custom script in the UserAuthenticated event handler sets the AccessDenied indicator to true, the system denies access to the portal, and if your script sets a message in the AccessDeniedMessage property, that message is displayed. The Customer Portal uses this event to validate that there is exactly one customer user entry for the current login.

Pre-login causes handler to run:

The UserAuthenticated event handler is called for the pre-login user prior to showing the first pre-login page. When a regular user logs in, the event handler is called again. The event handler receives a parameter indicating the scenario for which the handler was called.

Parameters available in handler:

The parms for the UserAuthenticated event handler contain the user ID, pre-login indicator, and session variables.

• parms.UserId: This indicates the user from the authenticator assigned in data sources.
• parms.IsPrelogin: This indicates if the event handler is called for pre-login user or a regular user.
• parms.IPFSessionVariables: When IsPrelogin is false, this contains all the IPFSession variables that were set for the pre-login user at the time the regular user logs in. When going from the pre-login user to a regular user, the architecture does not preserve any session variables. The application can preserve them by accessing the passed in IPFSessionVariables and creating them in the event handler for the regular user.

Parameters returned from handler:

The UserAuthenticated event handler can set output parameters indicating if the portal should allow access to the particular user.

• parms.AccessDenied: Custom script sets to true indicating access to the portal is denied.
• parms.AccessDeniedMessage: When AccessDenied is true, this contents of this field are displayed on the page.

When AccessDenied is set to true for a pre-login user, no portal content can be displayed and an error dialog is displayed. The pre-login user needs to be configured correctly for the portals to function.

When handler fires for regular user:

For a regular user, the UserAuthenticated event handler can fire in two slightly different scenarios. The first is when the user types in a user name and password and clicks the login button. The event handler runs prior to the click handler for the login button. As part of the existing login button field display format (FDF) processing, the access denied message is displayed in the component supplied to the FDF, or when no component is specified in the FDF, the message is displayed in a pop-up window. The second is when the user had previously logged in and viewed pages on the portal. After some amount of time, their session timed out but their login is still valid. In this case, the user does not have to log in with their user name and password again, but the UserAuthenticated event handler is run again by the architecture when they try to access content again. If the UserAuthenticated event handler now sets access denied to true, the architecture will redirect to the Login.aspx page. In either of the scenarios, the current login reverts to the pre-login user.

IPFUserAuthenticationResultI:

This version has FDF attributes for a login button that contains the result of the last user authentication performed for a regular user. Scripting can access this information to get the status of the last login attempt and the last UserAuthenticated event handler run. This is particularly useful in the second scenario described above, so an error message can be displayed to the user when they are redirected to the login page. The following information is available in the IPFUserAuthenticationResultI FDF attributes for an IPFButton:

...Item("loginButtonName").FieldDisplayFormatAttributes.IPFButton.LastAuthentication.AccessDeniedMessage

...Item("loginButtonName").FieldDisplayFormatAttributes.IPFButton.LastAuthentication.AuthenticationProvider

...Item("loginButtonName").FieldDisplayFormatAttributes.IPFButton.LastAuthentication.Result - possible values are:

• Invalid Credentials: The login/password combination that the user supplied was not correct.
• AccessDenied: The UserAuthenticated event handler in the SessionStart script denied the user access.
• SystemDown: The system was unable to authenticate the user either because the UserAuthenticated event handler in the SessionStart script a runtime error or IPF was unable to access the authenticator data source.
• AccessGranted: The user was authenticated successfully.

...Item("loginButtonName").FieldDisplayFormatAttributes.IPFButton.LastAuthentication.UserId

Customizing the handler in the SessionStart script:

If you must add logic for a user-authenticated event in your portal, log in to the Portal Manager and select Content Development > Layouts. Select the session start layout to customize, edit the server-side script by adding custom logic, and then save your changes. To enable your custom script, select Portal Configuration > Session Initialization, and then select this session start script in the User Authenticated Event Handler field.