20. PerlScript

Contents:
Client-Side PerlScript
Server-Side PerlScript

PerlScript is an ActiveX scripting engine that allows you to incorporate Perl within any ActiveX scripting host. PerlScript can be used on the client side (Internet Explorer 4.0) or in Active Server Pages (ASP) generated by web servers like IIS or WebSite Pro. To use PerlScript with these applications, you must have Active State's ActivePerl with PerlScript installed on the local machine (or you can use a network-based installation of each).

Since a local Perl and PerlScript installation is required, it is not practical to deploy applications that use client-side PerlScript across the Internet. Nevertheless, in situations where you have control over the desktop configurations, as in an Intranet environment, client-side PerlScript offers tremendous opportunities for browser-based application development.

Server-side PerlScript does not have this limitation. To use PerlScript on your web server, you don't need to worry about how the end user's desktop is configured. As long as you are running a web server that can use ASP, you can use PerlScript on your web server.

With the free distribution of Netscape Navigator source code, the availability of PerlScript is likely to broaden significantly. This is an area of development that you should keep an eye on if you like the idea of extending Perl's power to web authoring.

PerlScript is implemented into HTML pages or ASP pages via the Document Object Model used by the ActiveX scripting engine. Scripts are virtually the same as any other Perl script. They use Perl's object-oriented features on an object hierarchy defined by the script engine. The object model is different for clients and servers, but the same scheme is used throughout: top-level objects with sub-objects, each containing their own properties and methods.

Properties of objects, like the name of a frame or the background color of a window, are available as hash elements from a referenced object. For example:

$object->subobject{'property'} = "value";
$val = $object->subobject->{'property'};

Thus, properties can be set or retrieved.

Objects have a predefined set of methods available to them as well. Methods define actions such as writing to a document or performing actions on a mouse click. Methods are accessible in the usual way:

$object->method(args);

This chapter provides information on the parts of the object model that you will use most often. A complete reference for the object models for both ASP and ActiveX scripting clients is beyond the scope of this book. For more detailed information, consult the documentation for your server, or the Microsoft web site, which has complete client and server information.

20.1 Client-Side PerlScript

All PerlScript code must be contained within a <SCRIPT LANGUAGE="PerlScript"></SCRIPT> element. You may include any number of these elements in your program, so it is possible to intersperse Perl and HTML freely. For example:

<HTML>
<HEAD>
<TITLE>Hello, World</TITLE>
</HEAD>
<BODY>

<H1>Hello, from the Old Edition!</H1>

<SCRIPT LANGUAGE="PerlScript">

    my @one_hit = ('Bel', 'Biv', 'DeVoe');

    foreach (@one_hit) {
       $window->document->write(qq[$_ says "Hello"!<BR>]);
       }
    
    $window->document->write(qq[<P><I>"That girl is Poison!"</I></P>]);

</SCRIPT>

</BODY>
</HTML>

The write method is used on the document object to "write" HTML and text to the document displayed in the window.

The top-level object is the window. This is the default object that contains the script. (Even though the script is contained in the HTML file, the script object is a level below the window, just like the document object.)

Every window contains the following objects:

Frame: This object contains an array of frames in the window. Each frame object is accessible via the index, i.e., $window->frame[2] is the third frame object. Each frame object is a container that acts like its own window object.
History: This object stores the browser history - all the sites a client has been to in its current session.
Navigator: This object contains information about the client application, like the UserAgent header it provides.
Location: This object contains information about the current URL for the window.
Script: This object contains any script elements in the current window scope.
Document: This object contains all of the displayed content in a window: the HTML, text, forms, objects, etc.

The most important object in this hierarchy is the document object. The following section explains the objects it contains, their properties, and their methods.

20.1.1 The Document Object

The document object represents what is displayed within the client window. In the example above, we showed that the write method tells the client to show the given HTML and text. The document object contains a number of methods and properties that can be manipulated within a script. It also is a container for other objects that hold information about the document:

Anchor: An array of anchors (<a name="string"> </a> tags) in the document.
Form: An array of forms contained in the document.
Link: An array of hyperlinks (<a href="url"> </a> in the document.

The anchor and link objects both provide arrays. Each element in the array is a string with the name of the anchor or location of the hyperlink. The elements in the link array are read-only. Anchor names can be manipulated by the script.

The form object provides access to the elements of the forms within your document. Each form is an indexed element of the form object array and can be accessed like this:

$obj = $window->document->form[1];

This would be the second form in the document. Under this form object are objects representing the various parameters of the form and input tags. They are accessible by the names of the attributes used in the HTML tags.

20.1.1.1 Document methods

The following methods can be used on the document object. They are accessed using the usual object-method syntax: $obj->method(args).

write (string): Places the given string into the document at the current position. The string can contain HTML tags and text that will be interpreted by the browser or other HTML-capable client.
writeLn (string): Same as the write method, except that it places a new line after the given string.
open: Opens a document object for writing. The current document is already open for writing. This method may be used on another document object from another frame or window to send output to. After open is called, output to a document is not displayed immediately; it displays only after a close call is used on the document.
close: Closes a document and writes all output to it.
clear: Clears an output stream on a document.

20.1.1.2 Document properties

The document object contains a set of properties described below. Properties can be set or retrieved, and are accessed as hash variables under the document object. They are accessible via the following syntax:

$val = $window->document->{property};

linkColor: The color of hyperlinks in the document, given by an RGB-color value.
vLinkColor: The color of visited hyperlinks in the document, given by an RGB-color value.
bgColor: The background color of a document, given by an RGB-color value.
fgColor: The foreground color of a document, given by an RGB-color value.
location: The URL of the current document.
lastModified: The timestamp for the last modification of the document.
title: The title of the document as given by the <TITLE> tag.
cookie: The string value of the cookie for the document, if there is one.


19.18 OLE Automation		20.2 Server-Side PerlScript