Mod Settings Blocks

From TNG_Wiki
Revision as of 08:03, 25 March 2024 by Robinrichm (talk | contribs) (version 14.0.4.4d)
Jump to navigation Jump to search
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
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
Download link v14.0.4.4d
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.

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 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.
ModSettingsBlocksExcerpts.jpg

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

  1. Can be defined through checkboxes, radio buttons, and selection boxes,
  2. Can be validate at the time they are entered,
  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 composite values that are built from more than one form field,
  5. Can have pop-up help text that provides more information than typical mod parameter prompts,
  6. Can be combined with related options into tables and lists, and, notably
  7. Can be applied readily to more than one program, and even be used by programs modified by other mods.

In addition,

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

  1. Classic Mod Manager Parameters are more familiar
  2. 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.
500
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:

  1. 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.
  2. "Mod Options Help" links to the "Option" section of that Wiki article.
  3. "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:
      Mod settings blocks13-adminplacessearch.jpg
      (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.
  4. "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.

  1. 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).
  2. 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.

Fieldbuttons-fig1.jpg

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:
Show inner mod menu-newtab1.jpg

[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
ModSettingsBlocksMSB.jpg

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

(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]

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 does not use standard cust_text.php files for language strings. Instead, it stores languages strings in the mod's subfolder, and pages modified by this mod load language strings directly from files in the mod's languages/ subfolder. Read more about this technique and its procedure for handling site-specific language string overrides. [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

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

Problems?

  1. Try using the Mod Manager Remove capability
  2. Contact me through My Mod Support form.
[Hide Details]

Links to Mod Settings Blocks

  1. 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:
    ]Mod settings blocks13-adminplacessearch.jpg
    (This screenshot shows just one Mods Settings Block, though a TNG site could have several;)
  2. 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:
    ]ModSettingsBlocksMMOptionsPage.jpg
    (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.)
  3. (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:
    ModSettingBlocksIMM.jpg
    • 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.
  1. Forces the Mods Settings Block for the Mod Settings Blocks mod to be the first Mod Settings Blocks in the options editor.
  2. 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.)
  3. Adds the ability to place Inner Mod Menus in the page footer
  4. Moved language strings to the mod subfolder
  5. 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,
  1. Installs the code, strings, and Include file that were previously installed by Show Mod Names, Inner Mod Menus, and Field Buttons
  2. Defines mod settings that enables the features of each of the formerly separate mods.
  3. 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.

Sites using this mod

If you download and install this mod, please add your TNG site to the table below:

URL User Note Mod-Version TNG-Version User-language !
Robin's Roots Robin Richmond (developer) Go to my test site and login with a/a to see the Inner Mod Menu which link to Mod Settings Blocks 14.0.4.4d 14.0.4 EN
Roots & Relatives Remembered Ron Krzmarzick Public & Private See Here See Here EN,DE,CS
Family tree of Marcin & Emilia Senderski Marcin Senderski Only home page is public 13.0.0.1a 13.0.4 EN, PL
Vitter-Weaver Genealogy Jeffrey Vitter Public site 13.0.0.1b 13.0.3 EN,FR,CH,DE,ES,IT,NO
Hooley Family Links Rick Hooley Public/Private See Here See Here EN
KK's Family History Kathy Kult Public/Private site 14.0.0.3a
TNG 14.0.2
EN
Out Family James Dewberry Private 13.0.0.1a 14.0.0 EN
The Cole / Tanner Family Tree David Cole Public/Private see here see here EN,DE,FR,ES,NL
Die Familie Assent-Metternich Rainer H. Assent Private 13.0.0.1a 13.0.3 DE
Bastiaanssen Genealogy Jan Bastiaanssen Public / Private 13.0.0.1a 13.1.2 EN,NL,ES
Delvee Family Association Rob Roy Public 13.0.0.1a 13.1.1 EN
Sejarah Thümann Jeffrey Thümann Public 13.0.0.1a 13.0.3 NL,EN
Joseph Oran Holtz Genealogy Pages Jim Holt Private See Here See Here EN
Osage County Cousins Larry G Banks Public / Private 14​.0​.0​.3a 14.0 EN
Huygens - Van de Moortel Tom Huygens Public/Private on WordPress 13.0.0.1 13.1.2 NL
MOTYER Family Genealogy John Mark Motyer Public site See here See here EN
Your Roots are Showing Harold Craswell Public/Private See Here See Here EN
Van Peer Project Drew McClenaghan Private Site 14.0.0.3 14.0 EN
Daniel Bender - Generations Allison Sibert Public/ Living Private 13.0.0.1a 13.1.2 EN
Baza danych Rodziny Jarocińskich Michał Jarociński non-public site 14.0.0.2 14.0 PL,EN
ADLER-Wien Herbert Fischer Public site 14.0.0.2 14.0 DE
Les Lapierre d'Amérique Normand Lapierre Public/Private site 14.0.0.3 14.0 FR,EN
R G Strong Family Genealogy Russell Strong Public 14.0.0.4c
TNG 14.0.4
EN,DE,FR,NL
Kielakowie.com Janusz Kielak Public site 13.0.0.1a 14.0.1 PL,EN,DE
The Duttons of New England Darrin Dutton Public/Private site 14.0.0.3a 14.0.1 EN
Solem Genealogy Jan-Thore Solem Private 14​.0​.0​.3a 14.0.2 EN,NO
Genealogie Kroezen-de Man Jacob Kroezen Public/Pricate site 14.0.0.3a 14.0.2 EN,NL,FR
Os Belard Luís Belard da Fonseca Public 14.0.0.3a 14.0.2 PT,EN
Mello Garrido Luís Belard da Fonseca Public 14.0.0.3a 14.0.2 PT,EN
Auf den Spuren meiner Ahnen Michael Klein Public/Pricate site - Thanks to Russell Strong 14.0.0.4c
TNG 14.0.4
EN,DE,FR,NL,ES