Programmer's Guide to Parameters
CMS parameters control how both dynamic (pl) and static (htm) pages of the website are constructed. This includes the appearance of the pages and what appears on the pages. For a more complete understanding of how to control page appearance you also need to consider the contents of the style sheets. You should use the Styles button to view and change the style sheets.
Parameters have default values defined in JshPARM.pm. As the CMS constructs the web pages from the available information, the values of the parameters are dynamically changed by the various modules. The Parms button allows you to override the parameter values on a system-wide basis. The CMS calls JshPARM.pm to create the internal array of parameters and immediately overrides these, as needed, to establish the basic system environment. Site by site customization is done using the Parms button. JshPARM.pm is the same for all CMS sites.
Adding new parameters and using them to control the website involves changing the program modules that build the pages of the web site. Since this involves program code changes, the procedures below are aimed at programmers.
Users override the default and system-wide parameters to change the appearance of a web site without using HTML. Therefore, user documentation must also be maintained any time new parameters are added to the system.
There are six groups of parameters. The first five groups are intended to be manipulated by administrators and advanced users. These parameters are documented on the following pages:
Administrator's Guide to Debug Parameters
Administrator's Guide to Page Parameters
Administrator's Guide to Query Parameters
Administrator's Guide to Ring Parameters
Administrator's Guide to Site Parameters
The remaining group of parameter is intended for use by the programmer. These are the internal parameters. See this link:
Programmer's Guide to Internal Parameters
It is important to understand the possible negative impact of making an error when changing JshPARM.pm. If a syntax error is introduced into this module, the entire web site will be unavailable to the users. Fortunately, the changes needed to add a new parameter are relatively simple. Follow the steps listed below for best results. Try to do these steps at more or less the same time. After you verify the site is not broken, the documentation must be updated to reflect the new features and how to specify them. Lastly, implement the code that tests or uses the new parameter.
The general procedure to add a parameter is the same for all types of parameter. It does not matter to which of the groups the parameter may belong. Here is the procedure.
-
Decide on the parameter name. Follow the established naming convention. A parameter that controls whether a table is to shown to the user has the prefix "show_" followed by the table name. A parameter that controls whether a field is to shown to the user has the prefix "show_" followed by the table name followed by "_" followed by the field name.
-
Verify it is not being used by searching for it in JshPARM.pm.
-
Decide the default and optional values for the parameter.
-
There are two places in JshPARM.pm where you will need to add code for the new parameter. First add the parameter and its default value to the parm_get_defaults sub-routine. Make a note of the relevant details for use later.
-
Second, add the parameter to the valid_parm_value sub. Be sure to apply appropriate validation logic.
-
Install the new version of JshPARM.pm and verify that the site is operating. Be prepared to restore the previous version, if anything goes wrong.
-
Add the parameter to the appropriate documentation page. Use the summary above to decide where to document the new parameter.
-
Write the code to implement the function. The necessary subroutines are body_context_array and body_get_value. Both subs are in JshBODY and therefore share the body_ prefix. See member.pl for typical code. The first relevant line is near line 24. Observe the use of context_array.
-
Test the implementation and fix as needed.
For more details on how to write the code to implement a parameter, see the following link:
Programmer's Guide to Parameter Use
This procedure is abbreviated and high level. It is documented to prompt the programmer as to the needed steps and is not intended to be a detailed step-by-step procedures.
|
