This page explains how to configure your WWW server to handle iHTML Python programs and gives a general introduction to the iHTML system and its use with the Python language module.
The creation of an iHTML program involves at least two steps. First, the program must be written and made available on a Web server. Second, an actual HTML page must be made, with a link from it to the program. The link may take one of two distinct forms, as described below.
The link type that is likely most familiar is that of the
embedded object or applet within a standard HTML
document. In this case, the World Wide Web Consortium's
<OBJECT>
tag is placed within the document body,
containing a link to the iHTML program. Where this tag occurs, a
graphical object will appear on the page with the referenced program inside
it. This can be thought of much as a standard <IMG> tag,
but one that is able to do much more than just display static pictures.
For example, to embed a program stored in a file named "my_prog.ipy", which is located in the same directory on the server as the HTML document it is being embedded into, the following markup could be used:
<OBJECT CLASSID="my_prog.ipy"> </OBJECT>
When an iHTML browser encounters this markup, it will retrieve the "my_prog.ipy" program from the server, and begin executing it inside of the HTML document in which that markup appears.
With an additional tag, arbitrary arguments may be provided to the
requested program. This is done with the <PARAM> tag,
which allows the attributes NAME and VALUE. For
example, we may wish to add a parameter to our program that
supplies a set of data items as a Python tuple. This may look like:
<OBJECT CLASSID="my_prog.ipy"> <PARAM NAME="data" VALUE="(10,20,30,40)"> </OBJECT>
Some <OBJECT> attributes are handled by the iHTML
library as parameters. Most importantly,
WIDTH and HEIGHT result in the
object seeing parameters with names "Width" and
"Height", respectively.
The second form an iHTML program can take is that of a program
occurring
in the head of a document. We again make use of the HTML 3.2
<OBJECT> tag: including the
CONTEXT attribute
in the tag declares this to be a link to an external program, and
an iHTML-capable browser will retrieve it from the network and
execute it.
To execute a program stored in a file named "my_main.ipy", which is located in the same directory on the server as the HTML document it is to be executed in, the following markup could be used:
<OBJECT CONTEXT=DOCUMENT CLASSID="my_main.ipy"> </OBJECT>
Adding a document object changes the browser's behavior in displaying the document. Before being displayed, the document program is executed. This program may then examine and manipulate the document's HTML parse tree, before explicitly telling the browser to display it to the user.
Python programs written for the iHTML system are stored on the server machine in source-code form. When an HTTP request is made for the document, the server should return it with the header:
Content-type: application/ihtml;language=python
This causes an iHTML-capable browser to route the document to the iHTML library, and from there it is passed on to the Python interpreter. You will typically need to configure your HTTP server to send this header. While the exact procedure used to do this depends on the specific server, the following steps will work for NCSA's hpptd:
Alternatively, HTML documents can explicitly set the "Content-type" when embedding an object, through the "TYPE" and "CODETYPE" attributes of the <OBJECT> tag. For example, the first applet example could also have been written as:
<OBJECT CLASSID="my_prog.ipy" CODETYPE="application/ihtml;language=python"> </OBJECT>
The entry point for an iHTML Python program is a specially-defined symbol that is called by the Python interpreter once the program has been retrieved from the network. It is handed one argument (a dictionary of parameters) and must return an instance of a class appropriate for the type of program being executed. The details for the two program types are as follows:
ihEmbed(args)
dictionary
of program arguments. This
includes all <PARAM> tags supplied in the
markup
(the NAME attribute is the key
key and the VALUE attribute is its value), as
well as certain attributes of the <OBJECT>
as described in the
Application
class.
All keys and values in the dictionary
are
Application
class.
ihMain(args)
dictionary
of program arguments. This
includes all <PARAM> tags supplied by the
user (the NAME attribute is the key
key and the VALUE attribute is its value).
All keys and values in the dictionary
are
Document
class.
In either case, the program entry point is usually a class that is a
subclass of either a
Document or an Application.
When called by Python, the class is instantiated and its
__init__() function is called with the program
arguments. All of the (possibly modified)
arguments dictionary must be
passed off to the superclass's __init__() method to
be processed
As an example, consider the simplest possible embedded program:
import ihApp
class ihEmbed(ihApp.Application):
def __init__(self,**args):
# Send parameters to superclass: a tuple consisting of our
# self variable, and the dictionary of arguments.
apply(ihApp.Application.__init__,(self,),args)
__export__ = ['ihEmbed']
All iHTML Python programs must define one of two symbols,
__export__ and __public__, used
to declare which symbols defined by the file should be externally visible.
This feature can be seen in the example above, where the
__export__ symbol appears on the last line.
The two symbols are mutually exclusive, and provide different ways to control which symbols are visible:
__export__
list of
strings naming which symbols in the
module that should be externally visible. The interface for the
module will be constructed from a dictionary consisting of each of
the symbol names in this list, along with the value that has been
assigned to them in the module.
__public__
dictionary specifying the exact
the module dictionary that should be externally visible. Each entry
in the dictionary includes a symbol name and its associated value.
In order to prevent potential name-conflicts, it is recommended that Python programs adhere strictly to the following conventions for naming class methods, members and other symbols:
DrawLine()",
"Width", etc.
GIS_ClearMap()", "Pk_SetCompression()".
is_finished()",
"lineWidth", etc.
The private names in a class should follow the
same rules as described above, except that they should be prepended by a
single
underscore. Thus "_Buffer" would be a system private
variable, "_GIS_Color" a private symbol symbol for a class in
a public module, and "_lastSize" a private symbol for a user
class.
| Dianne Kyra Hackborn <hackbod@angryredplanet.com> | Last modified: Thu Oct 17 21:37:40 PDT 1996 |