Difference between revisions of "Mod Settings Blocks"

From TNG_Wiki
Jump to: navigation, search
(Page that all of my mods with mod options will link to)
 
(No difference)

Latest revision as of 20:15, 13 September 2019

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.

Mod Setttings

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.mod options in my new and updated mods are custom TNG setting - that is, custom TNG configuration variables, which are stored in TNG configuration files, and edited in the Admin>>Setup>> programs.

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 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 Settings>>Robin's Mods that points to those settings.

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.

<span class='mw-collapsible mw-collapsible-content mw-customtoggle-mm1a mw-customtoggle-mm1b' id='mw-customcollapsible-mm1a' s
[Hide the screen clip]

Robins folder open.jpg

[Hide the Screen Clip ]
</div>

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 Protected Files feature that was introduced in TNGv12.

What each mod must do

Mods that use this scheme for their mod options

  1. (Conditionally) Install the Include file rrshared_modsettings1_include.php,
  2. (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.
  3. 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,
  4. Inserts the PHP statement include_once('rrshared_modsettings1_include.php'); into the configuration program, and
  5. Modifies the action script that saves the configuration program's fields to its 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.
  4. (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 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, in the form

  • $(Correspondingly, 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:

  1. In the form: Define a hidden form field named rrconfig[modname] whose value is a list of the names of that mod's settings.
  2. 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_modsettings{v}_include.php contains

  1. 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.
  2. Three small PHP functions that help mods define little 'D' buttons that restore fields to the mod's installation default.
  3. An embedded style sheet
  4. Miscellaneous small Javascript functions
  5. 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, and
    3. Wraps each mod's forms inside
      • An outlined div with the mod name as a heading (and with a , then
      • A form layout table, and
      • A new subform that is added to the 14 existing subforms in the page,

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:

  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

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 ;Settings >> Robin's 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