Programmer's Guide:
Using Custom Viewers

What Are Custom Viewers?

Custom viewers are ASP pages registered at the server level for particular file extensions. They provide a mechanism for you to write your own viewers for files of a particular type. There are three display modes you can implement: embedded, standalone, and popup. eRoom will invoke your custom viewer whenever a user clicks on a file or chooses "Preview" from the file’s right click menu, if that file’s extension is associated with your custom viewer.

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

Developing Custom Viewers

Developing a custom viewer on an eRoom server consists of two steps:

Writing the custom viewer
Installing the custom viewer

These steps are explained in the following sections.

Writing Custom Viewers

There is an example of a custom viewer for text files in Toolkit\Samples\CustomViewers. Use this as a guide when writing your custom viewers.

When writing a custom viewer, you must create two files--one that implements the embedded mode by means of a class and one that implements the popup and standalone modes by means of a Main() subroutine. Even if you implement just one display mode, you still need to define both files. In this document, these files are referred to as the class file and the Main() subroutine file.

The naming convention of the files is based on the viewerID that you assign to the viewer. The viewerID should be in the form of "ProviderName.ViewerName." The Main() subroutine file is named using the convention "ProviderName_ViewerName.ASP" The class file must have the same name as the Main() subroutine file, except that "_class" follows the viewerName, as follows: "ProviderName_ViewerName_class.ASP" For example, in the toolkit sample, the text viewer's ID is "eRoomSample.TextViewer" while the Main() subroutine file is called, "eRoomSample_TextViewer.ASP" and the class file is called, "eRoomSample_TextViewer_class.ASP."

The Class File

eRoom calls into the class file if your viewer is displayed in embedded mode. You must define a class in this file called "providerName_viewerName" In the toolkit example, the class is called "eRoom_TextViewer" That class must contain a function called "GenerateBody()" The GenerateBody() method takes a single parameter, which is an IERUCustomContext interface. The IERUCustomContext interface contains information about the item selected for viewing. In both ASP files, always use IERUCustomContext to access eRoom data to help ensure that your viewers are not misused. You may define other functions in your class, but GenerateBody() is what eRoom calls to invoke your viewer.

Here is skeletal code for the class file named MyCo_ViewerExample_class.ASP:

Class MyCo_ViewerExample

function GenerateBody(Context)

’r;## Generate HTML to display the content of the item.

End function

end class

Note that the class file should contain only a class definition. No declarations of any kind should be placed outside of the class itself.

The Main() Subroutine File

eRoom calls into the Main() subroutine file if your viewer is displayed in either popup or standalone mode. The Main() subroutine file requires two components. You must include "eRoomCustomViewer.asp" and you must define a Sub Main() method. This is how eRoom is able to call into the custom viewer page when users navigate to a file in eRoom. The Sub Main() method takes a single parameter, which is an IERUCustomContext interface. Implement your custom viewer inside of Sub Main(). Optionally you may want to include your class file in the Main() subroutine file. This way you will be able to reuse the code in the class file for generating the content of the viewer.

Here is skeletal code for the Main() subroutine file named MyCo_ViewerExample.ASP:

Sub Main(Context)

’r;## Create an instance of your custom embedded viewer object.

dim viewer

set viewer = new MyCo_ViewerExample

call viewer.GenerateBody(Context)

</body></html>

End Sub

Redirection and Linking to Custom Pages

When your viewer is displayed in standalone mode and you want to send the user back to the previous eRoom page, redirect the browser to the URL in the ReturnURL property of IERUCustomContext. Alternatively in popup mode, you can just close the browser window rather than redirect. In embedded mode, the ReturnURL is empty, as there is no place to return to (you are already in the current page).

Note that when your viewer is displayed in embedded mode, all links are relative to the <base href> that specified the current eRoom server's URL, complete with any required proxy prefix. This is also true when you are using eRoomToolkit.ASP to generate your pages. URLs to your extension pages from within such pages should be relative to this <base href> or made qualified URLs.

Installing the Custom Viewer

Once you’ve finished writing your custom viewer, you must deploy it on the eRoom Server. Follow these procedures in the Configuring Your Server Extension topic.

Programmer's Guide: Using Custom Viewers