Mod Settings Blocks

From TNG_Wiki
Revision as of 16:04, 7 May 2020 by Robinrichm (talk | contribs)

Jump to: navigation, search

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,
  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.
    • Links directly to a Mod Settings Block can be found in Inner Mod Menus and in the Mod Managers "Edit Options" page for that mod.
To illustrate point 8 above, here's what the Admin>>Setup>>General Settings page looks like when I link directly to the options for the Admin Cemeteries Search mod.
Mod settings blocks-3blocks.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 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 of the mod list will open up that cell and reveal an "Edit Options" button. With my mods, when you click on Edit Options, you'll get something very close to 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 is 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<code> from the mod subfolder <code style='white-space:nowrap'>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