2
Document Viewers

This chapter introduces and describes the document viewers provided in the ConText Workbench. In particular, this chapter provides installation and usage information for the Viewer Plugin and Viewer Cartridge. Ensure you read the section entitled "Document Viewers" in Chapter 1, "Introduction" which briefly explains the purpose of the various viewers.

The topics covered in this chapter are:

Using the Viewer Control

This section provides usage information for the Viewer Control provided by the ConText Workbench.

The Viewer Control can be used on Windows NT or 95 in any application environment that supports custom controls.

It can also be used in a Web-based environment:

as a client/server component on a page as an Active-X control to view a document directly from the viewer's own database connection
in a helper application to view documents that are provided by means other than via the viewer's own database connection (see "URL as a Helper Application" in this chapter)

Online Help for the Viewer Control

Full usage information for the Viewer Control is provided online as a WinHelp file.

Registering the Viewer Control

The Viewer Control should normally be automatically registered for use during installation. If, for some reason, the Viewer Control is not registered, it can be registered manually using the regsvr32 utility.

Note:

The Viewer Control is not unregistered during deinstallation. You must manually unregister it using regsvr32 before deinstallation.

For example:

regsvr32 /u ctxv32.ocx

Using the Viewer Plugin

This section provides details on installing the client-side Viewer Plugin, which is used to display documents on the World Wide Web as they would appear in their native format.

However, the Viewer Plugin cannot work without the Viewer Cartridge, which must be installed first. The Viewer Cartridge generates the highlight information for a document, fetches the document from the ConText database, and then sends the document as a file to the Viewer Plugin for display.

Once installed, the Viewer Plugin is automatically invoked by the Web browser when:

a document with the Mime-type "application/x-ctxv" is delivered to the Web browser via the Viewer Cartridge and Oracle Web Application Server, or

a local file with the extension ".ctxv" is loaded into the Web browser

Note:

Before using the Viewer Plugin, the Viewer Cartridge must be installed, and at least one suitable URL must be specified.

For more information, see "Using the Viewer Cartridge" in this chapter.

Installing the Viewer Plugin File

Under automatic installation, the Viewer Plugin file - called npctxvpi.dll - is placed in the Web browser 'plugins' directory.

If there is no Web browser installed, you must install it before copying the file manually, as follows:

Copy the Viewer Plugin file (npctxvpi.dll) manually from the <ORACLE_HOME>\ctxw\Viewer\plugin directory to the Web browser 'plugins' directory.

Activating the Viewer Plugin

To activate the Viewer Plugin file, you must first close down all open Web sessions (if applicable).

Then, start a new Web browser session to ensure that the file has been registered. You can do this by selecting the Help -> About Plug-ins menu item from Netscape.

Using the Viewer Cartridge

The Viewer Cartridge is installed on Oracle Web Application Server. Its purpose is to deliver ConText-indexed documents, and any other data held in an Oracle database to Web browsers. These documents can then be viewed.

URLs are used to instruct the Viewer Cartridge to view ConText-indexed documents from an Oracle database. When these URLs are specified, there is a Mime-type that determines how the documents will be delivered. With the default Mime-type, "application/x-ctxv", the Web browser tries to use the Viewer Plugin, if it is available.

URLs can be used to display documents in various ways. Documents can be viewed full-frame, in a separate window, or to predetermined dimensions.

Access to ConText-indexed documents can be restricted through the Oracle Web Application Server by the use of realms.

A Viewer Cartridge configuration file is used to determine how the Viewer Cartridge connects to the database. Multiple configuration files can be used to allow different database connection details to be protected by different realms. This allows varying levels of security for documents.

See Also:

For more information about URLs in the Viewer Cartridge, see "Specifying URLs" and "Using URLs" in this chapter.

For more information about using realms, see "Security Mechanisms" in this chapter.

For more information about configuration files, see "Viewer Cartridge Configuration Files" in this chapter

Pre-Installation Requirements for the Viewer Cartridge

First, ensure the WebServer version to be installed against is 2.1.0.3.2 or higher.

Then, if necessary, install an Oracle JDBC driver (version 7.3.3.1.3 or later) and note the connection requirements. These are used when writing additional configuration file entries.

To obtain the JDBC driver, navigate to www.oracle.com and look for the free software page. Choose the Oracle JDBC option. Or you can navigate directly to the page; currently it is:

www.oracle.com/products/free_software/

Otherwise, you can use an alternative driver.

See Also:

For more information about configuration files, see "Viewer Cartridge Configuration Files".

For more information about alternative JDBC drivers, see "Using an Alternative Oracle JDBC Driver".

Installing the Viewer Cartridge

This section provides details for installing the Viewer Cartridge to a remote machine.

On installation, the middle-tier cartridge files are placed in the following directory:

<ORACLE_HOME>\ctxw\middle\ctxvcart

When installing the Viewer Cartridge to a remote machine, you need to copy or move all files from the locally installed directory <ORACLE_HOME>\ctxw\middle\ctxvcart\remote to a directory <ORACLE_HOME>/ctxw/middle/ctxvcart on the target machine.

The "install" subdirectory is not required on the remote machine.

Note:

If the target machine is not running Windows NT, all file and directory names must be in lowercase.

Specifying URLs

Once the Viewer Plugin and Viewer Cartridge have been installed, the next step is to specify URLs and embed them into HTML pages.

These URLs are required to be able to view ConText-indexed documents from an Oracle database through the Viewer Cartridge. They contain sufficient information for Web Request Broker to direct the request to the Viewer Cartridge. This enables the Viewer Cartridge to generate a database connection, plus parameters that define what the document is and any highlight information needed to service the request.

Parameters to the URL can be encoded within the URL, or supplied through HTML form fields.

To specify URLs:

To get a representation of a highlighted document (in WYSIWYG, if supported, or ASCII, if not supported), use the URL parameters to define:
```
indexing policy:      COLSPEC=<policy_name>
document selection:   TEXTKEY=<tk_value>
```
and, optionally:
```
query expression:     [QUERYEX=<term_specification>]
```
To retrieve the document in its original, unhighlighted form:
```
type info:            MIMETYPE=<mime_type_string>
```
Then the browser can use its own mapping to invoke a helper application or plugin to handle the data.

With the default Mime-type "application/x-ctxv", the browser tries to use the Viewer Plugin, if it is available.

See Also:

For information about installing the Viewer Plugin, see "Using the Viewer Plugin" in this chapter.
If the document in its original, unhighlighted form is required (without using ConText), and is stored internally in the database - that is, not URL or external data store - it is more efficient to go directly to the base table:
```
table spec:           TABLE=<table_name>
row selection         WHERE=<where_clause>
col to fetch:         COLUMN=<column_name>
Mime type:            MIMETYPE=<mime_type_string>
```

The following URL example displays a document from the table field defined by <table_name>, <column_name> and <where_clause> as these elements would appear in a SQL select statement:

http://<host>/<virtual_path>/CtxwViewCart?table=<table_name>&column=<column_name>&where=<where_clause>

The optional parameter, MIMETYPE, may be used to define the Mime-type of the data. The MIME-type defaults to "application/octet-stream" for binary data and "text/plain" for textual data.

Using URLs

Once suitable URLs have been specified, they can be used in HTML in various ways:

URL as a Link Target

When you use URLs as a link target, highlighted documents are viewed full-frame if the Viewer Plugin has been installed on the client. The frame is resizable, but plugin parameters cannot be specified.

Documents of other Mime-types (such as jpeg files) are supported. These are downloaded and viewed on the client by the best means available to the browser for that Mime-type.

URL as an Embedded Plugin Tag

Here, the dimensions of the plugin are pre-determined. So the height and width of the document view are set by the Height and Width EMBED tag parameters.

Plugin parameters can also be specified. A link can be provided to the location of the plugin archive for an 'install-on-demand' mechanism. Other Mime-types are not supported.

EMBED Tag Parameters

To embed the Viewer Plugin, include the following EMBED tag.

This example displays a document from the table field implied by <policy> and <textkey>, using <query> to highlight hit words:

<EMBED width="nnn" height="nnn" src="http://<host>/<virtual_path>/
CtxwViewCart?colSpec=<policy>&queryEx=<query>&textKey=<textkey>">

where nnn is a positive number, <host> is the WebServer host and <virtual_path> is the Viewer Cartridge alias. The src attribute value must be on a single line. An optional parameter, conf, is used to indicate which section name of the configuration file is used for database connection data. This parameter defaults to use the 'DEFAULT' section.

See Also:

For more information, see "Viewer Cartridge Configuration Files" in this chapter.

Plugin Parameters

You can specify the following parameters to the plugin:

toolbar=true|false
silenterrors=true|false
idleinterval=<n>
shortcutmenu=true|false
pageview=true|false

If toolbar is set to true, the toolbar is shown. The default is true.

If silenterrors is set to true, it suppresses error information dialog boxes. The default is false.

idleinterval represents a value (in milliseconds) between 1 and 500 that sets the interval between document section reads. The default is 50. A value of 0 means that there is no idle time reading of document sections.

If shortcutmenu is set to true, you can click the right mouse button on the viewer window to obtain a short-cut menu. The default is true.

If pageview is set to true, the plugin will attempt to represent the document page as the page would appear when printed. The default is false.

URL as a Helper Application

URLs can be used to invoke a helper application (which must have been defined in the applicable Web browser) to display the document in a separate window as a separate process.

The URL is used as a link URL where a Mime-type is mapped to the ConText Cartridge Viewer Example that uses the Viewer Control. The ConText Cartridge Viewer Example is delivered as part of the ConText Workbench, and is accessible via the icon of that name.

Security Mechanisms

Access to ConText-indexed documents can be restricted by using realms.

A realm is a group of users and (other) groups assigned by an authentication scheme to regulate access to specific documents and directories through the Oracle Web Application Server.

Authentication schemes allow you to define named groups of user name/password combinations, and named realms that are groups of these groups. You can then assign user, group, and realm names to virtual files and directories, requiring any client requesting access to input one of the specified username/password combinations.

This way, some groups can be granted access to ConText-indexed documents that are held in a variety of databases, while access is denied to other groups.

To restrict access through realms:

Map a virtual path to a realm through the Oracle WebServer Administration pages.
Map that virtual path to Viewer Cartridge through the WebServer Administration pages.
Create the configuration files to which the virtual paths are mapped.

If the virtual path contains more than one element, the last element is used to map onto the name of the configuration file. In this manner, each realm can have a separate configuration file. This ensures that users in groups with access to a realm can be denied access to information available in other realms.
Enter the connection details into the configuration file (using the conf URL parameter) for each database connection that is within that realm.

Specify URLs using the appropriate virtual paths.

See Also:

For more information about using the Oracle WebServer Administration pages, see Appendix A, "Viewer Cartridge: Manual Configuration", and also the Oracle WebServer documentation.

For more information about the configuration file, see "Viewer Cartridge Configuration Files" in this chapter.

For more information about specifying URLs, see "Using the Viewer Cartridge" in this chapter.

Viewer Cartridge Configuration Files

A Viewer Cartridge configuration file contains one or more entries that describe how the Viewer Cartridge connects to a database. This description includes the username and password, the database details, and the JDBC driver to be used.

The configuration files must reside on the same tier as the Web Server, in the following directory:

$ORACLE_HOME/ctxw/middle/ctxvcart

Multiple Configuration Files

Multiple configuration files can be created to allow different database connection details to be protected by different realms. These files can be used instead of, or in conjunction with, the default file ctxvcart.cfg.

Multiple files are created by giving the file the same name as the last element of the virtual path of the Viewer Cartridge, with a .cfg extension.

For example:

Virtual Path Configuration File

/ctxview

ctxvcart.cfg

/ctxview/secure

secure.cfg

/ctxview/public

public.cfg

Virtual Path	Configuration File
/ctxview	ctxvcart.cfg
/ctxview/secure	secure.cfg
/ctxview/public	public.cfg

Section Name

Each section of a configuration file starts with a section name enclosed within square brackets and has a number of parameters associated with the section, as follows:

[SECTION_NAME]
username
password
database
driver
subprotocol

All lines with any other parameter names are ignored. If one or more parameters of the same name are found within one section, the value associated with last one is used. A value cannot be split over more than one line.

username

This parameter specifies the name of the Oracle user that the database connection uses. Defaults to CTXSYS.

password

This parameter specifies the password of the Oracle user. Can be null.

database

This parameter depends on the value of the subprotocol parameter.

For any subprotocol, a full connect descriptor, as used in tnsnames.ora files, can be used. For example:

database=(DESCRIPTION=(ADDRESS=(COMMUNITY=DECCOM.FIN.HQ.ACME)(PROTOCOL=DECNET)(NODE=NY_VAX.FIN.HQ.ACME)(OBJEC
T=LSNR))(CONNECT_DATA=(SID=DB1)(GLOBAL_NAME=NY_FIN.FIN.HQ.ACME)))

For the oci7 or oci8 subprotocol, a service name present in a tnsnames.ora file can be used.

For the thin protocol, a value in the form <host>:<port>:<sid> can be used. For example:

hq_server:1521:ORCL

If database is null, it defaults to the installation's default database.

driver

This parameter specifies the Java class name of the JDBC driver (of version 7.3.3.1.3 or later). It should always be:

oracle.jdbc.driver.OracleDriver
subprotocol

This parameter should be assigned one of the following values:

oci7 | oci8 | thin

If the subprotocol parameter name does not appear within the section, a default of oci7 is used.

See Also:

For more information about the values you can specify for section names, see the documentation for the JDBC driver that you are using.

Using an Alternative Oracle JDBC Driver

To use an alternative Oracle JDBC driver:

If, for example, the OCI driver is not available for the Oracle WebServer host platform, you must install into the Oracle WebServer's <ORACLE_HOME>.
Modify the Viewer Cartridge CLASSPATH to include a path to (the zip archive containing) the class file root directory.
Modify the Viewer Cartridge LD_LIBRARY_PATH to include a path to the directory containing any native library object files required by the driver.

Modify the configuration file for that CONF section, specifying:

database connection string: database=<instance_specification>
java class name:            driver=<driver_class_path>
subprotocol identifier:     subprotocol=<oci7|oci8|thin>

See Also:

For more information about modifying the CLASSPATH and LD_LIBRARY_PATH, see Appendix A, "Viewer Cartridge: Manual Configuration".

For the precise requirements you must specify for your JDBC driver, see the appropriate JDBC driver documentation.

2 Document Viewers