Difference between revisions of "Mod Settings Blocks"

From TNG_Wiki
Jump to navigation Jump to search
Tags: Mobile edit Mobile web edit
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
This article is about a scheme that organizes mod settings 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.
  
== Mod Setttings ==
+
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'''
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, I use ''custom TNG settings'', that is, system variables that are saved in TNG's configuration files, and edited by the HTML forms at Admin>>Setup.
 
  
Significantly, I have enough mods with mod settings that I have defined '''a new subform named "Robin's Mods"''' in the general setting configuration program, admin_genconfig.php, at '''Admin>>Setup>>General&nbsp;Settings'''. I put almost all of settings into that subform, unless there is a compelling reason to put them elsewhere, in which case I will probably put an note in '''Admin>>Setup>>General&nbsp;Settings>>Robin's&nbsp;Mods''' that points to those 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
 +
#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.
  
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.
+
Mod Settings Blocks are distinct from other options in the Admin>>Setup programs in that
<div>[[Image:robins_folder_open.jpg]]</div>
+
#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
 +
#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 Include file is named '''rrshared_modsettings1_include.php''' (where the '1' in the filename is the a version number), and it is installed from the shared folder '''RR-shared_mod_settings_v12.0.0.1'''.  (The two version numbers will change together.) The Include file is shared among all of my mods that have mod settings, and can be installed by any of them.  The notion of a shared Include file is possible through the '''[[Mod_Manager_Enhancements_TNG_v12#Protected_flag|Protected Files]]''' feature that was introduced in TNGv12.
+
== Links to Mod Settings Blocks ==
  
== What each mod must do ==
+
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.
Mods that use this scheme for their mod options
+
 
# (Conditionally) Install the Include file <code>rrshared_modsettings1_include.php</code>,
+
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]]
# (Conditionally) Install a small image file that is a Wiki icon (a stylized W), and serves as a hyperlink to the mod's Wiki article.
+
 
# Define an HTML layout table in a configuration program. That layout table, of course, contains all of the form fields that edit the configuration settings,
+
== Protected Files ==
# Inserts the PHP statement <code>include_once('rrshared_modsettings1_include.php');</code> into the configuration program, and
+
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
# Modifies the action script that saves the configuration program's fields to its configuration file.
+
* 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 <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'''.
 +
 
 +
Protected files are identified by flagging a Mod Manger %copyfile command with a tilde, like this:
 +
<code style='white-space:nowrap'>%copyfile:~RR-shared_mod_includes_v12.0.0.4/rrshared_modsettingsblocks4.php%</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,
 +
# 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,
 +
# Insert the PHP statement <code>include_once("rrshared_modsettingsblocks4.php");</code> into the configuration program, and
 +
# 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.  
 
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.  
Line 28: Line 67:
 
#* In admin_pedconfig.php, it defaults to "peddesc", the ID of the "Common Elements" subform.
 
#* 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.
 
#* None of the other Admin>>Setup pages have subforms, so they ignore this attribute.
# (Optional) group= An arbitrary name such as "Places", "Reports", "Media", "People" into which the mods can be grouped.
 
#* This value was intended either to be used in an index of mods, or as part of the modname sort key, but, at present, it is not used.
 
 
== The configuration array $rrconfig ==
 
All of the configuration variables created by my mods are stored in the appropriate configuration file as $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 subscript.
 
 
=== Technical Details ===
 
 
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''"].
 
  
To simplify the code in the action scripts, mods with single-field settings do the following:
+
=== The configuration array $rrconfig ===
# In the form: Define a hidden form field named rrconfig[''modname''] whose value is a list of the names of that mod's settings.
+
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.  
# 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 ==
+
=== What the Include file does ===
The Include file rrshared_modsettings{v}_include.php contains
+
The Include file rrshared_modsettingsblocks#.php contains
# PHP and Javascipt code that initialize Field Buttons, so that multiple mods that use field buttons in the configuration program don't have to repeat the initialization.
+
# A PHP function that help mods define little 'D' buttons that restore fields to the mod's installation default.  
# Three small PHP functions that help mods define little 'D' buttons that restore fields to the mod's installation default.  
 
 
# An embedded style sheet  
 
# An embedded style sheet  
 
# Miscellaneous small Javascript functions
 
# Miscellaneous small Javascript functions
 
# A large Javascript document.ready function that
 
# A large Javascript document.ready function that
 
## Reads each mod's HTML table and grabs the attributes it needs,
 
## Reads each mod's HTML table and grabs the attributes it needs,
## Sorts the tables by mod name, and
+
## Sorts the tables by mod name,
## Wraps each mod's forms inside
+
## Wraps each mod's HTML table inside an outlined div with the mod name as a heading, and
##* An outlined div with the mod name as a heading (and with a , then
+
## Depending on which Admin>>Setup program is being modified, and whether a new subform is specified, either
##* A form layout table, and
+
##* Places the mod's div in a table row in an existing form or subform, or
##* A new subform that is added to the 14 existing subforms in the page,
+
##* 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:
 
Resulting in something like this:
 
<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 70: 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>
 
== Mods that define ==
 
Essentially all of my mods that are updated or created staring in August 2019 and that have mods settings will define those settings in Mod Setting Blocks, which, in most cases, will be in Admin >> Setup >> General&nbsp;;Settings >> Robin's&nbsp;Mods'''.
 
 
By late September, 2019, this should include [[Admin Branches]], [[Admin Cemeteries Search]], [[Admin Cemetery Edit]], [[Admin Media Predefined Search]], [[Admin Media Search]], [[Admin Places Geocode]], [[Admin Places Search]], [[Admin Reports Search]], [[Field Buttons]], [[Gedcom Import Mediatype]], [[Headstones Report]], [[Regroup Person Profile]], [[Regroup Person-Date Pace]], [[Regroup Person-Parent Rel]], [[Show Mod Names]], and [[TextPlus Charts]].
 
  
 
== See Also ==
 
== See Also ==
 
* [[Inner Mod Menus]]
 
* [[Inner Mod Menus]]
 
* [[User:Robinrichm#My_Mods|Robin's Mods]]
 
* [[User:Robinrichm#My_Mods|Robin's Mods]]

Revision as of 11: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:

File: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