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	25 Mar 2024
	TNG 14.0.4
Download stats
Author(s)	Robin Richmond
Homepage	Mod Settings Blocks (This page)
Mod Support	My Mod Support form
Contact Developer	My Mod Support form
Latest Mod	14.0.4.4d
Min TNG V	13
Max TNG V	14.0.4
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.
- Robin Richmond, 19 Mar 2024

Purpose of the Mod

The initial (and still primary) purpose of this mod was to allow mod configuration 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 the Mod Settings Blocks mods. 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 "features":

[See Details]

1. Mod Settings Blocks, which handle mod configuration settings in my mods

1. 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]

[See Details]

2. Inner Mod Menus – Drop-down menu on TNG pages that link to information about relevant mods, especial their mod settings block .

2. Inner Mod Menus

[Hide Details]

Inner Mod Menus are drop-down menus that placed on modified TNG pages and that provide handy links to documentation about the mod configuration options are (by default) placed at the right end of the standard TNG "Inner Menu", which is 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]

[See Details]

3. Field Buttons – Handy one-character buttons that essentially serve as keyboard shortcuts.

3. 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]

[See Details]

4. New Tab Flags – Flags that mark tabs that have been created by mods.

4. 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]

[See Details]

5. Mods Used List – A list of the mods that affected a displayed page

5. 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 Mods Used List 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 all mods that use the following Mod Settings Blocks features

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 use Inner Mod Menus or Field Buttons but not Mod Settings Blocks include 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
Mods that define New Tab Flags but not Inner Mod Menus, Field Buttons, or Mod Settings Blocks include Gedcom Converter, Mod Manager Compare, and Placename Format

(There may be mods that are not listed above and that use the Mods Used feature, but that feature does not require Mod Setting Blocks mod because all mods that use it check don't even try to display the list if the supporting code is not present.)

[See Alphabetical List of Mod-Settings-Blocks-dependent Mods]

Alphabetical List of all Mod-Settings-Blocks-dependent mods

Admin Mods

The Regroup Person Family

Other End-user Mods

Admin Branches
Admin Branches Show Users
Admin Branches Queue
Admin Cemeteries Search
Admin Cemetery Edit
Admin Media Predefined Search
Admin Media Search
Admin Media Thumbnails
Admin Places Geocode
Admin Places Search
Admin Reports Search] Admin Languages
Admin Reports Floating Editor
Admin Users-More

Gedcom Converter

Gedcom Import Mediatype
Gedcom Import Purge
Mod Manager Compare
Placename Format

Regroup Person Profile
Regroup Person-Date Place
Regroup Person-Hide Branches
Regroup Person-Move Media
Regroup Person-No Living Data
Regroup Person-Sources
Regroup Person-Branch Members
Regroup Person-Child2Parent

Browsemedia Search Form
Cemetery Burials Table
Cemetery Headstones
Cemetery Map and Images
New Account Validation
Placesearch-More Info
TextPlus Charts

[Hide this list]

Installation

The latest version of this mod (14.0.4.4c) is required for TNGv14.0.4, and is not backwards compatible with TNGv14.0.3. The only updates in this version are to accommodate changes to admin_updateconfig.php in TNGv14. Since none of its functionality has changed, none of the many mods that depend on Mod Setting Blocks need to be updated strictly because of the new version of this mod, though Admin Media Search, Regroup Person Profile, Regroup Person-Date_Place, and TextPlus Charts (and perhaps others) have been or will upgraded to accommodate TNGv14.0.4.

Files Installed

Javascript
1. js/rrmsb_blocks.js - A Javascript library used to set up Mod Settings Blocks in admin_genconfig.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 that allowed me to avoid having to proactively change all of my mods that define Inner Mod Menus, Field Buttons, and New Tab Flags. I don't believe that any of these files nare required any longer, but I'm leaving them in place until I make sure.
1. rrinnermodmenu_lib.php%
2. rrmodsettingsblocks.php%
3. rrinnermodmenu_newtab.php%
4. js/fieldbuttonsmod.js%

This mod's language strings are defined, distributed and files in its mod subfolder rather than in its .cfg file. TNG programs affected by this mod then load language strings from those mod subfolder files rather than from cust_text.php files. This non-standard technique for handling language strings has several advantages, including that

It loads language strings only into the pages that need them rather than into all TNG pages, and
It simplifies the process of defining and editing translations.

This non-standard technique should be invisible to you unless you want to define a translation or override any of this mod's string values.
Read more about this technique, the simplified translation process, and the procedure for defining site-specific overrides to its language strings.

[Show Standard Installation Process]

Requirements

A working TNG installation.
An installed current version of the Mod Manager.
You should backup files listed in the panel on the right.

Procedure

Remove and delete previous version of this mod.
Backup the files updated by this mod. They are listed in the panel at the upper right.
Download the .zip file, Extract its .cfg file to the mods folder.
Follow the normal automated installation for Mod Manager, as shown in the example Mod Manager - Installing Config Files.

Problems?

Try using the Mod Manager Remove capability
Contact me through My Mod Support form.

[Hide Details]

Links to Mod Settings Blocks

All Mod Settings Blocks (that is, all mod configuration settings for mods that use Mod Settings Blocks) are in the "Mod Settings Blocks" sub-form at Admin>>Setup>>General Settings, like this:
]
(This screenshot shows just one Mods Settings Block, though a TNG site could have several;)
All Mod Settings Blocks (just like classic mod %parameters%) are accessible through the relevant mods' "Edit Option" in the Mod Manager List. The resulting Edit Parameters page would look something like this:
]
(If you were to click on the options for Admin Branch link in this screenshot, you would be taken to the Mod Settings Block for the Admin Branch mod, as shows in the screenshot above this one.)
(Almost) all TNG pages that are affected by mod configuration options that are defined in Mod Settings Block have a link directly to the relevant Mod Settings Blocks through a drop-down "Inner Mod Menu" within the standard "Inner Menu" just below each page's tab menu, like this:
- Importantly, Inner Mod Menus are visible only to TNG site admins.
- As illustrated here, if a given TNG page is affected by more than one Mod Settings Block, that page's Inner Mod Menu will contain links to each of them.

Revision History

Mod Version	TNG Versions	Date	Note
14.0.4.4d	14.0.4	25 Mar 2024	Accommodated changes made to admin_updateconfig.php in TNGv14.0.4; Fixed incorrect files uploaded for v4.0.4.4c
14.0.0.4b	14	11 Nov 2023	This mod now 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.
14.0.0.4a	14+	24 Sep 2023	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.
14.0.0.3a	14	28 Jan 2023	[See Details] 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 14.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. [Hide details
14.0.0.3	14	7 Jan 2023	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.
14.0.0.3	13	28 Sep 2020	French translation by Katryne Chauvigné-Bourlaud
13.0.0.1	13	6 Sep 2020	New mod.