Server Extension Programmer's Guide:
Common Extension Information

This topic covers the following items that are common to one or more extension types:

Custom Context Object

ASP Functions

ASP Error Handling and Reporting

Extension Language Localization and Code Pages

Returning Control from ASP Extensions

Debugging ASP Extensions

Custom Context Object

The IERUCustomContext object is passed to Custom Commands, Custom Viewers, and UI Events via Sub Main(Context). This object can also be retrieved for use in Custom User Interfaces (Custom Page Frames) using ERGetCustomContext().

The ::IsPersistent property controls the context object and is stored on the user’s session state, making it available across server requests. If true, the context object is stored on the user's session, and the extension is responsible for performing cleanup prior to final redirect. (Not that you must include querystrings on you URLs to allow eRoom to retrieve the correct context object.)  This session state is uniquely identified using the ERWindowName querystring.

ASP Functions

The files SAAPIUtils.ASP and SAAPILogin.ASP contain numerous functions for use by server extensions. For information on these functions, refer to the eRoom Constants and Helper Functions topic.

ASP Error Handling and Reporting

ASP-based extensions all share a common structure. Each is made up of a Sub Main() that is called with a context object. If Sub Main() returns with an error set in Err.Number, a default error handler will report the error message. An extension can raise an error by using Err.Raise method. For Example:

Err.Raise MyERRNumber, MyERRSource, ”r;My specific error message for this failure.”

As appropriate, an extension may also choose to handle errors within the page itself or to ignore errors.

Extension Language Localization and Code Pages

eRoom extensions are common between languages. Language localization can be achieved in a number of ways: via Windows resource dll(s)/loadstring, server transfer to localized ASP pages, or other techniques.

ERoom establishes the client locale for the running thread before reaching any server extension. You can determine the client’s locale by using ASP Session.LCID or via GetThreadLocale() in the Windows API. A LANGID can be derived from LCID to determine the primary language.

A simple COM object could be built to expose a LoadString() method to your extension. The method would simply call Windows LoadString using the current thread’s locale.

In the case of Custom User Interfaces (page frame customization), you are more limited. You should try to keep changes language-neutral when possible.

eRoom can run in a variety of international configurations. We recommend that you specify the CODEPAGE of your ASP-based extensions by using the <%@ CODEPAGE = nnnn %> directive. You can specify the codepage of your ASP page by simply adding the following before any other statements:

<%@ CODEPAGE = 1252 %>

Returning Control from ASP Extensions

Returning control to eRoom from an ASP extension varies with the type of extension. In most cases, you can simply call ERCustomEnd() with the URL that you wish to redirect to. For example, ERCustomEnd Context.ReturnURL.

Returning or Redirecting from UIEvents

The function FinishHandleEvent(Status) &endash; This function will clean up any persistent session state associated with a running UIEvent. This is similar to ERCustomEnd(), which can also be used to clean up a UIEvent and redirect. Calling FinishHandleEvent() will clean up and/or redirect as defined by status. Status is defined as:

• eruiStatusDone -- Clean up, without any redirect.

• eruiStatusRedirectToPage -- Clean up and redirect to the ”r;current page”. This is only appropriate when there is a known current page to return to. Context.ReturnURL will be ”r;” (empty) if you the return location is unknown.

• eruiStatusRedirectToDialog &endash;- Don’t clean up; redirect to the non-overriden eRoom core dialog.

• 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.

Returning from Custom Commands, Custom Viewers, and UI Events

Redirect to Context.ReturnURL after freeing the custom context by calling "ERCustomEnd() or settings Context.IsPersistent=FALSE.

There is no need to release session state unless Context::IsPersistent is true."  Custom viewer's context are not persistent by default.

For standalone viewers, redirect to ReturnURL. For popup mode, close the browser window. Embedded mode viewers cannot return in that they are embedded in the eRoom page.

Debugging ASP Extensions

Note that you can find errors that are being thrown from deep within ASP code by simply disabling or removing your error handlers and allowing the error to stop execution of the script.

If you are having trouble finding an error during page generation of you extension, try temporarily editing /eRoomASP/EN/eRoomCustomUtils.ASP and changing the following constant to true.

CONST erDebugCustomErrors = false

Warning: Modifying ANY eRoom core file will result in a checksum warning being emailed to the site administrator. You must replace the original file with original date/time to satisfy the checksum.