Rcgi - running R over the web
=============================

You may find reading other files more appropriate:
   CHANGES  documents differences between versions of Rcgi
   INSTALL  gives installation instructions
   README   details the licence that Rcgi is released under
   HOWTO    is a web-author's guide to using Rcgi
   

Using Rcgi in websites HOWTO
============================
[Last revised with release 3]

[NOTE: This guide is far too hack-ish and probably doesn't
explain things at all well.  I would _love_ a version written
by someone who hasn't written the code.]

Basically, you call Rcgi as you would any other CGI script, by
using the HTML <FORM> tag.  The simplest case is the FORM
returned by the script when given no input at all:

<FORM METHOD=POST ACTION="/path/to/Rcgi/script">
<TEXTAREA NAME="INPUT" ROWS=5 COLS=64>
</TEXTAREA><BR><INPUT TYPE=SUBMIT VALUE="Go!">
</FORM>

This presents an input box and a button marked "Go!" which
will execute the contents of the box.  The next level of
sophistication is reached by adding hidden code to the
webpage, like so:

<FORM METHOD=POST ACTION="/path/to/Rcgi/script">
<INPUT NAME="INPUT" TYPE="HIDDEN"
VALUE="library(eda)">
<TEXTAREA NAME="INPUT" ROWS=5 COLS=64>
</TEXTAREA><BR><INPUT TYPE=SUBMIT VALUE="Go!">
</FORM>

Here we have an extra INPUT field which will load the eda
library into R before executing the contents of the input
box.  Of course, it would be possible to use these HIDDEN
elements to almost completely automate the process and just
present the user with an opportunity to choose the data or
final analysis.

There are two further methods for loading code and objects
into R with Rcgi which are beyond the scope of this document
[for now - I may add them later if people want to use them]:

- Placing a .RData in the Rcgi output directory to preload
      functions/data objects into Rcgi's workspace;
- Using other CGI scripts to generate Rcgi input (similar
      to Rweb modules);
      
Presentation
------------

A useful "tip": Rcgi can pass the user back to the HTML
document it was called from, if you set <INPUT TYPE=HIDDEN
NAME="CALLER" VALUE="http://your/url/here/">.  But you could
keep the Rcgi code for each exercise on separate pages which
you call from the main notes with a link of the form
  <A HREF="/path/to/new/page" TARGET="_new">link</A>
to open it in a new window which the user can do the Rcgi
work in and then close it.

Actually, this has other benefits: you can use the same
course materials even if you change system from Rcgi to
another web-based statistics system; and it separates the
computation work from the course notes, so users can flip
between the two easily, keep the computations in view for as
long as they like and "play" with the calculations more
easily.

