HW3php Config File Documentation
Contents:
HW2 used 3 main configuration files. System settings were stored in the hwconfig.txt and the remainder of the settings was stored in the user/theme files.
The main problem with this setup is the fact that the definition between user files & theme files was not very clear. Also installations with multiple users found it a pain to update all the user files whenever a small update needed to be made. Another disadvantage to this setup was the fact that all settings were loaded into memory whether needed or not. Thus wasting resources when not needed. The new HW3 use of INI files for configuration helps to make thing much simpler for comprehension, administration and resource usage.
SECURITY NOTE: In HW3php, the INI files by default include an ".php". Thus they are named names like: "hw3.ini.php". Each INI file also includes an "<?" as the first line and a "?>" as the last line of the INI file. This is for security purposes. Normally users will put the INI files in the main HTML area, and making the INI files psuedo php files will stop a web user from browsing the INI files.
HW3 INI files are stored in the configs directory and may be accessed by a variety of methods such as default loading of the system ini, loading of ini files based on user parameters, templates and more.
hw3.ini.php:
The hw3.ini.php is the main system configuration file and is loaded on each request to the HW3 script. In this file you will find settings controlling the HTTP mode, proxy settings, Template plug-in settings and more. Refer to table 1 for a break down of the default hw3.ini.php
INI files can be loaded using the "config" parameter. Adding "config=xxx" to the query string, where "xxx" is the name of the INI file minus the ‘.ini.php" extension, will make HW3 load the xxx.ini.php file from the configs directory. Thus to make HW3 load the additional INI file named "test.ini.php", you would use an URL similar to:
http://www.yourdomain.com/path/to/hw3.php?config=test
In this example, HW3 will first load the hw3.ini.php and then load the test.ini.php if it exists in the configs directory.
You can specify multiple INI files to be loaded by separating them with a comma. For example, to make HW3 load the test.ini.php, test2.ini.php and test3.ini.php you would use a URL similar to:
hw3.php?config=test,test2,test3
In this example, HW3 will first load the hw3.ini.php and then load test.ini.php, test2.ini.php and finally test3.ini.php.
NOTE: HW3 will load the INI files from left to right, so settings loaded from an INI file can override previous settings from loaded INI files.
NOTE: On operating systems that allow case sensitive file names such as UNIX and LINUX, you need to set the "config" parameter to the proper case of the file name. For example, on most UNIX servers the following URL are not the same:
hw3.php?config=test
hw3.php?config=TEST
The first URL will make HW3 attempt to load the "test.ini.php" and the second will make HW3 attempt to load the INI file "TEST.ini.php".
On operating systems that are non case sensitive, such as Microsoft Windows servers, the two URLs above would have attempted to load the same file. Thus to keep your INI files portable between operating systems, it is best to always make your INI file names be in lower case.
The "user" and "theme" parameters:
Users familiar with HW2, may be asking "What about the user=xxx and theme=xxx parameters?" HW3 will still allow you to use these parameters, though they will perform the same function as the "config" parameter. Thus the following three URLs will perform the exact same thing, they will load the test.ini.php:
hw3.php?config=test
hw3.php?user=test
hw3.php?theme=test
You may also combine the "config", "user" and "theme" parameters in a url, as in:
hw3.php?user=spanish&config=test
HW3 will load all of the requested INI files, but in the precedence of:
Thus, the above URL will first load test.ini.php and then the spanish.ini.php file. Also the above URL could be rewritten simply using the "config" parameter as in:
hw3.php?config=test,spanish
While you are free to use the "user" and "theme" parameters, they are now considered obsolete and the remainder of the docs will only reference the "config" parameter.
HW3 is plug-in based, thus every request to HAMweather will simply output a template or load a plug-in to perform data manipulation before outputting the template. Thus each plug-in can have an INI file to be loaded as needed.
After HW3 has loaded the hw3.ini.php and any additional INI files specified by the "config" parameter, HW3 will look at the "forecast" parameter (or the "do" parameter as "forecast" and "do" can be used interchangably). HW3 will add "fc_" to the beginning of the "forecast parameter" and if an INI file by that name exists it will be loaded. For example, with the URL:
hw3.php?forecast=zone&zipcode=24060
HW3 will look for an INI file by the name of "fc_zone.ini.php" and load it if it exists.
Another example:
hw3.php?forecast=pass&pass=test
Here HW3 will load the INI file, "fc_pass.ini.php" if it exists.
The feature of loading an INI file based on the "forecast" or "do" parameter allows you to have individual settings for each plug-in that are only loaded when needed, thus lowering system resources.
There may also be times when you do not want HW3 to load an INI file based on the "forecast" or "do" parameters. In such cases you can add the "nofc=1" parameter to the query string and HW3 will not load an INI based on the "forecast" or "do" parameter. For example:
hw3.php?forecast=zone&nofc=1&zipcode=24060
Normally HW3 would attempt to load the "fc_zone.ini.php", but the "nofc=1" in the above URL will prevent HW3 from doing this.
NOTE: If you are using the "do" parameter to specify the plug-in you would still use the "nofc=1" to stop the plug-in specific INI from being loaded. Thus in the example URL:
hw3.php?do=stockquotes&stock=yahoo&nofc=1
HW3 would not attempt to load the "fc_stockquotes.ini.php" because of the "nofc=1" parameter.
INI Files Loading Other INI Files
HW3 also gives the capability for one INI file to force the loading of another INI file. For instance, if while loading an INI file, HW3 comes upon a line beginning with "%%LOAD_CONFIG=XXXX%%, HW3 will pause the loading of the first INI file. Load the XXXX.ini.php file if it exists and then continue loading the first INI file where it left off.
This feature allows you to put settings common to several plug-ins into a single INI file and have them loaded automatically by the individual plug-ins INI files as needed.
NOTE: HW3 will not load an INI files if it has previously been loaded. This is prevent the potential for endless looping of one INI file loading a second which in turn loads the first which then loads the second INI file again which loads the first etc…
If you specify the "alt" parameter to make HW3 use an alternate template when outputting, HW3 will attempt to load the alttemplate.ini.php. Refer to Table 2 for more information on the default alttemplate.ini.php file.
Lastly, when HW3 is parsing through a template for outputting, the template can make HW3 load an INI file as well. If while outputting the template, if HW3 comes upon "%%CONFIG=xxx%%", then HW3 will attempt to load the xxx.ini.php file if it exists.
This is very useful to load a set of user defined variable presets. Thus at the beginning of your header you could load an INI file which held user defined variables which define the font faces, colors and other various settings.
The INI file used by HW3 are similar to the standard windows INI file.
parametername=value
An example from the hw3.ini.php may look as follows:
[SystemSettings]
cgi_ext=cgi
mime_type=text/html
debug_mode=1[Parse Plugins]
HWimage=HW::HWimage::Parser|parse_line|1|1|0Here the parameters, cgi_ext, mime_type and debug_mode are part of the "SystemSettings" section and the parameter "HWimage" is part of the "Parse Plugins" section.
debug_mode=1
debug_mode =1
debug_mode= 1
debug_mode = 1
debug_mode = 1
debug_mode=1
Debug_Mode=1
HW3 INI files also have three unique features to add additional control. If when parsing an INI file, if the first non space character is a percent sign ("%") HW 3 will compare the line to see if it matches one of the following INI file commands, and if so it will perform the designated action, otherwise it will ignore the line.
Parameter Values including other INI file Settings:
One last unique feature of HW3 INI files is the ability for a parameter value to include another previously loaded INI parameter value in itself. If in the parameters value, there exists %%INI:SectionName:ParameterName%% HW3 will insert the value for "ParameterName" in section "SectionName" into the current parameters value. For example:
[Paths]
html_side=/usr/www/users/hamnet/hamweather/hw3beta
blank_maps=%%INI:Paths:html_side%%/images/blankmaps
warning_maps=%%INI:Paths:html_side%%/images/warningmaps
In the above example the file path was set in the "html_side" parameter. To keep the user from having to also set this path in several other places in the INI file, the "blank_maps" and "warning_maps" parameters reference the previously loaded "html_side" parameter. Thus easing administration.
NOTE: There cannot be any spaces between the "%%INI:" and the SectionName, nor can there be spaces before or after the colon separating the SectionName and ParameterName. Finally there can not be any spaces between the ParameterName and the lagging "%%".