METHODICA TICKER (JAVA APPLET)
==============================



Introduction:
------------

METHODICA TICKER is brought to you by
methodica herger & krasznai, Information Technology (methodica).
All components are Copyright (C) 2002 by methodica. All rights are reserved.

The software contained in this archive file is freeware. Thus, its use is allowed in non-commercial and commercial contexts without a fee. The archive contains all components as well in executable and source code form.

You may re-distribute this software as long as you abide by the following rules:
1. The file "readme.txt" (you are reading it right now), all the copyright remarks and disclaimers here and in the source files are delivered together with the executables and source code files.
2. You don't charge recipients of this software. As an exception you may charge a minimal fee for storage media you use and copy work you do.
3. You may enhance or modigy and recompile the source code to meed your needs under the condition that all enhancements and modifications are given to the public domain as freeware as well. We might publish your enhancements on our server if you send us a copy.

The METHODICA TICKER embraces an applet (ticker.class), and an expandable set of text servers. 
Ticker.class is able to statically display or scroll text horizontally. Most of the presentation attributes can be configured via parameters.
Text servers supply the ticker.class with text from different sources, e.g. making it a text file viewer, a standard or an internet time clock, or an elapse time clock.
You may write your own text servers based on the abstract "txtsrvr" class (files "txtsrvr.java" and "txtsrvr.class").



Disclaimer:
----------

Methodica will under no circumstances be liable for damages you might experience, directly or indirectly, while using this software. Since the source code is distributed, you easily may convice yourself of the fact that is does not contain any offending or damaging code. If under the laws where you intend to use this software such an absolute exclusion of liability for software products is not legal you are not allowed to use the software.
The software is unsupported while bug reports and suggestions for enhancements are greatly welcome. This means, we quite care about it but cannot give it any prioriy.


Contents of the "ticker26.zip" archive:
--------------------------------------

readme.txt / liesmich.txt               (This text file, english / german version)
demo.txt                                Text file, used by t_ticker.htm with the FILDTXT text server class
tickercls.zip                           The same as (*)
t_ticker.htm                            Test and demo HTML page
    without_log.zip              (Entire archive, logging feature disabled)
        tickercls.src                   All class source files
            ticker.java                 Ticker source (standard, source, indirectly loads text server classes)
            urlldcls.java               URL handler base class, (standard, source)
            logger.java                 Dummy Logger class (standard, source)
            txtsrvr.java                Textserver base class (standard, source)
            deftext.java                Default text server class (standard, source)
            fildtxt.java                File reader text server class (standard, source)
            datimtxt.java               Date/Time text server class (source)
            itimtxt.java                Internet time text server class (source)
            y2kdtxt.java                Date/Time difference text server class (source)
        tickercls.zip / tickercls.jar   (*) Class archives, logging feature disabled
            ticker.class                Ticker class (standard, executable)
            urlldcls.class              URL handler base class (standard, executable)
            logger.class                Dummy Logger class (standard)
            txtsrvr.class               Textserver base class (standard, executable)
            deftext.class               Default text server class (standard, executable)
            fildtxt.class               File reader text server class (standard, executable)
            datimtxt.class              Date/Time text server class (executable)
            itimtxt.class               Internet time text server class (executable)
            y2kdtxt.class               Date/Time difference text server class (executable)
    with_log.zip                 (Entire archive, logging feature enabled, details see below)
        tickercls.src                   All class source files
            logger.java                 Client-side logger class, source
                                            [ all other .java files as above ]
        tickercls.zip / tickercls.jar   Class archives, logging feature enabled
            logger.class                Client-side logger class, executable
                                            [ all other .class files as above ]
        setlogent.cgi                   Host-side logger script
        logger.cfg                      Logger configuration file



General Installation Instructions:
---------------------------------

1. Decide whether you want logging enabled or not.
   If yes, continue with the files from the "with_log.zip" archive, else continue with the "without_log.zip" archive.
2. Expand the selected archive to a newly created directory.
3. Take either the "tickercls.zip" or the "tickercls.jar" archive and copy it to the directory on the server where your HTML-pages reside or to the one the "CODEBASE=..." tags in your HTML-pages are pointing to.
   Also copy the "demo.txt" and the "t_ticker.htm" files to the same directory for later testing.
  
   ---- only if logging enabled (see below) ----
4. Copy the "setlogent.cgi" file to the /cgi-bin/ (or the appropriate script directory) on your server. Note to correctly set the configuration parameters in this file.
5. After having correctly set the "LogScript" key in the "logger.cfg" file, copy it to the same directory as the "tickercls.xxx" archives.
   ---- end only if logging enabled ----

6. Execute the "t_ticker.htm" file to test your installation.

To make shure legacy HTML-pages without the "archive=tickercls.zip" / "archive=tickercls.jar" tags will continue to work, unzip the class files from the "tickercls.zip" file and put them in the same directory as you store the archive file.



The Logging Feature in More Detail:
----------------------------------

The ticker.class applet has been designed to log its own and its text servers usage.
Logging is handled by the client-side "logger.class" and its server-side counterpart, the PERL script "setlogent.cgi". Logger.class is called by ticker.class whenever it is loaded. Logger.class calls "setlogent.cgi" or any other server-side script configured.

The following configuration parameters are to be adapted in the file "logger.cfg":

(1)   LogScript=http://www.yourdomain.com/cgi-bin/setlogent.cgi
(2)   MaxLogSize=50000

Where "LogScript" (1) is the URL where the "setlogent.cgi" or your own equivalent can be found. The script should be copied to the standard scripts directory on your server (usually /cgi-bin/). Make shure it has the correct attributes for execution (i.e. 755).
The "setlogent.cgi" script accepts the maximum size a log file is allowed to be. Whenever this maximum is reached, the script swaps the log files attaching the digit "0" to the previous file's name, "1" to to previous-previous file's name, etc. This parameter is taken from the "MaxLogSize" (2) entry in the config file by "logger.class" and given to the "setlogent.cgi" script as the MAXSIZE parameter.

The following configuration parameters are to be adapted in the file "setlogent.cgi":

(1)   #!/usr/bin/perl
(2)   $serverRoot="/home/yourdomain/Web";
(3)   $httpRoot="www.yourdomain.com";
(4)   $logtempl = "%HOST% - %USER% [%CDATE%:%CTIME%] \"%MODE% - %PROT%\" - - \"-\" \"%TEXT%  Agent: %USRA%\"";
(5)   $inmxlfsize = 50000;
(6)   $applfname = "applet";
(7)   $applfext = "log";

The absolutely first entry (1) in the script points to the PERL interpreter on the server. Usually it's as show above.
The "serverRoot" parameter (2) shows the path on the server machine to your web files. It's the same directory where you usually are storing your HTML pages. On a MS Windows machine it could look like "C:/Web/mydomain".
The "httpRoot" parameter (3) is your host name (www.xxxx.yyy). With a personal web server on your workstation it might be "localhost".
The log template (4) string describes what information the script should write per log entry. The following substitutes are accepted in templates:
      %HOST%  : Name or IP address of the requesting host
      %USER%  : User identifier (if any)
      %CDATE% : Current system date
      %CTIME% : Current system time
      %NOW%   : Current system date and time
      %MODE%  : Request mode (e.g. GET, POST, etc.)
      %PATH%  : Script path information as provided by the host
      %PROT%  : Protocol used (e.g. HTTP/1.1)
      %REFR%  : Referer URL (if provided by the browser)
      %USRA%  : User agent (identifies the user's browser)
      %TEXT%  : A specific text provided by the "logger.class";
                contains the document path (where the applet is embedded)
                plus the code path (where the applet code is taken from)
Special characters are taken literally when preceeded by a backslash (\).
(5) is a default value for the maximum log file size in Bytes. Usually this value is explicitely set by "logger.class" according to the "MaxLogSize" entry in the "logger.cfg" file.
(6) and (7) declare the log file name and extension respectively to be used. Taking the above example, the current log file would be named "applet.log", the older ones "appletN.log", etc. "N" stands for the digits "0..9" which are added by the "setlogent.cgi" script. "applet9.log" would be the oldest, "applet0.log" the youngest but the current file.



Enjoy! Regards,

methodica herger & krasznai
Fellstr. 3, PO. Box 80
5413 Birmenstorf AG, Switzerland
http://www.methodica.ch
mail@methodica.ch
