Creating the HWscroll Templates

Template Variables

As with the normal HAMweather operation, templates are used when outputting the forecast information.  These templates define what exactly should be displayed to the user.  You will specify what weather information to display using the same template variables used with HAMweather. Whenever you want certian weather information to appear in the output you put the corresponding template variable in the template. 

There are many variables that can be used in your HWscroll templates.   The following table lists them.  Some variables are only available for certain forecast types.  This is indicated as well.  As you will notice these are the same as used by normal HAMweather templates.

Variable Name Description
Standard Variables
%%scripturl%% The URL to the hamweather.cgi script
%%getstateurl%% The URL to the getstate.cgi script
%%metarlisterurl%% The URL to the metarlister.cgi script
%%emailstorerurl%% The URL to the hw2email_storer.cgi script
%%mapimagesurl%% The URL to the HAMweather Pro national maps
%%place%% Current Place needing forecast for
%%lcplace%% Current Place needing forecast for with proper casing
%%lplace%% Current place with proper html encoding (spaces turned to "+", etc)
%%state%% Current State needing forecast for. (abbreviation) Note: Even is user types in the full state name this variable will only be the two letter abbreviation.
%%lcstate%% Current State needing forecast for with proper casing and full name.
%%country%% Current Country needing forecast for
%%lcountry%% Current Country needing forecast for with proper casing.
%%icao%% The Current ICAO code of place needing observation for.
%%zone%% The weather zone number supplied by user. (Only available is supplied)
%%zforecast%% The text based portion of the forecast
%%forecastdate%% Date of the needed forecast
%%forecastneeded%% The actual forecast type requested.
%%lcforecastneeded%% The actual forecast type needed with proper casing
%%user%% The current user name
%%theme%% The current theme
Variables for use with the Zone Forecasts Only
%%iconrow%% The table row that holds all the weather icon coding for the zone forecast
%%daytitlerow%% The table row that holds the corresponding day titles for the weather icon row
%%weatherrow%% The table row that holds the corresponding weather conditions for the weather icon row
%%temprow%% The table row that holds the corresponding temperatures for the weather icon row.
Variables for use with the Hourly and Metar Observations Only
%%hicon%% URL to the icon for current weather condition
%%hname%% The name of the current place
%%hsky%% The  sky condition (weather condition)
%%htempf%% The temperature in Fahrenheit
%%htempc%% The temperature in Celcius
%%hdewptf%% The dew point in Fahrenheit
%%hdewptc%% The dew point in Celcius
%%hrh%% The relative humidity
%%hwind%% The wind speed and direction
%%hpressure%% The barometric pressure
%%hremarks%% Possible additional Hourly remarks
%%hforecastdate%% The Hourly forecast date and time
Variables for use with HAMweather Pro  Only
%%nationalsummary%% Table containing the current condition summary for requested cities. Includes City Name, Weather condition and temp on each row.  Used with the national summary.
%%nationalforecast%% Table containing the weather forecast for requested cities. Includes City Name, Weather condition and temp on each row.  Used with the national forecast.
%%warningtable%% Table of the states that have an active warning.  Each state is a hyperlink to the individual state warnings page.  Used with the National warning (uswarnings) report.
%%usradar%% The URL to the national Radar image
%%radarzoneimg%% The URL to the regional radar image
Used Defined Variables
%%hwvxxxx%% HAMweather allows user defined variables to be passed and inserted into the output.   Refer to the User Defined Variables page for more info.
HAMweather Include
%%hwi=xxxx%% HAMweather allows you to include files in the output. This can be used to have a custom header or footer for all the templates.  Thus allowing you so simply edit a couple files for the entire weather site.

Directives

Along with the weather template variables you can also include other information inthe HWscroll template to be used to display additional data and/or control the HWscroll applet. When the applet retrieves the template output from either the hamweather.cgi or the hwscroll.cgi,  it reads the data one line at a time.  Each line the applet reads is treated one of two ways, depending on the first two characters of the line:

  1. If the first two characters are "^^", the line is treated as a directive, discussed later. For clarification, that string is a pair of carets, the characters resulting from a SHIFT-ed 6 on IBM keyboards.
  2. Otherwise, the line is treated as a line of plain text, and is displayed to the screen. Automatic line wrapping is supported, so you don't need to worry about making sure your text doesn't run off the side of the applet, it will do that itself. Newlines will be ignored, unless two or more occur in a row. This means you can't specify when to start a new line, but you can specify when to start a new paragraph. The easy way to remember it is a single newline by itself is converted to a space. Two or more newlines in sequence are treated as newlines.

Directives

First of all, what is a "directive?" The HWscroll applet operates by requesting weather information from HAMweather from over the network and displaying HAMweathers output. Part of the applet's strength comes from the fact that it can be modified during runtime with extreme flexibility. By embedding directives in the HAMweather templates file the applet is to display, the web developer can alter the way their text will appear in the applet. Directives are the commands embedded in the HAMweather templates file. Since they directly correspond with the methods the applet publishes with the same names, they can almost be though of as method calls.

How does the applet determine what is text is should display, and what is text it should try to interpret as a directive call? Directive calls in the text file are indicated by lines beginning with two caret symbols (^^), that is, the character resulting from a "Shift"-ed 6 on IBM keyboards, inserted twice.

If you wanted to just display "Zone Forecast for Roanoke, Virginia" in HWscroll, you would create a template file containing the following:

Zone Forecast for Ronaoke, Virginia

When HWscroll displayed this data, it would use all the default settings, and scroll it at a comfortable speed in black text on a white background. However, what if you wanted to change it so the text were blue? There are two ways to do this:

  1. By including the following <PARAM> tag in the HTML document containg HWscroll:
    <APPLET CODEBASE="http://www.hamweather.com/hwscroll" 
            CODE="HWTextScroll.class" WIDTH=100 HEIGHT=200>
       <PARAM NAME="foreground" VALUE="0,0,255">
    </APPLET>
          

    This will set the initial foreground color of all your text to a bright blue.

  2. Alternatively, you could specify the text color by modifying your template file. When we last looked at it above, all it contained was:
          Zone Forecast for Ronaoke, Virginia
          

    To tell HWscroll we want the text to be blue, we could use the setForegroundColor directive. Now, the contents of our text file would be:

          ^^setForegroundColor (0,0,255)
          Zone Forecast for Ronaoke, Virginia
          

    Using setForegroundColor allows you tighter control over the colors, since you can call it multiple times in the same file, and change the colors throughout the document.

Let's look at a more detailed example (its the actual zonejava.txt  template included in the HWscroll software package). The following illustrates several of the directives and Template variables. Assume we have a text file containing the following text:

^^setURL (http://www.hamweather.com/cgi-bin/hamweather.cgi?forecast=zandh&state=%%state%%&place=%%place%%)
^^setSpeed (40)
^^setFontSize (16)
^^setCenter (true)
^^setBold (true)
Zone Forecast for 
%%lcplace%%, %%lcstate%%
^^setBold (false)
^^setFontSize (12)
Dated:%%forecastdate%%
^^setCenter (false)
%%zforecast%%

Here's how the applet will behave when it reads this file. Lets examine this line-by-line.

  1. setURL (http://...)

    This sets it so when the user clicks on the applet, it loads the given URL into the page, just as if the user clicked on a link.

  2. setSpeed(40)

    This sets the scroll speed to 40, out of a possible 100, with 100 being the fastest and 1 being the slowest.

  3. setFontSize(16)

    This sets the font size applet will use to display text to 16 point. 

  4. setCenter(true)

    This sets the alignment to centering. All text following this method call will be centered, until a call to setCenter(false) is made.

  5. setBold(true)

    This sets the font to Bold style. All text following this method call will be bold, until a call to setBold(false) is made.

  6. Forecast For

    This is the first line of actual text to be displayed.

  7. %%lcplace%%, %%lcstate%%

    These template varibles will be turned into the appropriate place and state names by HAMweather during output to the HWscroll applet and will be the second line of actual text to be displayed

  8. setBold(false)

    This turns off the bold font style. All text following this method call will be not be bold, until a call to setBold(true) is made.

  9. setFontSize(12)

    This sets the font size applet will use to display text to 12 point. 

  10. Forecast Date: %%forecastdate%%

    The template varible %%forecastdate%% will be turned into the appropriate date by HAMweather during output to the HWscroll applet and will be the third line of actual text to be displayed

  11. setCenter(false)

    This stops the alignment to centering. All text following this method call will be left justified, until a call to setCenter(true) is made

  12. %%zforecast%%

    The template varible %%zforecast%% will be turned into the appropriate forecast text by HAMweather during output to the HWscroll applet and will be the remaining lines of actual text to be displayed.

     

Complete list of Directives

The following is a complete list of supported directives for HWScroll.

setSpeed (int) Sets the scroll speed to the given integer. The scroll speed must be between HWTextScroll.MIN_SPEED (1) and HWTextScroll.MAX_SPEED (100). If it is not, then the speed is left unchanged.
pause (int) This causes the applet to pause scrolling for the given number of milliseconds.
pause () This causes the applet to pause scrolling until the user clicks the text area. Note that this might cause a conflict if you have a URL set with setURL (). If you do have a URL set with setURL () and include the pause () directive, then if the user clicks on the applet, the URL will be loaded, and scrolling will never resume. Be extra careful when mixing this directive and setURL ().
setForegroundColor (int,int,int) Sets the foreground color to the given RGB value. If the given parameters do not form a legal RGB value, the current foreground color is left unchanged. This is the same as setRightForegroundColor.
setLeftForegroundColor (int,int,int) Sets the foreground color for the left pane to the given RGB value. If the given parameters do not form a legal RGB value, the current foreground color for the left pane is left unchanged. Panes are discussed below, in the section titled Panes.
setRightForegroundColor (int,int,int) Sets the foreground color for the right pane to the given RGB value. If the given parameters do not form a legal RGB value, the current foreground color for the right is left unchanged. Panes are discussed below, in the section titled Panes.
setBackgroundColor (int,int,int) Sets the background color to the given RGB value. If the given parameters do not form a legal RGB value, the current background color is left unchanged. This is the same as setRightBackgroundColor.
setLeftBackgroundColor (int,int,int) Sets the background color for the left pane to the given RGB value. If the given parameters do not form a legal RGB value, the current background color is left unchanged. Panes are discussed below, in the section titled Panes.
setRightBackgroundColor (int,int,int) Sets the background color for the right pane to the given RGB value. If the given parameters do not form a legal RGB value, the current background color is left unchanged. Panes are discussed below, in the section titled Panes.
setFontFace (String) Sets the font face to use to the given String. This should be one of:
  • Serif
  • SansSerif
  • Monospaced

This is the same as setRightFontFace.

setLeftFontFace (String) Sets the font face to use in the left pane to the given String. This should be one of:
  • Serif
  • SansSerif
  • Monospaced

Panes are discussed below, in the section titled Panes.

setRightFontFace (String) Sets the font face to use in the right pane to the given String. This should be one of:
  • Serif
  • SansSerif
  • Monospaced

Panes are discussed below, in the section titled Panes.

setFontSize (int) Sets the size of the font to use to the given integer. This is the same as setRightFontSize.
setLeftFontSize (int) Sets the size of the font to use in the left pane to the given integer. Panes are discussed below, in the section titled Panes.
setRightFontSize (int) Sets the size of the font to use in the right pane to the given integer. Panes are discussed below, in the section titled Panes.
setCenter (boolean) Sets the centering flag. If the given boolean is true, then all subsequent text is centered, until the directive is invoked with a false value. This is the same as setRightCenter.
setLeftCenter (boolean) Sets the centering flag for the left pane. If the given boolean is true, then all subsequent text in the left pane is centered, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setRightCenter (boolean) Sets the centering flag for the right pane. If the given boolean is true, then all subsequent text in the right pane is centered, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setBold (boolean) Sets the bold flag. If the given boolean is true, then all subsequent text is printed in bold style, until the directive is invoked with a false value. This is the same as setRightBold.
setLeftBold (boolean) Sets the bold flag for the left pane. If the given boolean is true, then all subsequent text in the left pane is printed in bold style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setRightBold (boolean) Sets the bold flag for the right pane. If the given boolean is true, then all subsequent text in the right pane is printed in bold style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setItalic (boolean) Sets the italic flag. If the given boolean is true, then all subsequent text is printed in italic style, until the directive is invoked with a false value. This is the same as setRightItalic.
setLeftItalic (boolean) Sets the italic flag for the left pane. If the given boolean is true, then all subsequent text in the left pane is printed in italic style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setRightItalic (boolean) Sets the italic flag for the rightpane. If the given boolean is true, then all subsequent text in the right pane is printed in italic style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setInset (int) Sets the value of the inset, or how many pixels in to print text.
setURL (String) Sets the URL of the page to be loaded when the applet is clicked on. The String can also be "null" to set the applet so that when the user clicks on it, it simply toggles the scrolling on and off. text. Note that the URL must be a full URL, including the "http://" at the beginning.
setURL (String, String) Sets the URL of the page to be loaded when the applet is clicked on, BUT it will be loaded in the named frame, not the same frame as the applet. The two arguments are:
  1. The name of the frame to load a URL in when the applet is clicked on. If this is "null" or "_top" then it will load the target URL in the whole browser window, destroying all frames. If a frame name is a name not associated with a frame on the page, a new browser window is opened and the target URL is loaded when the user clicks on the applet.
  2. The String URL. This is the same as in setURL (String), documented above. If it is "null", then when the user clicks on the applet, it will simply toggle scrolling off and on. Note that the URL must be a full URL, including the "http://" at the beginning.

This directive is best illustrated with some examples.

  1. Say you had a page made up of two frames, "left" and "right." You are running TextScroll in the left frame, and you want it so when people click on the applet, it loads the pages in the right frame. You would use directive calls in your text file similar to these:
                    ^^setURL (right, http://www.news.com)
                    ^^setURL (right, http://www.cnn.com)
                  

    This way, when the user clicks on your applet in the left frame, the URL is displayed in the right frame, while the left frame stays, still displaying the applet.

  2. Perhaps you want to open a new window to display your source code, and you want the browser displaying the page containing your applet to stay open. You could use:
          ^^setURL (new, http://my.host.com/~username/path/file1.java)
          ^^setURL (new, http://my.host.com/~username/path/file2.java)
                  

    If these are used in HWScroll while HWScroll is on a page that doesn't use frames, or simply doesn't have a frame named "new" then it will open a new browser to display your code.

  3. Finally, maybe you have a page containing frames, and HWScroll is in the left frame. You want it so when a user clicks the applet, it will display the target URL in the whole window, destroying the frames. You would use directives similar to the following:
          ^^setURL (null, http://www.news.com)
          ^^setURL (_top, http://www.news.com)
          ^^setURL (http://www.news.com)
                  

    All three of those directive calls have the same effect. They will all load the web site www.news.com in the browser, destroying all your frames.

setLeftText (String) Sets the text to display in the left pane to the given String.