Server Extension Programmer's Guide:
Using Dialog Toolkit (eRoomToolkit.asp)

You may find that in addition to customizing eRoom, you need to build a few additional pages of your own to work with eRoom. It would be nice if those pages looked like eRoom dialogs. You could do that by copying and pasting HTML, but to make it easier we've provided a dialog toolkit. To see how it works, examine the Samples\CustomCommand\MyCustomCommand\script\MyCustomCommand.ASP file for an example dialog that uses the dialog tookit.

Using eRoomToolkit.ASP to generate an eRoom-like page is done by setting some page variables (five required, one optional), defining two subroutines, and adding an INCLUDE directive.

Note: All pages generated using eRoomToolkit.ASP contain a <base href> that makes all relative URLs relative to the current eRoom server. Refer to the Notes on Upgrading to SAAPI Version 7.0 topic for additional information on <base href>.

Page variables

  • mySubmitPage: the page to post to when this form is submitted. Required.

  • myContextSmall: the small blue text that usually shows the name of the eRoom or the facility. If you don't want any text there, just set this to "". Required.

  • myContextLarge: the large text that usually shows the name of the page being modified. If you don't want any text there, just set this to "". Required.

  • myTitle: the title of your dialog page. In the default design this appears in the orange bar. Required.

  • myLogo: a specific logo, if you want one. If you leave this as "", eRoom will insert the default eRoom logo. Required.

  • myMode: generates an eRoom pop-up-style dialog instead of the normal full-page-style dialog. This optional variable takes three different string values:

="popup": generates a pop-up dialog.

="manual": does not generate any kind of dialog, so the custom file is responsible for calling either GenerateDialog or GeneratePopupDialog itself.

="other" (or omitted): generates a normal, full-page-style dialog.

Subroutines

InsertButtons: this subroutine defines the buttons you want on your page. It should be nothing but a series of InsertButton statements, in order, the syntax of which is:

InsertButton caption, urlBtnName, buttonWidth, validate

where the parameters are:

  • caption: the text for the button

  • urlBtnName: the name of the button

  • buttonWidth: the width of the button, in pixels

  • validate: either "true" or a validation function of your own that returns true or false to indicate whether the data is valid and whether or not the button action can proceed.  Look at the "Close" button in the "eRoomSample_TextViewer.ASP" file's InsertButtons() sub for an example of a custom validation function. In this case, it closes the window if the viewer was opened in popup mode. Form field validation can be accomplished in the same way.  For Example:

sub InsertButtons
'## Insert OK button with client side validation of fields
'   (assumes form fields name and number)
%>
<script>
function doIt()
{
    if(document.Main.name.value == "" || document.Main.number.value
    == "")
    {
         alert("You must enter a name and a number.");
         return false;
    } else
    {
         return true;
    }
}
</script>
<%
InsertButton "OK","OK",80,"doIt()"
end sub

The dialog toolkit will insert your buttons either left-to-right, or top-to-bottom, depending on the dialog design (see above).

InsertDialogBody: this subroutine defines the body of your page. You can include ASP and/or client script code in this section, if you need to, as well as the HTML for the form itself. There are a few utility functions you can use within the body:

  • =Spacer(height, width): inserts a transparent .gif file of the specified size. Useful for controlling table spacing.

  • =eImageAlt(filename, alt-text, alignment): inserts a standard-format IMG tag for a graphic from the eRoom graphics directory. If you are using graphics of your own, just insert them normally, using IMG tags.

  • eTable: inserts a standard table tag, like:

<table border=0 cellpadding=0 cellspacing=0>

These are useful for making labels and widgets line up. Note that if you use embedded tables in your dialog body, you must enclose all text within them in DIV tags, so the fonts and margins will work right. For example:

<td><div>Name</div></td>

<td><div><input type=text name="name"></div></td>

rather than:

<td>Name</td>

<td><input type=text name="name"></td>

Include

At the end of your ASP file, after the "end sub" for InsertDialogBody, put:

<!--#include virtual="/eRoomASP/en/eRoomToolkit.asp"-->

This includes the toolkit file, which in turn includes the eRoom’s Frame or your custom UI frame as appropriate., which in turn includes the appropriate style sheet, all of which combine to make your page not only look right, but update automatically if you customize your eRoom design, or change it later.