Location: PHPKode > scripts > servertime > servertime/readme.txt
servertime class readme.txt doc file
Peter Klauer, September 7 2003
hide@address.com

Changes:
October,   26 2003: Optional starting within the body tag per onload="clock()"
                    (see Synchronisation)
October,    3 2003: New Feature $offset_hours. Idea from Martin Link
October,    1 2003: New Language "french" from Eric Mathieu
September, 25 2003: New switch $ucaseampm for uppercase or lowercase am/pm.
                    New Feature: Alarm clock times and output of alarm messages
                    using a user defined php page. 
                    New vars: $alarmon, $alarmdate, $alarm, $onalarm, $alarmpage.
                    Ideas and code contributions from Paul Hargreaves. 
September, 10 2003: New Switches "military" and "showdate" from Paul Hargreaves
September, 11 2003: New Section "Synchronisation" 

Themes covered by this document: 

Functions in the class
Variables in the class
Example
Synchronisation

This class is called "servertime" and shows approximately the time of the server 
from which it had started. If $offset_hours is defined it will display the time
and date plus $offset_hours. Javascript has to be enabled to have the clock work.
The time is shown in a digital text clock which is situated in a <div> tag. The
servers time is not shown in realtime: Until the time is taken over into the
page and the javascript begins to run a cerain time span passes. Afterwards the
clock runs with local speed. Please refer to the last section "Synchronisation".

The feature "alarmtimes" allows the class to announce events for certain days
and times. For example a sports page may announce a match that takes place at
this moment (or in a few moments).

You can test some of the variable settings for servertime on this page:
http://www.ingoknito.de/scripts/servertime/index.php

********************************************************************************
********************************************************************************
Functions in the class servertime:
********************************************************************************
********************************************************************************

InstallClockHead()
InstallClock()
InstallClockBody()
Help()

********************************************************************************
function servertime::InstallClockHead()
********************************************************************************

This function is to be placed into the <head> section of the page. It installes
the array of month names, the initial time value "digital" which is loaded
with the current time from the server and a very common javascript function
named "writeLayer" which does the writing of the clocks content into the page.
I fount this function in so many places that I can not tell you who has it done.

On
http://beta.experts-exchange.com/Web/Web_Languages/JavaScript/Q_20631686.html

you fill find notice of a similar writeLayer function, but I do not have it
from there and can not tell any more where I found it. I worked it over using
Mozilla's Javascript Console until it did not show any more warnings. The clock
will not make any output to the console if correctly installed.

The following class variables cause installclockhead() to do something:

language shorthmonth showdate onalarm alarmon offset_hours

The following class variable is set to true when installclockhead() has run:

ok_head

********************************************************************************
function servertime::InstallClock()
********************************************************************************

This function is to be called in the place where the clock shall be displayed.
It must be placed after installclockhead() and before installclockbody().

The following class variables cause InstallClock() to do something:

divclass divstyle divtag divid title ok_head

The following class variable is set to true when installclockhead() has run:

ok_clock

********************************************************************************
function servertime::InstallClockBody()
********************************************************************************

This function is to be placed near the very end of the page. It installes the
javascript function "clock()" and the first call to this function.
One of the improvements of this class facing the old script is that there is
no need to put a kick starter "onload='clock()'" into the <body> tag.

The following class variables cause installclockbody() to do something:

language military showdate ok_head ok_clock
alarm alarmon onalarm alarmdate ucaseampm

********************************************************************************
function servertime::Help()
********************************************************************************

This is just a little extra function giving a short instruction how to use this
clase in case this readme.txt is lost.

********************************************************************************
********************************************************************************
Variables in the class
********************************************************************************
********************************************************************************

divid        string    Holds the default id name of the clock tag.
                       'Pendule' is the default id name.
divstyle     string    Holds the default style string for the clock tag.
                       'position:absolute;' is default for making NS 4.7 work.
                       I think this is deprecated and could be killed with a ''.
                       As a matter of fact the clock will overwrite the next
                       following line in some browsers if this default value is
                       kept. But I am not yet ready to drop NS 4.7 out of
                       the scope of this class.
divtag       string    Holds the clock's tag "species".
                       'div' is default, other possibility: 'span'.
divclass     string    Holds a classname for the divtag. The class must be 
                       defined in an external style sheet or in a <style>
                       section in the <head> of the page.
                       '' is default: an empty string.
title        string    This is a piece of text which precedes the time sting.
                       'Serverzeit: ' is the default value.
                       You can put anything there. My favorite: an empty string.
language     string    Holds the language for the date format and the month
                       names. 'german' is the default value. Other languages
                       are 'english' and 'french'.
shortmonth   bool      If set to true, the month names will show up only 3 chars
                       long. If set to false, the whole month names will be
                       displayed. False is the default value.
military     bool      If set to true, the time will be displayed in 24h format.
                       If false it will be the 12h format. If the language is not
                       "german" "am" or "pm" will be shown when in 12h standard
                       format. True is the default value.
showdate     bool      If true then day, month and year are shown. No date is
                       shown when false. Default is true.                     
ucaseampm    bool      Uppercase am/pm? Default is TRUE.
alarm        array     Array of time values in military (24h) format, with or
                       without date part. When the date part is included, the
                       format string is "YYYY-MM-DD HH:mm"     
                       
                       The basic format for entries is:
                       
                          $st->alarm['HH:mm'] = 'Message to be shown';
                       
                       Example: 
                       
                       with date part(alarmdate = true)
                       
                          $st->alarm["2003-09-19 01:25"] = "1st+alarm";
                       
                       without date part (alarmdate = false)
                       
                          $st->alarm["01:25"] = "1st+alarm";
                       
alarmdate    bool      Hint for the class, telling if the array "alarm" contains
                       date parts. Default value is FALSE.            
alarmon      bool      The class tries to show the alarms. Default is FALSE.
onalarm      string    Name of a javascript alarm function. Default is the 
                       function of the class "doAlarm", but any other javascript
                       function defined outside of this class can be given. 
alarmpage    string    Name of a page which will output the alarm message and
                       that will be loaded from doAlarm(). Default: "alarm.php".
                       If alarmon is TRUE and onalarm is "doAlarm" then the
                       presence of the page "alarmpage" is checked and the script
                       will be terminated if it is not there. 
alarmpagew   integer   Width of the alarmpage in pixel. Default is 200.
alarmpageh   integer   Height of the alarmpage in pixel. Default is 200.
alarmpageopts string   Additional options. 
                       Default: "scrollbars=yes, resizable=yes"
offset_hours integer   This var changes the hours of the displayed date and time.
                       Set this to any reasonable integer value, positive or 
                       negative. The date part will be changed if necessary. 
                       Default value is 0.
bodyonload   bool      Must be set to true ONLY WHEN the javascript function 
                       clock() was called in the body tag of the page per
                       <body onload="clock()">. Then the calling of clock() per
                       InstallClockBody() is surpressed.
                       
                       Error 1: Clock runs at double speed: Programmer forgot
                       to set this var to true after using 
                       <body onload="clock()">                                                                     
                       
                       Error 2: Clock does not run at all: Programmer forgot to
                       use <body onload="clock()"> after setting this var to true.
                       
                       Default value: False
                       
ok_head      bool      Do not touch it. It is an attempt to make the installation
                       of the class more easy.
ok_clock     bool      Do not touch it. It is an attempt to make the installation
                       of the class more easy.                       
                     
********************************************************************************
********************************************************************************
Example:
********************************************************************************
********************************************************************************
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Test Servertime Klasse</title>
<?php

include 'inc_servertime.php';
$st = new servertime;

$st->InstallClockHead();

?>
</head>
<body>
<?
$st->InstallClock();

$st->InstallClockBody();
?>
</body>
</html>

********************************************************************************
********************************************************************************
Synchronisation:
********************************************************************************
********************************************************************************
At first Servertime gets the time from the server. Then Javascript gets startet 
after the whole web page has loaded. There may be some delay until the clock 
really begins to run. When finally the clock runs, it runs at the speed of the 
computer of the surfer. Mostly the workstations wish to make up the lost time and 
do even better than the server does. They perform up to 5 minutes per hour 
better. To have workstations the right server time it is a good idea, to have 
them refresh the page every some minutes (here it's two minutes) with 

<meta http-equiv="refresh" content="120" />

to synchronize server time and local javascript. The line
<meta http-equiv="refresh" content="120" /> is to be placed into the <head>
section of the page. Please note that if the page reloads there may be a 
jumping effect that may disturb the users pleasure reading your page.
 
To achieve faster starting times until the clock begins to run it is possible to
force the starting of the clock per <body onload="clock()">. Then the class has
to be told about this fact because the clock will run at double speed if not.
Here the example using the <body onload="clock()">:

...
<body onload="clock()">
<?
$st->bodyonload = true;
$st->InstallClock();
...
  
Return current item: servertime