Mod Settings Blocks

Mod Settings Blocks
Mod Settings Blocks
Summary	This mod installs code that is defined or declared in other mods:-Field Buttons-Inner Mod Menus-New Tab Flags-Mods Used This mod is a prerequisite for all mods that define Mod Settings Blocks, Inner Mod Menus, New Tab Flags, or Field Buttons.
Validation
Mod Updated	11 Nov2023
	TNG 14.0.3
Download stats
Author(s)	Robin Richmond
Homepage	(this page)
Mod Support	My Mod Support form
Contact Developer	My Mod Support form
Latest Mod	14.0.0.4b
Min TNG V	13
Max TNG V	14.0.3
Files modified	genlib.php, adminlib.php, admin_genconfig.php, admin_updateconfig.php, Dutch, English, French, and Norwegian cust_text.php, ; Installs 8 files: js/rrmsb_blocks.js, css/rrmsb_blocks.css, js/rrmsb_fieldbuttons.js, rrmsb_lib.php, rrmsb_modsused.php, js/rrmsb_lib.js, css/rrmsb_lib.css, img/rrmsb_wiki.gif
Related Mods	Virtually all of my other mods depend on this mod
Notes	Mods that depend on this mod should display a note to that effect in the Mod Manager list.

The name "Mod Settings Blocks" applies both to this mod and mod setting subforms that are implemented through this mod. This mod is required by most of my other mods. Mod Settings Blocks subforms support all types of form fields and both PHP and Javascript logic. They are thus more powerful (and much more complicated) than the native Mod Manager %parameters.

The current version of this mod is v14.0.0.4a. All of my TNGv14 mods installed before 1 Sep 2023 work with version 3 or version 4 of this mod. Mods installed after that require at least v14.0.0.4, and v14.0.0.4a is recommended.

- Robin Richmond, 24 Sep 2023

Purpose of the Mod

The initial (and still primary) purpose of this mod was to allow mod settings (sometimes called mod options or mod parameters) to be defined and edited in more powerful and flexible ways than is possible with the native Mod Manager %parameter feature.

With TNGv14, the Inner Mod Menus, Field Buttons, and Show Mod Names mods have been incorporated into Mod Settings Blocks. All three former mods fit naturally into this mod because, like Mod Settings Blocks, they did not modify TNG pages themselves (except for the mod settings form fields that they added to the Admin General Settings form). Instead, they installed the support code for features that could be used by other mods. Thus, at this point, Mod Settings Blocks has what I'll characterize as five "components"

Mod Settings Blocks
Inner Mod Menus - Drop-down menus that provides handy drop-down links to the Mod Settings Blocks that have changed those pages and to documentation about the mods and their settings.
Field Buttons - Handy one-character buttons that are attached to form fields and that essentially serve as keyboard shortcuts.
New Tab Flags - Flags that mark tabs (in the standard tab menus) that have been created by mods. The mod name will popup when the user mouses over the tab,
Mods Used List (The feature implemented by the old Show Mod Names mod), which generates a list of the mods that affected a displayed page at run-time. That is, the Mods Uses List essentially lists all of the mods that affected all of the modules used to execute the program..

Mod Settings Blocks [See Details]

Mod Settings Blocks

[ Hide Details]

Mod settings blocks contain the form fields that edit a mod's settings. All mod settings blocks are placed in a new subform titled "Mod Settings Blocks" in the Admin General Settings page. Each mod settings block is a subform within the Mod Settings Block subform. Opening the Mod Settings Blocks subform reveals all of the TNG site's mod settings blocks. But the Links to Mod Settings section below identifies link within the Mod Manager and in modified programs that will open only a single specified mod settings block.

For example, in contrast to the textarea fields that are always and only used by %parameters, Mod Settings Blocks support the use of checkboxes, selection boxes, and radio buttons to constrain a setting's value. In fact, Mods Settings Blocks can use virtually the full power of HTML (not just form fields), PHP, and Javascript, and can use the current value of any TNG configuration setting or mod setting. This mockup of portions of three mod settings blocks reveals,

Buttons that open and hide other form fields
Checkboxes, a selection box, and radio buttons
An icon that pops up help text
A set of radio buttons that are displayed in a table and whose values are recombined into three mod settings.
A field with type="number"
A small "D button that fills in a default value, and
A set of fields that are disabled and greyed out when a checkbox is unchecked (In the Cemetery Map and Images block)

The image also reveals the general appearance of mod setting blocks, which are enclosed in borders and identified by mod name. The mod name and W icon are links to the mod's Wiki article. The mod settings blocks are displayed one column and in alphabetical order (expect that the mod settings block for the Mod Settings Blocks mod is always first.)

The Mod Settings Block mod is defined and documented so that it can used for any mod written by any mod programmer. However, at this point, the author of the Mod Settings Blocks mod (Robin Richmond) is the only programmer who has defined mod settings blocks - in approximately 25 mods. only mods that use mod settings blocks on a TNG site and the names of those blocks will, of course, vary according to the mods that have been installed on that site.

Mod Settings Blocks are non-standard in TNG, but have several advantages over conventional options defined by %parameter% tags in Mod Manager.

[See Advantages and Disadvantages of Mod Settings Blocks]

Advantages

[Hide Advantages and Disadvantages]

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 be validate at the time they are entered,
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 composite values that are built from more than one form field,
Can have pop-up help text that provides more information than typical mod parameter prompts,
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.

In addition,

Programs that are affected by mod options can have links (visible only to Admins) directly from those programs to the relevant Mod Settings Block. That is, if you see program behavior that is driven by an option, and you want to change that option, you don't necessarily have to close the program, return to the Mod Manger, edit the option there, and then return back to the program that is affected by the option.
The prompts, labels, and descriptions for options in Mod Settings Blocks can be translated into languages other than English. (Well, of course, with classic Mod Manager parameters, a prompt can include text in more than one language, but the language cannot be driven by the TNG language setting. Instead, all of the languages have to be visible at the same time.)

Note that some mods do already define their mod options in Admin>>Setup pages, but those options are relatively hidden among all of the many TNG settings. With Mod Settings Blocks, the options for a mod are clearly distinguished from other mods' options.

Disadvantages

Classic Mod Manager Parameters are more familiar
Every classic Mod Manager Parameter necessarily can be set back to a default value. Only a few settings in Mod Settings Blocks can be reset to a default value, but all settings for a given mod can be reset by

Uninstalling the mod
Running and saving the form at Admin>>Setup>>General Settings. You do not need to change anything.
Reinstalling the mod.

[Hide Advantages and Disadvantages]

[Hide Mod Settings Blocks Details]

Inner Mod Menus [See Details]

Inner Mod Menus

[Hide Details]

Inner Mod Menus are drop-down menus that are (by default) placed at the right end of the "Inner Menu", which is a the horizontal menu immediately below the Tab menu. Both the Inner menu and Tab menu menus are standard components of TNG end-user and admin pages. Mods that make "significant" changes to a TNG page define an Inner Mod Menu for that page. If more than one mod changes a page, all Inner Mod Menus that have be defined for that page are consolidated into one drop-down menu on the page.

For example, in the screenshot below, three mods have define inner mod menus for admin_places.php. Admin Place Copy and Admin Places Date have no options, but they have defined messages that describe what they have done to the page. ]Admin Places Search has options and a "What Has Changed" message.

The default value for the menu heading is "Mod Information", but the heading is a setting within the Mod Settings Blocks mod.

Each mod's Inner Mod Menu (within a page's Inner Mod Menu) contains up to four links:

The mod name and a W icon (like the one in the Mod Manager's mod list) link directly to the mod's Wiki page.
"Mod Options Help" links to the "Option" section of that Wiki article.
"Change Mod Options" links to the mod's Mod Settings Block in admin_genconfig.php (Admin>>Setup>>General Settings).
- This link loads the page, and displays only the specified Mod Settings Block like this:
  
  (If you follow the Admin menus to the General Settings Page, you'll see all of your Mod Settings Blocks if you open the Mod Setting Blocks subform, and then you'll have to scan through the alphabetized mod settings blocks to see the one you want.
"What Has changed" displays a pop-up that (as you might expect) describes what the mod has changed about the program.

[Hide Inner Mod Menu Details]

Field Buttons [See Details]

Field Buttons

[Hide Details]

Field Buttons are small buttons (with 1-character labels) that are attached to form fields and that perform handy editing tasks.

X - clears the field
R - Restores the value that the field had when the page was loaded
D - Fills the field with a default value that has been specified within the page.
A - Represents "All" possible choices for a field that specifies things such as a search page's number of results per

This screen clip illustrates 5 field buttons on 2 fields in admin_reports.php (Admin>>Reports), which has been modified by the Admin_Reports_Search mod.

The search field has X and R buttons, but not D or A buttons because they do not apply. That is, in a search field, here is no need for a default value (other than an empty string, which the X button handles) nor to an "all items" value (which would also be an empty search field).
The 'Results per page" field, which was added by the mod, has R, D, and A buttons.
- You never want an empty 'Results per page' value, so there is no X Button.
- The D button sets a default value, which, in this case, is the TNG system variable $maxsearchresults.
- The A button sets a value that represents 'All Items'. That value is the word 'all' (or its translation). When the value 'all' is passed back to the page as part of the submit form, the page does not have to interpret it as a large number; the page can just use 'all' to omit a result set size in its SQL query.

To recap

the X button is not needed when a field value is already empty,
the R button is not needed when the current value is the initial value,
the D button is not needed when current value is the default value, and
the R button is not needed when the current value is the 'All Items' value.

When a button is not needed, it is shaded out, but still physically present on the screen.

[Hide Field Buttons Details]

New Tab Flags [See Details]

New Tab Flags

[Hide Details]

New Tab Flags do just what the name implies - they highlight the fact that a new tab has been created by a mod, and allow the user to see which mod installed the new tab. The flag is an asterisk, and the mod name is displayed when the user hovers over the asterisk, like this:

[Hide New Tab Flags Details]

Mods Used List [See Details]

Mods Used List

[Hide Details]

This rarely-used feature is intended to lists the names of mod-altered files that were used in the construction of a TNG page and the names of the mods that altered those files. It does not report how the files changes or how those changes may have affected the page; it is just a cross-reference list of modnames and filenames. It is analogous to information that the Mod Manager Analyzer reports about the mods that affect a file, but the Mod Manager Analyzer cannot report how mods affect a given page as it is displayed. ((See the Show Mod Names article)

[Hide Show Mod Names Details]

Mod Options

In TNGv14, the Mod Settings Block has its own mod settings block. The meaning of each setting should be evident from this screen of that mod settings block

Compatibility

No known incompatibilities. THis mod is used only by mods that I (Robin Richmond) wrote.

Related Mods

This mod is a prerequisite for

Mods that place mod settings in a Mod Settings Block.
- At the moment, over 20 mods have Mod Settings Blocks, including Admin Branches Show Users, Admin Branches, Admin Cemeteries Search, Admin Cemetery Edit, Admin Media Predefined Search, Admin Media Search, Admin Media Thumbnails, Admin Places Geocode, Admin Places Search, Browsemedia Search Form, Cemetery Burials Table, Cemetery Headstones, Cemetery Map And Images, Gedcom Import Mediatype, Gedcom Import Purge, New Account Validation, Placesearch-More Info, Regroup Person-Branch Members, Regroup Person-Child2Parent, Regroup Person-Date Place, Regroup Person-Hide Branches, Regroup Person Profile.
Mods that define Inner Mod Menus or Field Buttons
- This includes mods such as Admin Reports Search, Admin Branches Queue, Admin Languages, Admin Reports Floating Editor, Admin Users-More, Regroup Person-Move Media, Regroup Person-No Living Data, and Regroup Person-Sources

Installation

Files Installed

Javascript
1. js/rrmsb_blocks.js - A Javascript library used to set up Mod Settings Blocks in admin_genfig.php.
2. js/rrmsb_fieldbuttons.js% - Dedicated Javascript library for Field Buttons.
3. js/rrmsb_lib.js - (mostly) for Inner Mod Menus and New Tab Flags
CSS files:
1. css/rrmsb_blocks.css - Styles for MSBs in admin_genconfig.php.
2. css/rrmsb_lib.css# - Styles for Field Buttons, Inner Mod Menus, New Tab Flags, and the "Mods Used" feature (formerly Show Mod Names)
These standalone css files are examples of my policy of avoiding genstyle.css for style rules that are used in only a very few TNG pages.
PHP files:
1. rrmsb_lib.php - PHP functions for Inner Mod Menus and New Tab Flags.
2. rrmsb_modsused.php - Function and inline code for the "Mods Used" feature (formerly Show Mod Names).
Images
1. /img/rrmsb_wiki.gif:img - A styled W used for links to mod articles in the TNG wik. Used in Mod Settings Blocks and Inner Mod Menus.
Legacy files from Mod Settings Block v3 and from the mods that were incorporated into Mod Settings Blocks for TNGv14.
- These files are part of a backward-compatibility scheme that allowed me to avoid having to proactively change all of my mods that define Inner Mod Menus, Field Buttons, and New Tab Flags. When Inner Mod Menus, Field Buttons, and New Tab flags were implemented by separate mods, all mods that defined instances of those features had to install the relevant <link> & <script> elements and Include statements into all programs that used those features. Now that Inner Mod Menus, Field Buttons, and New Tab Flags have been incorporated into Mod Settings Blocks, individual mods don't need to load that code into numerous programs. But since the centralized code uses the same function names that were in the legacy files, those functions are available to various programs whether or not those programs load the legacy files. Since the legacy files are now empty, mods and programs that do still load these legacy files don't actually load any code from them. Thus those mods and programs don't have to be changed proactively.*$#
1. rrinnermodmenu_lib.php%
2. rrmodsettingsblocks.php%
3. js/fieldbuttonsmod.js%
4. rrinnermodmenu_newtab.php%

languageandfiles] install]

Links to Mod Settings Blocks

Just as you would expect, opening the Mod Settings Blocks subform within the Admin General Settings page reveals all of the site's mod settings blocks, kind of like the inage on the right. But it is possible to load the General Setting page with only specified mod settings block visible. Links that open one mod settings block can be found in two places:

'From the Mod Manager Edit Options page for each mod that has a mod settings block.

the page for each mod with a mod settings block contains a hyperlink that opens only that block.directly to the mod's options. That is, the Edit Options page for each mod that has a Mod Settings Block looks very much like this:

1. From each "Edit Mod Options" link in inner mod menus, which look like thislike this:

Revision History

Mod Version	TNG Versions	Date	Note
14.0.0.4b	14	11Nov2023	This mod installs code that is defined or declared in other mods:-Field Buttons-Inner Mod Menus-New Tab Flags-Mods Used This mod is a prerequisite for all mods that define Mod Settings Blocks, Inner Mod Menus, New Tab Flags, or Field Buttons.
v14.0.0.4a	14+	24Sep2023	Moved all language strings to standard cust_text.php files. Installed a patch that allows to it be backwards compatible from TMGv14.0.2 to TNG14.0. Reorganized code in library files.
v14.0.0.3a	14	28Jan2023	All mods that have Mod Settings Blocks, Inner Mod Menus, or Field Buttons and are (or were) installed Before 28 Jan 2023 are compatible with both v14.0.0.3 and v14.0.0.3a. Change #1 below is the only one that even affects such mods. After Jan 28 v14.0.0.3a. Forces the Mods Settings Block for the Mod Settings Blocks mod to be the first Mod Settings Blocks in the options editor. In both genlib.php & adminlib.php, calls the field buttons initialization function after loading the FB library. (Mods that use field buttons thus don't have to go through the somewhat complicated process for initializing them.) Adds the ability to place Inner Mod Menus in the page footer Moved language strings to the mod subfolder Added functions that are called before and after each mods settings are written to the configuration file. These functions consolidate some functionality used by several mods, and will allow updates to Mods Settings Blocks to change aspects of the configuration file without having to change individual mods.
v14.0.0.3	14	7Jan2023	For TNGv14, Installs the code, strings, and Include file that were previously installed by Show Mod Names, Inner Mod Menus, and Field Buttons Defines mod settings that enables the features of each of the formerly separate mods. All Mod Settings Blocks are now in the General Settings form. In TNGv12, some mods placed their Mod Settings Blocks in the Import/Export or Chart Settings forms. Mods that change native settings in those other forms now add a note explaining the the remaining settings for that mod are in the General Settings form.
v14.0.0.3	13	28Sep2020	French translation by Katryne Chauvigné-Bourlaud
13.0.0.1	13	6Sep2020	New mod.