HAMweather 3 - RawData Plug-in

Contents:

Overview

The HW3 RawData plug-in is the plug-in that allows HW3 to fetch and display most any raw data from NOAA.

The RawData plug-in is designed to allow you to easily expand your HAMweather installation by adding new products. Two examples of using this plugin are included they are:

Module Name Description
statediscussion Uses the RawData plugin to fetch and display the State Dicussion text from IWIN.
stateforecast

Uses the RawData plugin to fetch and display the State Forecast text from IWIN.


Requirements:

The RawData plug-in requires that HW3 have been previously installed and is working correctly..

Installation:

    Installation of the RawData plug-in is fairly simple per the following steps:

Step Description
1 Confirm that HAMweather 3.03 or newer is installed and working correctly. 
 
2 Decompressing the Distribution:

The first step is to download the "zip" distribution of HW3image from the HAMweather Download Site and decompress the software package.  You can use  Winzip or something similar. Once unzipped you should have one main directory,  "cgi-bin"  and the files "readme.txt" and "license.txt".
 
3

Upload the Files:

The Installation requires the uploading of files to your server, specifically to the CGI side of the HW3 installation.  You will need to upload the following files to your current HW3 installation:

  1. Upload the "FetchRawData .pm" file to the hamlib/HW3Plugins directory.

    NOTE: Your FTP program may not auto recognize ".pm" files as text files and may try to upload in binary mode. You should force your FTP program to upload these files in ASCII mode as uploading in binary mode will cause errors on UNIX/LINUX servers.

    The following should be installed in the paths indicated after you upload the file:

         hamlib/HW3Plugins/FetchRawData.pm
     
  2. Upload the files with-in the distribution's "configs" directory to the "configs" directory of the HAMweather 3 installation. NOTE: You are not replacing your current "configs" directory but simply uploading the ini files to the "ini" directory on the server.

    NOTE: Your FTP program may not auto recognize ".ini" files as text files and may try to upload in binary mode. You should force your FTP program to upload these files in ASCII mode as uploading in binary mode will cause errors on UNIX/LINUX servers.

    The following should be installed in the paths indicated after you upload the in the distributions "configs" directory:

         configs/fc_statediscussion.ini     
         configs/fc_stateforecast.ini
     
  3. Upload the files with-in the distribution's "cgi-bin/templates" directory to the "templates" directory of the HAMweather 3 installation. NOTE: You are not replacing your current "templates" directory but simply uploading the template files to the "templates" directory on the server.

    The following should be installed in the paths indicated after you upload the in the distributions "templates" directory:

         templates/statediscussion.html
         templates/stateforecast.html  

 

Accessing the demos:

For instructions on accessing and using HW3 review the HW3 access instructions.  To access the two examples included with the plugin use the following:

Parameter 
Setting		 Description
forecast=statediscussion Used to display the state discussion text
forecast=stateforecast Used to display the state forecast text

To access the RawData Plugin and have it display the state discussion text for Virginia:

    hw3.php?forecast=statediscussion&state=va

Accessing Other Raw Data:

You will most likely want to use the RawData plugin to fetch other data besides just the state forecast text and the state discussion text. When you use the RawData plug-in you will need to create two files, an INI file thats holds the configuration information and a HTML template used for outputting the data. 

The first thing you will need to do is find the URL to the raw data that you want to display in HAMweather. Once you have this you can begin creating the INI file.

The INI file:

The INI file should be saved into the "configs" directory with a name similar to fc_xxxx,ini (fc_xxxx.ini.php  in HW3php), where "xxxx" is the same as the value you will pass in the "forecast" parameter. For example: to access the State Discussion text, we decided to use "forecast=statediscussion", thus the INI file must be saved as "fc_statediscussion.ini".

Once the naming of the new INI file is complete you will need to add the various required settings to it for use in grabbing your Raw Data. The following is the INI file from the fc_statediscussion.ini.Comments have been added above the various settings to provide additional information.


[URLs]
;raw_data_url should be set tot he domain of the server
containg the data you need
raw_data_url=iwin.nws.noaa.gov

;raw_data_prefix should be set to the path on the domain where
the needed data is located. Note that the plugin will allow
you to use simple "INI" variables. Parameters passed in the 
query string (or form post), the cache_path or data obtained from
looking up information on a location. In close the variable name with
"%%" as in "%%state%%". You can also prepend the variable name with 
"lc_" to turn the result to lowercase or "uc_" for uppercase.
raw_data_prefix=/iwin/%%lc_state%%/discussion.html

;raw_date_cache_file should be set to the path to cache the data
raw_data_cache_file=%%cache_path%%/us-%%lc_state%%-discussion.txt


[ForecastTypes]

# type = IWIN/URL, max age, template,parse code
; Set the beginning portion the "type" to the value you will pass in the 
"forecast" parameter. The right side of the equal sign is:
    IWIN/URL : no longer used
   Max Age : used to control the max age in to cache the data for
   template : the template to use when outputting the data
   Plugin Module : Set to "FetchRawData"
   Plugin routine name : set to "fetch_raw_data"
   ParseCode : Normally 0 for this plugin, set it to 1 if you want 
                       HW3 to obtain information on a location before 
                       fetching the data
statediscussion=notused,60,statediscussion.html,FetchRawData,fetch_raw_data,0


[Raw Data Cleanup]
; Here you can place perl regular expressions which should be parsed against
the obtained raw data before it is outputted. The name to the left of the equals
is a simple description of the regular expression which appears on the right side.
See perl documention for information on regular expression.
remove_html=s/<[^>]*>//g;
remove_nbsp=s/\&[Nn][Bb]sp;?//g;
remove_iwin_top=s/\s+IWIN.+?here\s+/\n/;
remove_iwin_bottom=s/\s+This\s+?data\s+?is\s+?from\s+the\s+?IWIN.+$//;
remove_03=s/\03/<hr width="90%">/g;
remove_extra_lf=s/\n\n+/\n\n/g;


Template Variables:

Once the RawData is obtained the following parameters may be used in the templates during output:

 
Template
Variable		 Description
%%raw_data_found%% Set to 1 if the data was obtained, set to 0 otherwise.
%%raw_data_text%% Contains the raw text after it was cleaned with any regular expressions in the [Raw Data Cleanup] section of the INI file.
%%raw_data_clean_error%% If during the "Raw Data Cleanup" any errors from the regular expressions will be in this variable. Useful for debugging purposes.