Using HyperCard as a CGI Application - An Example

(See HyperCGI.html for a more general description of the subject)

This archive, containing the HyperCard stacks"People.acgi" and "Home", and a WWW form "People.html", in addition to this Readme file (Text only and HTML version), is both an example for the potential of Hypercard as a CGI application, and a basic version for a Web-accessible database which can be easily expanded. (If you repeatedly download an incomplete version of the archive, try an ftp-download.)
The project is a simple address database, which allows the input, modification, and deletion of datasets, and the searching of the database via the WWW. In the current setup, input is allowed from every Web surfer coming by (so you could use it as your guest book), but can be restricted to, e.g., clients from certain domains (see below for the necessary modifications), or can be password protected from the Web server (see the manual of your server program for details). Currently, every single dataset is password protected, "belonging" to the person who entered it, and allowing him/her to later modify or delete the entry. (If no password is used on entry, a master password is assigned to prevent tampering with the data). You as the owner of the stack have superuser privileges simply because you can access all data from within HyperCard.

It should be fairly easy to modify the project for your wishes:

How to use it:

Some remarks

When you look at your entries directly in Hypercard, you may notice that some chars look funny. The Web uses the ISO Latin-1 char table for ASCII>127, the Mac has its own table. For its purpose as a Web database, the stack just stores the text as it comes (ISO Latin encoded) and sends it back unmodified. You can type directly into the fields of the stack, but if you enter higher ASCII chars, they probably will look differently on the Web. Beware of entering quotes (") and be careful with <> when typing directly into the stack (see next paragraph).

The program converts returns in the multiline field to <BR> (the Web browser converts them back to returns), and quotes (") and < > to their character entities &quot; &lt; &gt;
Randomly placed quotes can do bad things in Hypertalk, and < > would otherwise be interpreted as HTML tags. If you want to allow the inclusion of HTML tags (which makes it possible to enhance text with <STRONG> or to include a link in the message, but also to submit defective code which messes up the page), remove the various QuickReplace((it),"<","&lt;") etc. in the script of People.acgi.

It is possible and fine to enter character entities into the Web form. They are of the format &entname; with entname the symbolic name of the char, or &#number; with number representing the decimal ASCII number (ISO Latin, of course) of the char (e.g., &nbsp; or &#160; for a non-breaking space). Use &amp; to represent the ampersand (&).

Technical details

How does it work internally (also important for modifications)?
The Home stacks waits for an Apple event to come in, checks whether it is from the Web server, then extracts the path args (direct parameter) and uses them to decide which further data have to be extracted from the Apple event, and which stack and which function to call. You can have many different database stacks open and branch to them depending on the incoming data. If you want to restrict access to certain domains, this is the point to get at the relevant data (request appleEvent data with keyword "addr" gives the name of the clients computer, or its Internet number, if no name is available, request appleEvent data with keyword "Kcip" always returns the Internet number of the client computer). Don't forget to pass all necessary data to the function.

If a new dataset is submitted, the Web data are parsed and distributed to Hypercard variables, a new card is created (chance to check for the number of cards here), and the variables are written to the fields. If no password has been entered, the default password is put into the relevant field.

If a search, modification or deletion is requested, the database is searched to see whether the criterion is met by several entries (in this case, a summary is returned, with each line containing a link to one of the cards, with the primary request as the direct argument of a search request: <A HREF="Hypercard.acgi$Delete?ID"> with ID an identifier number for the dataset; choosing one of the entries triggers the requested action), or fits one entry only. In the later case, the full data of the found card is returned: in reply to a search as ordinary text; in reply to a deletion request, as part of a form which contains the identifier for the dataset in a text field of type "hidden" (so it is not shown to the user and cannot be modified, but is sent back with the conformation of deletion, allowing the identification of the correct dataset), and a field for the password. In reply to a request for modification, the data are inserted into the fields of a form similar to the data entry form, ready to modify; as for the deletion, a password is requested and the identifier included in a hidden field. The password is checked for identity (get field "Secret"          if it is Password then (Action) else (Rejection)). The program performs the action and confirms it by replying the new version of the dataset, or the dataset before deletion.

Some error handling is built in and produces a reasonable reply to the client: for the case a dataset has been deleted before the modification/deletion has been submitted; if an ID is requested which is not present in the database, if the direct argument or the path args are other than expected.

Potential additions

The stacks use the following Xternals:

This is just a little tested demonstration project. If you find bugs, I am always interested to know them, but if you present a solution for them, I am even happier. That's one advantage of HyperCard: you have access to the complete source code, so you can (and should) have a look by yourself. But comments are always welcome (don't be too critical with the code: if I were a real programmer, I might have done it far better, but then I would probably not have bothered with HyperCard but had used C or Java instead :-).


[To our home page][Our lab and projects][To the software archive][Hypercard as a CGI application]

Last edited: October 23, 2001 by KaiFr