Back to Browser Object
Up to Table of Contents
Ahead to Check Box Object

CGI Object

The CGI (Common Gateway Interface) object lets your application call CGI programs. CGI is a standard for interfacing external applications with information servers, such as http or Web servers. You need to have an experienced programmer create any CGI programs you plan to use.

Typically, you use a CGI program to perform operations that enhance the performance of your application in some way. For example, if you want to do a mathematical computation for your applet, you could do the operation in a CGI program. Also, CGI is often required to make full use of several objects such as the Check Box, Combo Box, List Box and Radio Buttons.
Use the CGI tool to draw a CGI object. The tool appears as follows:

CGI Object Appearance

When you draw a CGI object it appears as shown in the figure to the right. However, CGI objects are never visible at runtime.

Using CGI to Enhance other Objects

Use the Filename property to set the name of the CGI program you want to run. Note that the CGI object does not block user interaction while the CGI program is executing. This means that the user can continue to interact with your Jamba applet while the CGI application runs in the background. If necessary, set the Enabled property of the other objects on the page to False to achieve blocking behavior.

Sending Information to the CGI Program

You can use the CGI object to significantly enhance the functionality of other Jamba objects. Specifically, your application can send one or more values to a CGI program via the ParameterList property. For example, consider a CGI program that is set up to evaluate the state of CheckBox1 in your application. You would set the CGI object's ParameterList property to CheckBox1.Checked. This would send either the value True or False to the CGI program, depending on the state of the object. The CGI program can then evaluate the received value and send back a response if necessary. If you need to send more than one value to the CGI program, separate each Object.Property from the next using a semicolon (;).

Returning Object.Property Values to the Application

If your application needs to receive information back, you must set the CGI object's Response property to True. Also, you need to code the CGI program to return information using the required syntax. If you want the CGI program to set a property in the calling application, make sure that it returns information in the form of Object.Property="Value". For example, if you want the CGI program to set a Graphic1 object's Filename property to birds.gif, the CGI program must send the following to the application: Graphic1.Filename="birds.gif". Similarly, if you want the CGI program to set a method in the calling application, make sure that it returns the information in the form of Object.Method(). For example, if you want an Audio object called Audio1 to play, send back the information Audio1.Play(). If the CGI program returns more than one piece of information, follow each item with a NewLine.

Triggering Events in the Application

You can also let your CGI program use the TriggerEvent() method to trigger an event in the calling application. To do this, the CGI program returns information using the following syntax:

Application.TriggerEvent ( Object,Event )

where:

Object is the name of the object you want to affect

Event is the event you want to occur

For example, if you want the application to behave as if PushButton1 was clicked upon completion of the CGI program, make sure the program returns the following value to the application:

Application.TriggerEvent (PushButton1,Click)

Other useful Jamba tools that work in conjunction with the TriggerEvent() method are the CGI object's Response1 through Response5 events. These events let you set up multiple To Do Lists in the CGI object and allow the CGI program to trigger which list will execute. For example, in CGI1's To Do List you can set the Response1 event to display Page1 and play Audio1 and set the Response2 event to display Page2 and play Audio2. The CGI program evaluates a user's interaction and returns either Application.TriggerEvent (CGI1,Response1) or Application.TriggerEvent (CGI1,Response2). The former information causes the Response1 To Do List to execute and the latter causes the Response2 To Do List to execute.

Hint: Keep in mind that whatever purpose a CGI program serves, it should not take too long to process. Otherwise, the user might become frustrated if he or she is forced to wait.

Security

The CGI object lets authors execute applications on the http server through the Common Gateway Interface (CGI). Since the program is executable, it is basically the equivalent of letting the world run a program on your system. Therefore there are some security precautions that need to be taken when it comes to using CGI programs.

CGI programs need to reside in a special directory, so that the Web server knows to execute the program rather than just display it to the browser. This directory is usually under direct control of the webmaster, prohibiting the average user from creating CGI programs. There are other ways to allow access to CGI scripts, but it is up to your webmaster to set these up for you.

CGI Programming Hints

If you have a version of the NCSA HTTP server distribution, you will see a directory called /cgi-bin. This is the special directory mentioned above where all of your CGI programs currently reside. A CGI program can be written in any language that allows it to be executed on the system, such as:

  • C/C+
  • FORTRAN
  • PERL
  • TCL
  • Any UNIX shell
  • Visual Basic
  • AppleScript

    If you use a programming language like C or FORTRAN, you must compile the program before it will run. If you look in the /cgi-src directory that came with the server distribution, you will find the source code for some of the CGI programs in the /cgi-bin directory. If you use one of the scripting languages instead, such as PERL, TCL, or a UNIX shell, the script itself only needs to reside in the /cgi-bin directory, since there is no associated source code. Many people prefer to write CGI scripts instead of programs, since they are easier to debug, modify, and maintain.

    • Lesson: Using CGI to Act on a List Box Selection

    In this lesson, you use CGI to evaluate a user's selection and change a property based on that selection. The application will contain a List Box that displays a list of animals, a CGI object, and a Graphic object. When the user clicks on an animal, the CGI object sends the selected item to a CGI program. The CGI program evaluates the selected item and returns information that sets the Filename property of the Graphic object to display the appropriate animal.

    Note: You can also do this kind of task without CGI if you want to display an explicit list of Filenames in the List Box instead of a list of animals. See the List Box object for more information.

    A completed version of this lesson, called lesn_8, is located in the \Jamba\lessons directory.

    First you'll draw the three objects.

    Next you'll set up the CGI object. Use the Filename property to set the name of the program to run.

    Use the Filename property to set the name of the program to run.

    The Response property lets the application know that a response is expected back from the CGI program. Now you need to set the value of the ParameterList property to the property you want to send to the CGI program. You will send the List Box's SelectedItemData property because it will contain the item that the user clicked on. Specifically, you need to specify the name of the object, followed by a period, followed by the name of the property. (Hint: To send more than one value you would separate each value from the next using a comma.)

    Next you'll set the List Box properties and To Do List.

    Use the ItemList Property to set the contents of the ListBox.

    The items are returned to the Value field for the ItemList property. They appear in the required format which is a semicolon (;) delimited list.

    At runtime, the List Box will appear similar to the following:

    Now you need to set the To Do List for the List Box.

    The default event is Create. You need to change this to Select because you want the List Box to cause a To Do Item to occur when the user makes a selection.

    You need to set up a To Do List item that causes the CGI object to run its program when the user makes a selection.

    Note that Run() is a method that doesn't require any information in its Value field. You have already specified the program to run via the CGI object's Filename property.