HW3php Parameter Documentation
Contents:
When calling the HW3 script, you can will need to pass data to tell HW3 what to do and for what location data is needed etc. The data that is passed to HW3 to control its functionality are called parameters.
How Are Parameters Passed to HW3?
HW3 allows you to pass it parameters via INI files, Query String in a URL, an HTML form, cookies or the command line/cron.
NOTE
: It should be noted that with all methods of passing parameters, HW3 is case sensitive with parameters. Thus the parameter "state=va" is not the same as "STATE=va". For this reason all default parameters in HW3 are always lowercase.For information on INI file usage refer to the INI File Documentation and for information on cookie usage refer to the Cookie Usage Documentation.
Passing Parameters via the Query String in a URL:
When sending parameters as part of the query string, you specify the script name followed by a question mark (?), then the parameter name, an equal sign and the parameter value. Multiple parameters can be used by separating them with an ampersand (&). For Example:
hw3.php?forecast=zone&zipcode=24060
NOTE: The parameter name and value should be URL encoded. Review the HTTP standards on such encoding for more info. One quick hint is to turn spaces into a plus sign (+). For example:
hw3.php?forecast=zone&place=Virginia+beach&state=va
Passing Parameters via an HTML Form:
When calling HW3 from a form you follow the standard HTML form convention. You can post to the HW3 script using either the GET or POST methods. The difference between the two is that when using the GET method, the browser will append the parameters to the query string when calling the HW3 script. This has a benefit of allowing the user to easily bookmark the data wanted. The POST method will send the parameters to HW3 behind the scenes. So if you look at the URL in the browser, you will only see the URL to the HW3 script and not the query string data.
As an example, below is the html coding for a web page that will allows a user to enter in a US zip code and when the submit button is pressed the zip code entered, the forecast parameter and the country parameter are sent to the hw3.php:
| Example 1 |
| <HTML> <HEAD> <TITLE>sample Form call to HW3</TITLE> </HEAD> <BODY> <FORM NAME="zipcode_entry" METHOD="POST" ACTION="hw3.php"> <INPUT TYPE="HIDDEN" NAME="forecast" VALUE="zandh"> <INPUT TYPE="HIDDEN" NAME="country" VALUE="us"> <INPUT TYPE="TEXT" NAME="zipcode" VALUE="" SIZE="5"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="submit"> </FORM> </BODY> </HTML> |
Passing Parameters via the command line/cron:
If you are running HW3 from the command line you can pass parameters to HW3 by following the script name with a space, the parameter name, an equal sign (=) and the parameter value. Multiple parameters can be specified, by separating this with spaces. For example:
hw3.php forecast=zone zipcode=24060
NOTE
: Since the parameters are separated with spaces you should either URL encode the parameter name/values or at the minimum turn any spaces in the parameter names and values to plus signs (+). For example:hw3.php forecast=zone place=Virginia+beach state=va
NOTE
: If needed for security reasons you can prevent HW3 from allowing parameters to be passed from the command line. To turn off the functionality, open the hw3.ini in the configs directory and the section "SystemSettings" find the setting for "allow_command_line" and set its value to 0. Thus the line would look like.allow_command_line=0
Alternatively, you could simply remove the allow_command_line line from the ini file or place a pound sign (#) to the left, thus turning the line into a comment.
What are the parameters that can be used with HW3?Since HW3 is plug-in based, the actual parameters that can be used are endless, as each plug-in can have its own defined parameters. There are two sets of parameters that are common to any HW3 usage.
User defined variables are defined by having an "hwv" as the first three letters of the parameter name. When set they will override any preset for that variable in the INI files and then can be used in the template output.
For example:
hw3.php?forecast=zone&zipcode=24060&hwvBGcolor=ffffff
HW3 will set the user defined variable "hwvBGcolor" to "ffffff". Then whenever "%%hwvBGcolor%%" is found in the templates, it will be replaced with the setting "ffffff". In this example hwvBGcolor could be used to allow the background color of the web page to be changed.
| Cookie Parameters: NOTE: See Cookie Usage docs for more information | |
| uc | Use Chip: Allow HW3 to use chips from HW3 cookie. I.E. hw3.php?uc=hwall |
| nc | No Chip: Make HW3 not use chips from HW3 cookie. I.E. hw3.php?nc=hwall |
| sc | Set Chip: Make HW3 set the chips in the HW3 cookie. I.E. hw3.php?sc=hwall |
| rc | Remove Chip: Make HW3 remove a chip from the HW3 cookie. I.E. hw3.php?rc=forecast |
| Configuration/INI Parameters: NOTE: See INI File Usage docs for more information | |
| config | Set to name of ini file minus file extension (.ini) to make HW3 load stated ini file. I.E. hw3.php?config=test |
| user | Set to name of ini file minus file extension
(.ini) to make HW3 load stated ini file. I.E. hw3.php?config=test NOTE: Obsolete. Use config instead. |
| theme | Set to name of ini file minus file extension
(.ini) to make HW3 load stated ini file. I.E. hw3.php?config=test NOTE: Obsolete. Use config instead. |
| nofc | Set to 1 to tell HW3 not to attempt to load an ini file based on the forecast or do parameter. I.E. hw3.php?forecast=zone&nofc=1 |
| Control Parameters: Used to control what plug-in is used and templates outputted. | |
| forecast | Controls what Plug-in HW3 loads and runs. I.E: hw3.php?forecast=zone&zipcode=24060 |
| do | Controls what Plug-in HW3 loads and runs.
Equivalent to the forecast parameter above and can be used interchangeably. I.E: hw3.php?do=zone&zipcode=24060 Note: If you specify both the forecast and do parameters at the same time, HW3 will only use the forecast parameter setting. |
| pass | Specifies what pass template to use. Only used
if the forecast/do parameter is set to "pass". The parameter should be set to
the nick of the pass template to use. I.E. hw3.php?forecast=pass&pass=test |
| dpp | Do Place Processing. Only used when the
forecast/do parameter is set to "pass". Normally when HW3 outputs a pass
template it will not waste time processing the info for a place/zip code to find the time
zone, latitude/longitude and other info. When you set dpp=1 then HW3 will perform the
place processing so the data can be used with in the pass template being outputted. I.E. hw3.php?forecast=pass&pass=test&dpp=1 |
| alt | Specifies which alt template to use. If set
HW3 will use the specified alternate template when performing output instead of the system
default for the particular plug-in Review the docs on Alternate templates for more
information. I.E hw3.php?forecast=zone&zipcode=24060&alt=test_zone |
| om | Output Mode. Defined whether HW3 outputs to
the web, file, both or no output at all. See the Output File Docs for more information. om=0 (or not specified) means output to web only om=1 output to web and file (requires "of" parameter to be set) om=2 output to file only (requires "of" parameter to be set) om=-1 do not output anything. |
| of | Output File. Used when the output mode
parameter ("om") is set to either 1 or 2. The output file parameter should be
set to nick output file to save to or the name of the file to save to depending on your
output file security level. Refer to the output file docs for more information. I.E. hw3.php?forecast=zone&zipcode=24060&om=2&of=24060 |
| debug | Sets the debug mode. If set to one (1) then debug mode is on, if set to zero (0) or not specified then debug mode is off. |
| Place Parameters: Settings used to request data or set data for the location that information is needed. | |
| zipcode | Should be set to a valid zip code/postal code
for the specified country. If no country parameters is specified then the must be for the
default country (usually the United States, "us"). I.E: hw3.php?forecast=zone&zipcode=24060 NOTE: You can obtain a zip code database for the US from HAMweather. To allow zip codes/postal codes for other countries you will need to provide the zip code database yourself, per the HW3 specifications. See the Zip Code/Postal Code documentation for more information. |
| pands | Original meaning in the beginning of HW3 was
Place and State. But since has taken up much more capability. The "pands"
parameter is the work horse when determining location the person requested. HW3 will test
the "pands" parameter for the following in succession:
NOTE : The "pands" parameter has priority over the "place", "state" and "country" parameters. Thus if they are provided with in the "pands" parameter and also specified individually the values in the "pands" parameter will be used.NOTE: The "zipcode" parameter has priority over the "pands" parameter. So if both parameters are given, the "zipcode" parameter will be used. |
| place | Place name. Should be used in combination with
the "state" and "country" parameters. If the "state" and/or
"country" parameters are not provided then the defaults from the INI file will
be used. I.E. hw3.php?forecast=zone&place=Roanoke&state=va |
| state | State/Province name or abbreviation. Should be
used in combination with the "place" and "country" parameters. If the
"place" and/or "country" parameters are not provided then the defaults
from the INI file will be used. I.E. hw3.php?forecast=zone&place=Roanoke&state=va |
| province | Equivalent to the "state" parameter
and can be used interchangeably. State/Province name or abbreviation. Should be used in combination with the "place" and "country" parameters. If the "place" and/or "country" parameters are not provided then the defaults from the INI file will be used. I.E. hw3.php?forecast=zone&place=toronto&province=Ontario&country=ca NOTE : The "state" parameter has priority over the "province" parameter, so if both are provided at the same time, only the "state" parameter will be used. |
| country | Country two letter abbreviation to use when
parsing the location that data is needed for. If not specified then the default country
setting in the INI file is used. The default is usually the United States
("us"), unless changed. I.E. hw3.php?forecast=zone&place=toronto&province=Ontario&country=ca |
| zone | Defines the US Weather Zone with in a state
that data is needed for. Should be used in conjunction with the "state"
parameter. Only used if the "country" is the US. I.E. hw3.php?forecast=zone&state=va&zone=14 |
| icao | Used to set the ICAO that data is needed for.
If not place/state/zipcode is provided but icao is then the place/state/country and other
location info will be derived from the ICAO. I.E. hw3.php?forecast=metar&icao=KBCB |
| fips | Defines the US state and county that the data
is needed for. Must be a valid 5 digit US FIPS number. The 1st 2 digits being
the state ID and the last 3 being the county ID with in the State. Valid usage for US
only. I.E. hw3.php?forecast=zone&fips=51121 (FIPS 51121 is for Montgomery County, VA) |
| lat | Latitude. If both the "lat" and "lon" are given they will override the default lat/lon for the requested place. |
| lon | Longitude. If both the "lat" and "lon" are given they will override the default lat/lon for the requested place. |
| radar_icao | ICAO of the radar station to display Nexrad for in the US. If given it will override the default radar_icao for the given place. |
| tzdif | Overrides any time zone settings found for a location. This should be set to the time zone difference from GMT. i.e. for EST you could set tzdif=-5 |
| tzname | Overrides any time zone settings found for a location. This should be set to the time zone name to use for the tzdif parameter. i.e. for EST you could set tzdif=-5&tzname=EST |
As stated earlier, plug-ins can have their own specific parameters as well. But if you do specify a parameter that is not used by HW3 it will not hurt anything. Actually parameters not used by HW3 are treated as pseudo Template variables. For example:
hw3.php?forecast=zone&zipcode=24060&Lee=The+Best
In the above example, the parameter "Lee" is not used by HW3, thus it will not bother the HW3 execution. Also if in the template being outputted the template variable "%%Lee%%" is found, it will be replaced with "The Best". Thus you can see Unused parameters act similar to User Defined Variables, but it is suggested that you use User Defined Variables in stead so that there is not a chance of conflicting with parameters of future plug-ins.