html.readme

THIS SCRIPT WILL RUN ON BOTH REGISTERED AND UNREGISTERED COPIES OF AEMAIL

The html.aem script is used to read html attachments in email.  It can also
be attached to a function key or menu item and used to activate your
browser to display a web address that is contained within a message.

The script requires the "rexxsupport.library" to run.  This library
normally comes with your Amiga at version 2.1 or greater.

When reading HTML attachments, the script uses your browser to read the
HTML file.  This script can use either IBrowse or AWeb to read and display
the html document.  The script will have to be modified to use a different
browser.

The script chooses which browser to use based upon the ASSIGN statements in
your system.  If you have more than one browser with the appropriate ASSIGN
statements, it will choose the appropriate browser based on the following
priority:

    IBrowse
    AWeb3
    AWeb-II

To use a different priority or to remove a particular browser you can
re-arrange or remove the appropriate statement sections that use
SHOWLIST().

Also in this directory is an alternate mailcap file which is required for
displaying the html document.  You will notice in the mailcap file the
first line which is as follows:

    text/html; "run >NIL: rx html.aem %s"

This line calls the html.aem script to display the html attachment with
your browser.  To use the mailcap, the script, "html.aem", should be moved
to your REXX:  directory.  Notice that the call line says "run".  This is
required to allow the script to become detached from AEMail so that ARexx
commands can be directed back to AEMail.  If the "run" is not present,
AEMail will become frozen when you attempt to display the document.

You can move this mailcap to your mail directory when you install AEMail
(if you install at the "expert" level) or, using the Viewer page of the
Configuration screen, you can create a "text/html" statement in your
mailcap.  If you use the Viewer page, you do not have to move the script to
the REXX: directory since you can specify the full path name in the rexx
script call.

                             HOW TO IMPLEMENT
                             ----------------

Copy the mailcap file over your existing mailcap file or create a mailcap
entry for "text/html" in your mailcap using the Viewer page of the
Configuration Setup Window.

Move the html.aem script to either your program directory or the REXX:
directory.  If you create your own mailcap with the Viewer page of the
Configuration Setup, you can create a line for:

    text/html

and locate the ARexx script using the file requester in AEMail's ARexx
drawer.  Be sure the full path is specified.  If you do this you do not
have to move the "html.aem" script.

The script is designed specifically for IBrowse or AWeb and must be
modified if another browser is used.

At the beginning of the script you will notice the section beginning:

    IF (file = "") THEN DO

this is used to pick up the variable (the GETVAR statement) that is the URL
when you are activating a web address embedded in a message.  If you are
reading an HTML attachment, the local file address used is passed to the
script so that "file" will not be empty which bypasses these statements.

Since IBrowse doesn't normally create an assignment for it's program
directory, you will have to add an assignment for the IBrowse program
directory to your startup sequence.  This is only necessary if you are
using IBrowse.  AWeb does create the assignments.  Note, however, that the
assignment for AWeb3 is all in upper case letters.  Even though the assign
statement specifies upper and lower case letters, you have to specify the
assign with all caps for ARexx to properly find it.

If you wish to use another browser, you will have to add an ASSIGN for that
browser's program directory and modify the following statements:

    IF SHOWLIST('A', "IBROWSE") THEN
        DO
        wwwdir = "IBROWSE:"
        wwwprog = "IBROWSE:Ibrowse"
        wwwport = "IBROWSE"
        END

You would change the SHOWLIST('A', "IBROWSE" line so that it references the
ASSIGN for the directory containing your browser.  You will have to
substitute the directory containing your program ("wwwdir" variable) for
"IBROWSE:", the program name ("wwwprog" variable) for "IBROWSE:Ibrowse",
and the ARexx port name of your browser ("wwwport" variable) will have to
be substituted for "IBROWSE".

The section of the script that begins with

    IF (wwwport = "AWEB." THEN

is used to obtain the port number for AWEB.  If you are using AWeb and AWEB
is not running this will default to AWEB.1

The section beginning:

    IF ~ SHOW('P', wwwport) THEN

is used to load your browser if is not already loaded.

The line:

    olddir = PRAGMA('D', wwwdir)

is used to change the directory to the directory containing your program.
This is necessary with some browsers (especially IBROWSE) so that they can
find the modules and files they need.  IBROWSE gurus in some instance if
this statement is not there.

The section beginning:

    IF (file2 == 'T:AMtemp') THEN DO

is used to set up the URL call for a local file if the file name "T:AMtemp"
is passed to the script.  This is the standard name and place AEMail uses
for temporarily storing attachment files.  The name must be changed to
t:amtemp.html since browsers require the .html suffix on the name.  The
full call that browsers use is:

    "file://localhost/t:amtemp.html"

which is stored in the variable "file".

The final part of the script:


    ADDRESS VALUE wwwport

    IF (wwwport = "IBROWSE") THEN DO
        "INFO SCREEN"
        ADDRESS AEMAIL1 SCREENTOFRONT result
        "GOTOURL" file
        END
    ELSE DO
        "SCREENTOFRONT"
        "OPEN" file
        END

causes things to happen a bit differently if you are running IBROWSE versus
AWEB.  The statement:

    ADDRESS VALUE wwwport

sets your ARexx port to the correct port name.  If the port was "IBROWSE"
then this action takes place:


    "INFO SCREEN"

This obtains the public screen name for your browser.  Since IBROWSE uses
MUI, this is a standard stament for any program using MUI.  The next
statement:

    ADDRESS AEMAIL1 SCREENTOFRONT result

is a call to AEMail to switch your browser's screen to the front.  "result"
is the screen named obtained through MUI of the browser's public screen.

The statement:

    "GOTOURL" file

is an ARexx call to IBROWSE to display the html document.

If your browser is not IBROWSE, then it is assumed to be AWEB.  The
statements after ELSE are used for AWEB.  Since AWEB does not use MUI, it
has its own statement for bring the AWEB screen to the front.  This is:

    "SCREENTOFRONT"

Then the call to AWEB to display your URL is "OPEN" rather than "GOTOURL"


                                HOW TO USE
                                ----------

When you get an email with an html attachment (or text body) call up your
attachment requester, select the appropriate attachment (it will say
"text/html"), and click on VIEW.  Your browser will be loaded (if it is not
already loaded) and the page will be displayed.  You should have an open
connection to your Internet server when you call your browser since many
html attachments obtain information over the internet (such as graphic
images).

When you are done viewing the html document you should either close the
browser or switch it's screen to the back to re-display the AEMail screen.

For browsers that open on the Workbench, there is an AREXX script called
AEMAIL_TOFRONT.aem.  This script will automatically close your browser and
bring the AEMail screen to the front (see the AEMAIL_TOFRONT.readme) and
must be installed in the AREXX portion of your browser.

To use this script to display embedded web addresses in a document you will
have to bind the "html.aem" script to a function key in AEMail and assign a
menu title.  To do this call up the ARexx page of the AEMail configuration
screen and select the function key you want the "html.aem" script bound to.
Enter the script name (full path name) in the string gadget.  Be sure you
have AREXX selected in the cycle gadget.  You can use the file folder glyph
to call up the file requester to locate the script.  Then, if you want a
menu item, enter a menu title in the "Menu Title" string gadget.  Then save
the configuration.

When you receive a message with an embedded web address just double click
on the line containing the web address.  The web address will appear in
the Clip window.  Now either hit the function key that you bound the
html.aem script to or select the menu item indicate by the "Menu Title"
and the web page will be called up.  You will, of course, have to be
connected to your Internet provider for this to work.

If for any reason your browser can not be loaded, multiview will be called
to display the document as a text document.