Hosting a Clock
adding one to your own page
is nearly easy as pie
 
 
if you'd like to attach a WRLD.time clock to your web page, read on.     without much effort, you can configure the color, font and position of the digits being displayed.     add a background color or image to give it flair.     and if you wanna go hog-wild, you can create a configuration file.
 
totally insane people may go so far as to download the class files so they can use the command-line version.
   
 
 
Attaching a Clock how to put a WRLD.time clock on your web page
Config Files making your clock look as groovy as possible
On the Desktop fun with WRLD.time clocks executed from the command line
UTC Sites a list of sites which support the UTC protocol
 
 
 
    Contents          Previous    Next  Attaching a Clock     
 
       Basically, what you need to do is create an applet which references the WRLD.time class files. The most direct way of doing this is referring to the class files on sleepbot.com.
 
Here's an example of what you'd put in your web page:
   <APPLET
    CODEBASE="http://www.sleepbot.com/WRLDtime/lib"
    CODE="WRLDtimeApplet.class"
    WIDTH=***
    HEIGHT=***
   >
      <PARAM NAME="config" VALUE="***">
      <PARAM NAME="bg" VALUE="***">
      <PARAM NAME="fg" VALUE="***">
   </APPLET>
Don't worry about the carriage returns & indentation... that's just there for visual effect. I'll explain the blue asterisks in just a moment.
 
First of all, the APPLET tag tells the browser that an applet should be put in place. APPLET needs a closing tag, which you see on the last line of the example.
 
The basic stuff that an applet needs to know are the name of the applet class and where it's located. The CODE portion identifies the name of the class to display, and CODEBASE indicates where the classes are located. In this example, you're referencing the standard WRLD.time applet class (WRLDtimeApplet) from the sleepbot.com domain. That way you don't have to set them up on your own server.
 
The WIDTH and HEIGHT portions are defined by you... experiment with the applet sizing until you get something that looks nice. When sizing your window, keep in mind that the standard WRLD.time applet class reserves a 25-pixel-high row at the bottom of the applet so that it can display the WRLD.time logo.
 
The standard time-piece accepts parameters from the applet definition.... that's what the PARAM tags are for. The ones that the applet recognizes are bg (background), fg (foreground), and config (configuration file). All of the parameters are optional... you could just as easily have no PARAM tags if you wish. If you don't provide any parameters, you'll get the standard black-on-grey clock.
 
See configuration files below for full details on all these parameters and the default values for the time-piece.
 
You'll probably have noticed that there's a pair of WRLD.time clocks on each of the pages you've been looking at here. They're identical across each page, except for the background color. All that was needed to make these clocks is the fg and bg parameters... do a View Source and see for yourself.
   
 
 
 
    Contents          Previous    Next  Config Files     
 
       If all clocks looked the same, it'd be a boring, boring world. So, in the interest of preventing such boredom, the standard time-piece determines its appearance according to a configuration file.
 
A configuration file is just a simple text file. Each line in the file that is not blank and not a comment denotes a configuration setting. A line can be marked as a comment by making its first character a semicolon (';').
 
Configuration settings have the following general format:
   NAME=KEY:VALUE, KEY:VALUE, ...
NAME is the name of the setting and it is followed by an equal sign ('='); you'll see more on the individual settings below. The setting contains a series of key-value pairs, each separated by a comma (','). The KEY is separated from its VALUE by a colon (':').
 
The applicable key-value combinations are defined by the setting itself. Finally, since the setting takes up a whole line, it is terminated by a carriage return. If you need to put a comma somewhere within your VALUE, then enclose the KEY:VALUE in full quotes ('"').
 
The settings are grouped below by a rough classification. Each setting can accept certain key types. Each key type is made up of one or more key-value pairs. You'll probably have to scroll around this document a while to figure out the full inter-relationships between these things.
 
Now, before I go into great technical detail, I'll refer you to the configuration files I've already created. They're all sitting in the same directory, and the best ones to look at are Green, jonathan and Ambience. If you want to actually see one of them in action, choose it from the many faces.
 
 
Okay, the fun starts here. First, we have what I call the Global Settings which are used to describe general display components. All Global Settings are optional... the defaults for each setting are described below.
bg
the background setting.
this setting can accept the following key types:
 
a color - the background color. if not specified, it defaults to lightGrey.
an image - the background image. it's drawn on top of the background color.
fg
the foreground setting.
this setting can accept the following key types:
 
a point - the global point. its key-value pairs override the default of (0, 0). now... this may sound strange, but if you don't supply either coordinate, it actually defaults to (5, -2) so that the generic clock will look right.
a color - the global color. its key-value pairs override the default of black.
a font - the global font. its key-value pairs override the default of 16-point Courier Bold.
cron
the chronometer setting.
there are no key types associated with this setting. instead, it can accept the following key-value pairs:
 
factor - the chronometer factor.
divisor - the chronometer radix (or so jonathan called it).
fromGMT - the chronometer GMT offset.
utchost - a UTC host used to align the chronometer. if not specified, the chronometer is not aligned. there's a nice list of UTC hosts down here.
utcport - the proper port at the UTC host. if not specified, it defaults to 13.
utccgi - a URL which points to a script that returns a UTC code.
 
turns out that utchost and utcport don't work in the applet version. that's due to security hobbling in Java... the applet isn't allowed to go off to another site and make a request. however, you use utccgi to reference a local CGI script which goes out to a UTC host and prints out the UTC code it receives. if a config file contains both a utccgi and utchost setting, the script is referenced first, and if it fails, the host is referenced.
 
for a complete understanding of this setting's key types, please take a look at the WRLDcron class documentation.
window
the window setting.
this setting can accept the following key types:
 
a rectangle - the window position and dimensions. its key-value pairs override the default of ((30, 0) - (50, 50)).
 
this setting is only put to use by the command-line version. the applet version relies upon the WIDTH and HEIGHT of the applet tag to determine its size.
draworder
the draworder setting.
there are no key types associated with this setting. instead, it can accept the following keys:
 
ml, mr, bl, br and separator... see the Digit Settings below for more details.
 
basically, with this setting, you're describing to the time-piece the order in which your digits should be drawn. this would probably only be useful if your images overlapped strangely.
 
Other than that, we have what I call the Digit Settings, which are used to define the individual drawing elements of the clock. All Digit Settings are optional... if none are provided, then the time-piece assumes the text types 0-9 for each digit and a period ('.') for the separator.
 
However, it's all-or-nothing; if even one Digit Setting is provided, then all digits which are not explicitly specified via a setting are not displayed.
separator
the separator setting.
this setting can accept the following key types:
 
a text - the separator text.
an image - the separator image.
an alias reference to another setting.
 
if not specified, a separator will not be displayed.
ml, mr, bl, and br
the digit groups.
these settings allow you to generally over-ride the global settings for all digits in the group. the digit group names are abbreviations for the measure's left and right digits, and the beat's left and right digits (respectively).
 
each of these setting can accept the following key types:
 
a point - the group point. its key-value pairs override the global point.
a color - the group color. its key-value pairs override the global color.
a font - the group font. its key-value pairs override the global font.
 
if not specified, then the global settings are used for digit-specific references.
_0 thru _9 for each digit group
the digit settings.
each digit group has ten different digits... 0 thru 9. so, the setting named "br_7" is what is displayed for the beat's left digit is at seven.
 
this setting can accept the following key types:
 
a text - the digit text.
an image - the digit image.
an alias reference to another setting.
 
any digit which is not specified will not be displayed.
Now you know the names of each individual setting. Plus, you have the option to set up named alias references, which can be called anything you want.
 
For instance, if you had set up text settings for the measure's left digit, and you wanted all the digits to have the same settings, you'd could write your file with things like "mr_0=alias:ml_0" and "bl_4=alias:ml_4", etcetera.
 
Or you could write it another way by creating a new alias setting called "one" and referring to it like "ml_1=alias:one", "mr_1=alias:one" and "bl_1=alias:one". They're not necessary, but they make the file a little more legible.
 
Any point, font or color key-value pairs in the 'alias' setting override the group settings, and any key-value pairs for the digit itself override the respecitve key-values of the 'alias' settings. Just like layers on an onion.
 
Oh... and one more thing. 'Alias' settings don't cascade, so if you know what what means, don't do it.
 
 
Okay, now you know about the settings. Here are the individual key types and the key-value pairs that are used to define each:
image
the image type.
this setting can accept the following key-value pairs:
 
image - the name of the image file. if you don't specify a full URL, it's assumed to be within the document's address and port. if the filename starts with "/", it's assumed to be an absolute reference from the root of your web server. if not, then it's assumed to be relative to the directory in which the page containing the applet tag resides, or the directory where the class files reside if you're running it from the command line.
 
this setting can also accept the following key types:
 
a point - where the image should be displayed.
text
the text type.
this setting can accept the following key-value pairs:
 
text - the text to display.
 
this setting can also accept the following key types:
 
a point - where the text should be displayed.
a color - what color the text should be.
a font - font characteristics of the text.
point
the point type.
this setting can accept the following key-value pairs:
 
x - the horizontal position. this value can be either absolute, or relative to the value it is overriding. for example, "x:10" sets the horizontal position to 10, whereas "x:+10" sets the horizontal position to 10 pixels to the right of the point it is overriding.
y - the vertical position. this value can be either absolute, or relative to the value it is overriding, just like x.
color
the color type.
this setting can accept the following key-value pairs:
 
color - a hexidecimal representation of the RGB color to be used. it's just like HTML... for example, '000000' is black, 'FF0000' is red and '000080' is dark green.
font
the font type.
this setting can accept the following key-value pairs:
 
face - the name of the font face to be used. unfortunately, i don't have a full list of font names to give you. all i know is that 'Courier' and 'Times' are the standard fixed and proportional fonts (respectively).
size - the size of the font face to be used. this value can be either absolute, or relative to the value it is overriding. for example, "size:8" sets the font size to 8, whereas "size:+8" sets the font size to 8 points larger than the font it is overriding.
plain - plain font... it's just a KEY with no VALUE. this key eliminates all existing style from the font. if you want to guarantee that you wont get extra bolds and italics from the font style you're overriding, specify the plain key.
bold - bold style font... it's just a KEY with no VALUE. this key makes the font bold. it is always used relative to the font style you're overriding (unless the plain key is specified).
italic - italic style font... it's just a KEY with no VALUE. this key makes the font italic. it is always used relative to the font style you're overriding (unless the plain key is specified).
rectangle
the rectangle type.
this setting can accept the following key-value pairs:
 
x - the horizontal position, which is always absolute.
x - the vertical position, which is always absolute.
width - the horizontal size, which is always absolute.
height - the vertical size, which is always absolute.
 
The weirdest thing to get used to in configuration files is the whole 'override' thing. I'll run you through a tiny example to touch on all the aspects of overriding:
   ;  the Global Settings
   bg=color:000000
   fg=size:+4, x:2, color:FFFFFF

   ;  the Digit Settings
   separator=text:^, bold

   ml=x:+10, y:+10
   ml_5=image:five.gif

   br_8=alias:ml_5, y:-1
   br_9=alias:eight, italic, color:00FF00

   eight=text:8
Now granted, this would look like crap, but hear me through. All this clock is going to display is a separator, the 5 of the measure's left digit, and the 8 & 9 of the beat's right digit.
 
The background color of this clock will be black with no image. The global color will be white. The global point will be (2, 0), since we specified an absolute horizontal position and left the y alone; if you provide only one coordinate, the other one defaults to 0. The global font will be 100% default, since we didn't specify any key-value pairs that the font type recognizes.
 
The separator is going to be a caret, and it'll be displayed in the global font's face and size, but with a bold style. As it turns out, it doesn't make sense to do this because the global font is already bold. If you wanted to display it without the bold styling, then the setting should have the 'plain' key in it somewhere.
 
All of the measure's left digits are going to be displayed at (12, 10), because its point is 10 pixels diagonal to the global point of (2, 0). Since only its 5 digit is described, you'll only know when it's between 50% and 59% through the day. The digit is an image, and the file itself is assumed to be in the same directory as the page (or the class files, if it's a desktop clock). If the file isn't there, even the 5 digit won't display!
 
There is no digit group setting for the beat's right digit, so each of its digits will be relative to the global settings. The 8 digit will be the same as the 5 digit from the measure's left, but it is displayed at (2, -1)... the measure's left group setting is not considered here. The 9 digit will be a text '8', and will be displayed in the face and size of the global font, with italic style (plus the default's bold style), and it will be light blue.
 
 
It looks really convoluted, but it's really not all that bad. Check out my examples (linked above), experiment a little, and you should be able to implement some really cool ideas. And with the generic images and positioning, you can make it as abstract as you'd like.
 
Oh... and did I mention... it's all supposed to work, but I haven't done rigorous testing. If any of it needs tweaking, feel free to let me know.
   
 
 
 
    Contents          Previous    Next  On the Desktop     
 
       The standard time-piece uses configuration files to define its appearance. For this reason, the command-line application (WRLDtimeApp) takes one optional parameter:
configfile
name of the configuration file to prepare itself with (defaults to standard black-on-grey clock).
See configuration files below for full details on configuration and the default values for the time-piece.
   
 
 
 
    Contents          Previous    Next  UTC Sites     
 
       Here is a list of known UTC hosts. Each of them serves its signal from port 13.
   time-a.timefreq.bldrdoc.gov
   time-b.timefreq.bldrdoc.gov
   time-a.nist.gov
   time-b.nist.gov
   time.nist.gov
   time-nw.nist.gov
   utcnist.colorado.edu
For much more detailed information, please see http://www.bldrdoc.gov/timefreq/.
   
 
 
 
HTML & Java Implementation (c)1998, Lookit the Cat Productions
WRLD.time Conceived (and (c)1998) by jonathan jay

WRLD.time
a fine global temporal standard

Root Sleepbot Constructs