Difference between revisions of "Mod Settings Blocks"

From TNG_Wiki
Jump to: navigation, search
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
This article is about a scheme that organizes '''mod settings''' (i.e. "mod options") in the forms at Admin>>Settings>>General Settings. This scheme organizes mod settings into bordered '''blocks''' that are labeled with the mod name.
+
<div class='toccolours'>
 +
This article describes an technique that organizes a mod's configuration settings (i.e. mod options) into a bordered block (called a Mod Settings Block) in an Admin>>Setup program, and labels that block with the mod name.  This technique and the code behind it ''could'' be used by any mod author, but it really is used only by my (Robin Richmond's) mods. Thus I will break with convention and use first person pronouns in this article.
 +
The code that implements Mod Settings Blocks is incorporated into all of my mods that ''have'' mod options through a Mod Manager file-sharing technique that this article will describe.
 +
- Robin Richmond 7 May 2020</div>
 +
{| style="margin-right:0.5 em;" align="right" ; "font-size:120%";
 +
| __TOC__
 +
|}Here are three Mod Settings Blocks in Admin>>Setup>>General&nbsp;Settings, where there are actually quite a few more as you scroll down the page<div>[[Image:mod_settings_blocks-3blocks.jpg]]</div>Note that I have so many mods with options, and thus so many Mod Settings Blocks (at least 19 in admin_config.php, that I have defined a new subform named "Robin's Mods". The specific set of Mod Settings Block that you seen in your configuration page will, of course, depend on the mods that you have installed.
  
== Shared Mod Libraries ==
+
I place mods of my mod's Mod Settings Blocks at '''Admin>>Setup>>Chart&nbsp;Settings>>Robin's&nbspMods''', but, for example, the settings for my [[TextPlus Charts]] mod are in '''Admin>>Setup>>Chart&nbsp;Settings''', and the settings for my [[Gedcom Import Purge]] mod are in '''Admin>>Setup>>Import&nbsp;Settings'''
Mod Settings Blocks are a way of handling mod options, and are implemented in several of my mods with the help of the Mod Settings Block "Shared Mod Libraries" (aka "Shared Mod Includes").  I (Robin Richmond) don't expect them to be used by other mod programmers (though they ''could be'').  Still, they are fundamental to enough of my mods that they need some Wiki documentation. And since they a really are tied to me, I'll take the liberty of using first person pronouns and my name in this documentation. (FWIW, I'm not really very happy with this documentation, but I don't think that there will be enough interest in Mod Settings Blocks to justify the time it would take to clean it up.  So take what you can from it, and contact me through [https:/www.robinrichmond.com/family/suggest.php my TNG contact form] if you need more information.
 
  
=== The Shared Subfolder ===
+
== Advantages ==
The files that support Mod Settings Blocks are in a mods subfolder that is packaged and distributed with all of the mods that need it.  The folder is named <span style='white-space:nowrap'>'''RR-shared_mod_includes_v#.##.#'''</span>, where the number symbols, of course, represent a standard Mod Manager version number.
+
The distinct advantages that Mod Settings Blocks have over options defined by native Mod Manager %parameter% directives are that the options in Mod Settings Blocks
 +
#Can be defined through checkboxes, radio buttons, and selection boxes,
 +
#Can do validation,
 +
#Can use Javascript as necessary to do things like disable an option that is not relevant when another option has a certain value,
 +
#Can be composed of values form more than one form field,
 +
#Can be combined with related options into tables and lists, and, notably
 +
#Can be applied readily to more than one program, and even be used by programs modified by ''other'' mods.
  
A Mod Manager feature (new in TNGv12) called "protected files" allows files to be shared among multiple mods. Each mod that uses the shared files has %copyfile directives that ''can'' install the files, but, because of a "protected file flag" within the %copyfile directive,
+
Mod Settings Blocks are distinct from other options in the Admin>>Setup programs in that
# The mods do not care whether the files has already been installed, and
+
#The options for a mod are wrapped in a bordered block with a heading that states the mod's name and provides a link to the mod's Wiki article, as shown in the screen clip above
# The files are not uninstalled when a mod is uninstalled (since other mods that need them may still be installed.)
+
#I can link directly to a Mod Settings Block so that the TNG admin who wants to edit a mod's options doesn't have to open a specific subform within the Admin>>Setup program, nor scroll through other settings and other Mod Settings Block, like this:<div>[[Image:mod_settings_blocks-adminplacessearch.jpg]]</div>Note that the triangular arrow next to the heading "Robin's Mods" points to the right, indicating that the subform is ''not'' open. If you were to click on that heading, the subform would open, revealing all of the Mod Settings Blocks, as in the first screenshot above.
The protected file flag is a tilde that is placed into a %copyfile directive like this:
 
<code>%copyfile:~RR-shared_mod_includes_v12.0.0.4/rrshared_modsettingsblocks4.php%</code>
 
  
The shared subfolder is packaged into the distribution zip file for every mod that puts its mod options in a Mod Settings Block. When the distribution file is unzipped, the shared subfolder should be copied to the site's mods folder, and may (without causing any problems) overwrite an existing copy of the shared subfolder and of existing files.
+
== Links to Mod Settings Blocks ==
  
== Mod Setttings ==
+
There are two places in TNG application where links take you directly to a single Mod Options block. The first is in Mod Manager, where I have use the native mod parameters form for that link.  The native [Option] link in the status cell opens the status cell to reveal action button, include an "Edit Options" button.  Then, when you click on "Edit Options", you get a standard "Mod Manager - Edit ParameterA" page. With my mods, the Edit Parameter page looks very much like this:<div>[[Image:mod_settings_blocks-modmanageroptions.jpg]]</div> You ''should not'' enter a value for the options, but no real harm will occur if you do.
As of '''August, 2019''', I have virtually stopped using '''mod parameters''', which are configurable settings that affect mod behavior, and that are updated through the "Edit Options" button on a mod's row in the Mod Manager list. Instead, my mod options are ''custom TNG settings'' (which I also refer to as "mod settings"), that is, system variables that are saved in TNG's configuration files, and edited by the HTML forms at Admin>>Setup.  
 
  
Significantly, I implemented Mod Settings Blocks in enough mods that I have defined '''a new subform named "Robin's Mods"''' in the General Settings configuration program, admin_genconfig.php. I put my settings into that subform, unless there is a compelling reason to put them elsewhere. (For example, the settings for my [[TextPlus Charts]] mod are in '''Admin>>Setup>>Chart&nbsp;Settings''', and the settings for my [[Gedcom Import Purge]] mod are in '''Admin>>Setup>>Import&nbsp;Settings'''.
+
The second place where you can link directly to a Mod Options Block is from what I call an Inner Mod Menu. Mods that ''significantly affect'' a TNG page can define an Inner Mod Menu, which pulls down from the "Mod Information" label at the right end of TNG's standard "inner menu", as in the Admin>>Places page:<div>[[Image:show_inner_mod_menus.jpg]]</div>which has been affected by three mods, only one of which has mod options. The "Change Mod Options" link for [[Admin Places Search]] goes directly to the Mod Options Block for [[Admin Places Search]]:<br>[[Image:mod_settings_blocks-adminplacessearch.jpg]]
  
The mods that define settings (i.e. define form fields for settings) in the Admin>>Setup forms also install an Include file that organizes each mod's options into labeled blocks that are sorted by filename.
+
== Protected Files ==
<div>[[Image:robins_folder_open.jpg]]</div>
+
Mod Settings Blocks are implemented by an Include file that is incorporated into each mod that defines a Mods Setting Block. The mods use a Mod Manager feature called "Protected Files" to share the Include files so that
 +
* There is just one copy of the Mods Setting Block Include file in the main TNG folder, no matter how many mods use it, and
 +
* The Includes can be installed by ''any'' mod that uses it.
  
The Include file is named '''rrshared_modsettingsblocks?.php''' (where '?' is a version number). It is installed from the folder '''RR-shared_mod_includess_vx.y.z.?''', which is described [[#The_Shared_Subfolder the Shared subfolder section above]].  
+
The Include file that support Mod Settings Blocks is in a mods subfolder that is packaged and distributed with all of the mods that need it. The folder is named <span style='white-space:nowrap'>'''RR-shared_mod_includes_v#.#.#.#'''</span>, where the number symbols, of course, represent a standard Mod Manager version number. The include file itself is named '''rrshared_modsettingsblocks#.php''' where the number symbol matches the incremental mod version number, which is the last component of the folder's version "number". Thus, <span style='white-space:nowrap'>'''RR-shared_mod_includes_v12.0.0.4'''</span> would contain the file '''rrshared_modsettingsblocks4.php'''.
  
== What each mod must do ==
+
Protected files are identified by flagging a Mod Manger %copyfile command with a tilde, like this:
Mods that use this scheme for their mod options
+
<code style='white-space:nowrap'>%copyfile:~RR-shared_mod_includes_v12.0.0.4/rrshared_modsettingsblocks4.php%</code>
# Install (or at least ''try to install'') the Include file <code>rrshared_modsettingsblocks#.php<code> from the mod subfolder <code style='white-space:nowrap'>RR-shared_mod_includes_v12.0.0.#</code>,
+
 +
When a protect file %copyfile command is places in each mod that wants to shared the file,
 +
# The first mod that needs the shared file that is installed on a site actually installs the file,
 +
# Mods installed later see the installed file and effectively ignore the %copyfile command.
 +
# When a mod that uses the protected file is uninstalled, the protected file ''is not unistalled'', since other mods that need it may still be installed.
 +
 
 +
The downside of this technique are that
 +
# When all mods that use a protected file have been uninstalled, the file still remains in its TNG folder, and
 +
# The file cannot be updated unless it is removed by a mod that does not use the protected flag.
 +
#* To accommodate this condition, the shared folder name and filename must be changed (by incrementing the version number), and mods that need the new version must be modified to install the new shared file.
 +
 
 +
== Technical details you don't need ==
 +
 
 +
=== What each mod must do ===
 +
Mods that use this technique for their mod options
 +
# Install (or at least ''try to install'') the Include file <code>rrshared_modsettingsblocks#.php</code> from the mod subfolder <code style='white-space:nowrap'>RR-shared_mod_includes_v12.0.0.#</code>,
 
# Install (or at least ''try to install''), from the same shared subfolder, a small image file that is a Wiki icon (a stylized W), and that serves as a hyperlink to the mod's Wiki article,
 
# Install (or at least ''try to install''), from the same shared subfolder, a small image file that is a Wiki icon (a stylized W), and that serves as a hyperlink to the mod's Wiki article,
 
# Define an HTML layout table in a TNG configuration program (that is, one of the Admin>>Setup programs). That layout table must contains all of the form fields that edit the configuration settings,
 
# Define an HTML layout table in a TNG configuration program (that is, one of the Admin>>Setup programs). That layout table must contains all of the form fields that edit the configuration settings,
Line 43: Line 68:
 
#* None of the other Admin>>Setup pages have subforms, so they ignore this attribute.
 
#* None of the other Admin>>Setup pages have subforms, so they ignore this attribute.
  
== The configuration array $rrconfig ==
+
=== The configuration array $rrconfig ===
 
All of the configuration variables created by my mods are stored in the appropriate configuration file in the array $rrconfig. Most of them have single string value (possibly with multiple delimited values), in $rrconfig["''settingname''"]. A few of my configuration variables are multivalued, with two subscripts.  
 
All of the configuration variables created by my mods are stored in the appropriate configuration file in the array $rrconfig. Most of them have single string value (possibly with multiple delimited values), in $rrconfig["''settingname''"]. A few of my configuration variables are multivalued, with two subscripts.  
  
=== Additional Technical Details ===
+
=== What the Include file does ===
Most mod settings are implemented in the configuration forms in a single field (where a radio button set must be considered as one field). The name of these fields (the name attribute in the HTML tags) is "rrconfig[''settingname'']" (with no quote mark inside the brackets). Conveniently, these field names are received by the action script as $rrconfig["''settingname''"].
+
The Include file rrshared_modsettingsblocks#.php contains
 
 
To simplify the code in the action scripts, mods with single-field settings do the following:
 
# In the form: Define a hidden form field named rrconfig[''modname''] whose value is a list of the names of that mod's settings.
 
# In the action script: Install a two-line loop that
 
#* Scans the list of setting names provided by $rrconfig["''modname''"], and
 
#* For each setting, writes an assignment statement in config file.
 
#** In the assignment statement, the variable $rrconfig["''settingname''"] is given the value of $rrconfig["''settingname''"] within the action script.
 
With these scheme, the action script doesn't even know which variables it is saving; it just need to look at the $rrconfig element with the appropriate mod name.
 
 
 
== What the Include file does ==
 
The Include file rrshared_modsettingsblocks?.php contains
 
 
# A PHP function that help mods define little 'D' buttons that restore fields to the mod's installation default.  
 
# A PHP function that help mods define little 'D' buttons that restore fields to the mod's installation default.  
 
# An embedded style sheet  
 
# An embedded style sheet  
Line 72: Line 86:
 
<div>[[Image:inner_mod_menu-robins_mods.png|650px]]</div>
 
<div>[[Image:inner_mod_menu-robins_mods.png|650px]]</div>
  
The shared Include file also contains Javascript code that implements two new querystring variables:
+
The shared Include file also contains Javascript code that implements two new querystring variables for the Admin>>Setup programs:
 
# '''open''' specifies a subform to be opened automatically, and
 
# '''open''' specifies a subform to be opened automatically, and
 
# '''mod''' specifies a mod (within the "Robin's Mods" subform) to be opened automatically.
 
# '''mod''' specifies a mod (within the "Robin's Mods" subform) to be opened automatically.
Line 80: Line 94:
 
and, when you follow that link, you will see only the options for the Admin Cemetery Edit mod:
 
and, when you follow that link, you will see only the options for the Admin Cemetery Edit mod:
 
<div>[[Image:inner_mod_menu-one_mod_options.png|650px]]</div>
 
<div>[[Image:inner_mod_menu-one_mod_options.png|650px]]</div>
[[Inner Mod Menus]] contain links like this.
 
 
== Mods that define Mod Settings Blocks==
 
Essentially all of my mods that are updated or created starting in August 2019 and that have mods settings will define those settings in Mod Setting Blocks, which, in most cases, will be in .
 
 
When I'm done, this should include (at least)
 
* In '''Admin>>Setup>>General&nbsp;Settings>>Robin's&nbsp;Mods''': [[Admin Branches]], [[Admin Cemeteries Search]], [[Admin Cemetery Edit]], [[Admin Languages]], [[Admin Media Search]], [[Admin Places Geocode]], [[Admin Places Search]], [[Admin Reports Search]], [[Field Buttons]], [[Headstones Report]], [[Placesearch-More Info]], [[Regroup Person Profile]], [[Regroup Person-Date Pace]], [[Regroup Person-Parent Rel]], and [[Show Mod Names]].
 
* In '''Admin>>Setup>>Import&amp;Settings''':  [[Gedcom Import Mediatype]], [[Gedcom Import Monitor]], and [[Gedcom Import Purge]].
 
* In '''Admin>>Setup>>Chart&amps;Settings''': [[TextPlus Charts]] and [[Count Descendants]].
 
  
 
== See Also ==
 
== See Also ==
 
* [[Inner Mod Menus]]
 
* [[Inner Mod Menus]]
 
* [[User:Robinrichm#My_Mods|Robin's Mods]]
 
* [[User:Robinrichm#My_Mods|Robin's Mods]]

Latest revision as of 16:27, 7 May 2020

This article describes an technique that organizes a mod's configuration settings (i.e. mod options) into a bordered block (called a Mod Settings Block) in an Admin>>Setup program, and labels that block with the mod name. This technique and the code behind it could be used by any mod author, but it really is used only by my (Robin Richmond's) mods. Thus I will break with convention and use first person pronouns in this article. The code that implements Mod Settings Blocks is incorporated into all of my mods that have mod options through a Mod Manager file-sharing technique that this article will describe.

- Robin Richmond 7 May 2020
Here are three Mod Settings Blocks in Admin>>Setup>>General Settings, where there are actually quite a few more as you scroll down the page
Mod settings blocks-3blocks.jpg
Note that I have so many mods with options, and thus so many Mod Settings Blocks (at least 19 in admin_config.php, that I have defined a new subform named "Robin's Mods". The specific set of Mod Settings Block that you seen in your configuration page will, of course, depend on the mods that you have installed.

I place mods of my mod's Mod Settings Blocks at Admin>>Setup>>Chart Settings>>Robin's&nbspMods, but, for example, the settings for my TextPlus Charts mod are in Admin>>Setup>>Chart Settings, and the settings for my Gedcom Import Purge mod are in Admin>>Setup>>Import Settings

Advantages

The distinct advantages that Mod Settings Blocks have over options defined by native Mod Manager %parameter% directives are that the options in Mod Settings Blocks

  1. Can be defined through checkboxes, radio buttons, and selection boxes,
  2. Can do validation,
  3. Can use Javascript as necessary to do things like disable an option that is not relevant when another option has a certain value,
  4. Can be composed of values form more than one form field,
  5. Can be combined with related options into tables and lists, and, notably
  6. Can be applied readily to more than one program, and even be used by programs modified by other mods.

Mod Settings Blocks are distinct from other options in the Admin>>Setup programs in that

  1. The options for a mod are wrapped in a bordered block with a heading that states the mod's name and provides a link to the mod's Wiki article, as shown in the screen clip above
  2. I can link directly to a Mod Settings Block so that the TNG admin who wants to edit a mod's options doesn't have to open a specific subform within the Admin>>Setup program, nor scroll through other settings and other Mod Settings Block, like this:
    Mod settings blocks-adminplacessearch.jpg
    Note that the triangular arrow next to the heading "Robin's Mods" points to the right, indicating that the subform is not open. If you were to click on that heading, the subform would open, revealing all of the Mod Settings Blocks, as in the first screenshot above.

Links to Mod Settings Blocks

There are two places in TNG application where links take you directly to a single Mod Options block. The first is in Mod Manager, where I have use the native mod parameters form for that link. The native [Option] link in the status cell opens the status cell to reveal action button, include an "Edit Options" button. Then, when you click on "Edit Options", you get a standard "Mod Manager - Edit ParameterA" page. With my mods, the Edit Parameter page looks very much like this:
Mod settings blocks-modmanageroptions.jpg
You should not enter a value for the options, but no real harm will occur if you do. The second place where you can link directly to a Mod Options Block is from what I call an Inner Mod Menu. Mods that significantly affect a TNG page can define an Inner Mod Menu, which pulls down from the "Mod Information" label at the right end of TNG's standard "inner menu", as in the Admin>>Places page:
Show inner mod menus.jpg
which has been affected by three mods, only one of which has mod options. The "Change Mod Options" link for Admin Places Search goes directly to the Mod Options Block for Admin Places Search:
Mod settings blocks-adminplacessearch.jpg

Protected Files

Mod Settings Blocks are implemented by an Include file that is incorporated into each mod that defines a Mods Setting Block. The mods use a Mod Manager feature called "Protected Files" to share the Include files so that

  • There is just one copy of the Mods Setting Block Include file in the main TNG folder, no matter how many mods use it, and
  • The Includes can be installed by any mod that uses it.

The Include file that support Mod Settings Blocks is in a mods subfolder that is packaged and distributed with all of the mods that need it. The folder is named RR-shared_mod_includes_v#.#.#.#, where the number symbols, of course, represent a standard Mod Manager version number. The include file itself is named rrshared_modsettingsblocks#.php where the number symbol matches the incremental mod version number, which is the last component of the folder's version "number". Thus, RR-shared_mod_includes_v12.0.0.4 would contain the file rrshared_modsettingsblocks4.php.

Protected files are identified by flagging a Mod Manger %copyfile command with a tilde, like this: %copyfile:~RR-shared_mod_includes_v12.0.0.4/rrshared_modsettingsblocks4.php%

When a protect file %copyfile command is places in each mod that wants to shared the file,

  1. The first mod that needs the shared file that is installed on a site actually installs the file,
  2. Mods installed later see the installed file and effectively ignore the %copyfile command.
  3. When a mod that uses the protected file is uninstalled, the protected file is not unistalled, since other mods that need it may still be installed.

The downside of this technique are that

  1. When all mods that use a protected file have been uninstalled, the file still remains in its TNG folder, and
  2. The file cannot be updated unless it is removed by a mod that does not use the protected flag.
    • To accommodate this condition, the shared folder name and filename must be changed (by incrementing the version number), and mods that need the new version must be modified to install the new shared file.

Technical details you don't need

What each mod must do

Mods that use this technique for their mod options

  1. Install (or at least try to install) the Include file rrshared_modsettingsblocks#.php from the mod subfolder RR-shared_mod_includes_v12.0.0.#,
  2. Install (or at least try to install), from the same shared subfolder, a small image file that is a Wiki icon (a stylized W), and that serves as a hyperlink to the mod's Wiki article,
  3. Define an HTML layout table in a TNG configuration program (that is, one of the Admin>>Setup programs). That layout table must contains all of the form fields that edit the configuration settings,
  4. Insert the PHP statement include_once("rrshared_modsettingsblocks4.php"); into the configuration program, and
  5. Modify the action script that saves the configuration program's fields to save the new options in the program's configuration file.

The mods add their layout tables at the end of the configuration page (not within the existing form or HTML layout table). A Javascript document.ready function defined in the Include file sorts all of those layout tables by mod name, and adds them to the appropriate HTML form or subform.

To enable this reorganization, each mod applies specific HTML attributes to its HTML layout table:

  1. (Required) class='rrConfigTable'
  2. (Required) modname= The mod name
  3. (Optional) subform= An existing subform ID within current configuration program
    • In admin_genconfig.php, this attribute defaults to "robin", the ID of the subform titled "Robin's Mods".
    • In admin_pedconfig.php, it defaults to "peddesc", the ID of the "Common Elements" subform.
    • None of the other Admin>>Setup pages have subforms, so they ignore this attribute.

The configuration array $rrconfig

All of the configuration variables created by my mods are stored in the appropriate configuration file in the array $rrconfig. Most of them have single string value (possibly with multiple delimited values), in $rrconfig["settingname"]. A few of my configuration variables are multivalued, with two subscripts.

What the Include file does

The Include file rrshared_modsettingsblocks#.php contains

  1. A PHP function that help mods define little 'D' buttons that restore fields to the mod's installation default.
  2. An embedded style sheet
  3. Miscellaneous small Javascript functions
  4. A large Javascript document.ready function that
    1. Reads each mod's HTML table and grabs the attributes it needs,
    2. Sorts the tables by mod name,
    3. Wraps each mod's HTML table inside an outlined div with the mod name as a heading, and
    4. Depending on which Admin>>Setup program is being modified, and whether a new subform is specified, either
      • Places the mod's div in a table row in an existing form or subform, or
      • Wraps multiple divs into a HTML table, which is then placed in a table row in an existing form or subform.

Resulting in something like this:

Inner mod menu-robins mods.png

The shared Include file also contains Javascript code that implements two new querystring variables for the Admin>>Setup programs:

  1. open specifies a subform to be opened automatically, and
  2. mod specifies a mod (within the "Robin's Mods" subform) to be opened automatically.

Thus, for example, the Admin Cemetery Edit mod could install a link in admin_editcemetery.php that specifies

href="admin_genconfig.php?open=robin&mod=AdminCemeterySearch,

and, when you follow that link, you will see only the options for the Admin Cemetery Edit mod:

Inner mod menu-one mod options.png

See Also