Server Extension Programmer's Guide:
Using UI Events

What Are UI Events?

UI Events allow you to write custom code that you can use either to replace or to augment the eRoom dialog pages for a subset of commands. You write a UI event handler and register it for particular commands through the eRoom Extension Manager. Before eRoom displays the dialog page for any of the commands that you specify, it calls your UI event handler. Your handler can display its own dialog pages in order to replace the eRoom dialogs, or it can display dialogs to gather information from the user before proceeding to the eRoom user interface. After your UI Event handler is completed with its processing, it returns control to eRoom passing a parameter that indicates how eRoom should proceed.

The list of commands that support UI Event handlers are listed in the ERUUIEventType enumeration. We recommend that extensions that handle the site login event do not also handle other events, because all files in the extension will be accessible without authentication. The buttons for New Member/Group in the room wizard are hidden if the chosen community has a handler for the create member/group event turned on. The same is true for the Add a Role button in the room wizard.

For important information that is common to multiple extension types, refer to the topic Common Extension Information.

Writing a UI Event

There is an example of a UI Event handler in the Toolkit\Samples\UIEvents subdirectory. Use this as a guide when writing your UI Event handler.

When writing a UI Event Handler, you must create an ASP file that has a Main()subroutine that takes a single parameter. The main subroutine will contain the implementation of your handler. That parameter will be the context object for the command that was triggered. The context object will contain the following information:

Effective user/member who triggered the command
Current facility/community
Current room (null if not applicable)
Current eRoom object (member, room, etc. -- as appropriate for the event)

After the event handler completes its processing, it must call the following method: FinishHandleEvent(status). You can set the status parameter to be one of three values depending on what you would like to have happen next.

eruiStatusDone = don't display the eRoom dialog and do not redirect the user. The UI Event handler takes care of redirecting to the next page.
eruiStatusRedirectToPage = do not display eRoom UI and return the user to the starting point before this command was triggered.
eruiStatusRedirectToDialog = display the eRoom UI associated with this command
eruiStatusRedirectReturn = redirect to Context.ReturnURL; If returning to a dialog, session state will not be released. This can be used for the erEventCreateUser and erEventCreateGroup to return to the calling add members page.

FinishHandleEvent only allows redirect to core dialog for dialog events. Events that are pages, such as Members Page, Settings Page (not dialogs) are not intended to get to core pages.

Returning Information to the Calling Dialog

For the erEventCreateUser and erEventCreateGroup events, you can tell eRoom about the newly created objects returning to the core add members dialog. This can be done by calling the IERUCustomContext::SetResults method with the IERUMember of any created users and groups. This adds these members to the calling dialog and selects their check boxes.

To return control to the calling dialog, call ’r;FinishHandleEvent eruiStatusRedirectReturn’. This will return to the calling add members dialog in the case of CreateUser and CreateGroup UI events.

Linking to Dialog URLs

You can get the URL to execute a specific UI event using the ERGenerateUIEventURL() helper function. This function returns URLs relative to the <base href> that specifies the eRoom server URL complete with any proxy prefix. eRoom will redirect to the FinalURL specified in the FinalURL paramemter when the user selects OK or Cancel in the core dialog. The following UIEvent URLs cannot be generated using ERGenerateUIEventURL()

SiteLogin
CreateCommunity
ImportCommunity
ExportCommunity
DeleteCommunity
CreateFacility
ImportFacility
ExportFacility
ReprovisionFacility
ImportRoom
ExportRoom

Installing a UI Event