Show Mod Names

From TNG_Wiki
Revision as of 12:18, 18 July 2016 by Robinrichm (talk | contribs) (mod v3)
Jump to navigation Jump to search
Show Mod Names
Summary A utility mod that doesn't change any programs by itself, but rather installs an include file that is used by other mods to reveal to admins (and potentially all users) the names of mods that affect the running TNG programs.
Validation
Mod Updated {{{mod_last_update}}}
Download link For
TNG 11.0
TNG 10.0
show_mod_names_v10.0.0.3.zip
Download stats
Author(s) Robin Richmond
Homepage Robin Richmond's Genealogy Database
Mod Support My Mod Support form or TNG Community Forums
Contact Developer My Mod Support form
Latest Mod 10.0.0.3
Min TNG V 10.0
Max TNG V 11.0.1
Files modified
css/cust_text.css, genlib.php, creates showmodnames.php
Related Mods
My mods that require this mod are flagged on my Wiki home page
Notes


Purpose of the Mod

To display a list of the mods that affect a particular program, if those mods have "registered" themselves. This mod doesn't do anything by itself; it just installs code that can be used by other mods. It exists as a separate mod only so that each mod that wants to use this new mod-listing scheme doesn't have to install this code redundantly.

In other words, you should install this mod only if you install one or more other mods that say they depend on this mod. (Or, in other words, you should install this mod if you install any of Robin Richmond's mods.)

This mod (and the overall mod-reporting scheme behind it) is motivated primarily by the fact that when mod developers go to a TNG site to track down a possible mod problem it is often not clear which mods (and which versions) affect the program they are checking out. Although TNG Mod Manager does a good job of listing which versions of which mods are installed, and its Analyzer shows which mods affect which TNG files,

  1. it is only available to the administrator of a site, and
  2. it does not show which mods affect the function libraries used by a program.

This mod can also be useful for TNG site administrators as a reminder of which mods affect a given program, as it is not easy to remember exactly which features of a program are "pristine" and which are the result of mods.

This mod, and the mod-registration scheme behind it ARE NOT anything close to a TNG standard or convention. I have attempted to implement and document it so that it could be used more widely, but, in truth, I don't know of any other mod programmers who are considering using this scheme.

Mod Parameters

The three mod parameters determine how visible the mod list is to users.

  1. $showModNamesAtAll determines whether the running program will try to display the mod names on the screen, or just write them to an HTML comment. If it is false, the mod names will always be written to an HTML comment, and will never affect the visible output of any program. It defaults to true.
  2. $showModNamesAdminOnly determines whether to display mod information only only to administrators. When it is true, the code will not affect the output of programs run by non-admins. (Note that this parameter's value doesn't matter if the first parameter value is false.) It default to true.
  3. $showLinkToModNames causes the list of mods to be hidden behind a button. (Again, this parameter's value doesn't matter if the first parameter value is false.) It defaults to true.

With the parameters' default values:

  • End users never see information about the mods that affect the program they are running, since the list of mods is placed in an HTML comment.
  • Administrators see just a "Show Mods" button in the program footer, and can click on that button to see the list.

Compatibility And Dependencies

No known conflicts. This mod is not dependent on any other, but several mods are dependent on it.

Installation

  1. Uninstall previous version of this mod.
  2. Backup css/genstyle.css, the only distributed file affected affected by this mod.
  3. Download the .zip file and 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.

In the event of a problem

  1. Try using the Mod Manager Remove capability
  2. Contact the mod author through My Mod Support form.

Visualization of this Mod

AFTER:
With the default parameters, there is no visible effect to end-users, but admins will see this button in the footer of pages produced by programs that have been affected by mods that implement the Show Mod Names scheme. The list of mods can be made more or less visible through the mod parameters described above.
When admins run end-user programs that use this mod (and that have a template-controlled footer), they will see this button at the very body of the content area of the page:

Show mod names-after-enduser.png

Admin programs that use this mod will display the button on the left side of the page footer.

Show mod names-after-admin.png

Here's how an admin program footer might look after the button is clicked. The version of each mod is shown, and each mod name is a hyperlink to the mod's Wiki article.

Show mod names-after-expanded.png

Then, as you mouseover one of the mod names, you can see
  1. The hyperlink to the mod's Wiki page, and
  2. The mod's Title text, which lists the files that the mod edits, and possibly the PHP function(s) within a file.

Show mod names-after-mouseover.png

Programmer Documentation

You don't need to understand any of the documentation in this section to install this mod. This information is just for programmers who wish to use this scheme in their mods.

Registering a mod

If a mod - or really, a modded program, wants to display a list of mods that affect the program, the program (via mods) must first "register" each mod at runtime by saving it in the associative array $tngModNames through a PHP statement of the form

$tngModNames[mod name][program name] = version#;

e.g.

$tngModNames['Show Branch Members']['getperson.php'] = 1;

The mod name should be the same as the name of Wiki article that describes it (with or without underscores). If your mod name doesn't match your Wiki article, you might consider changing one or the other. But since the mod name saved in $tngModNames will be used to form a hyperlink to the Wiki article, you should use the Wiki article name rather than the mod name if they are different.

The version number should generally represent just the mod version number (typically, a single digit; sometimes a number and a letter such as "12c"), not the full filename suffix consisting of a TNG version and mod number (typically, 4 "period-parts"). However, if, say, you have distributed mymod_v9.0.0.4 for TNG9 and TNG10.0 as well as mymod_v10.1.0.4 for TNG10.1 and above, then it might be appropriate to specify the full version string.

Where to place the registration statement

It is generally useful, just for the sake of documentation, for mod programmers to put a comment at the beginning of each PHP file that they modify. And it is generally convenient to "register" the mod along with that comment. For instance, the program admin_dataimport.php has been modified by three different mods, each of which have placed comments at the top of the file, so that the beginning of the file looks something like this:

<?php
# This program has been modified by the Gedcom Import Purge mod to:
# - Offer a checkbox so the user can or suppress the purge of media links previously
#   imported from a Gedcom.
$tngModNames['Gedcom Import Purge']['admin_dataimport.php'] = 1; #Register the mod

# This program has been modified by the Gedcom Import Monitor mod to (for example):
# - Offer a set of radio buttons to control the frequency of import status display.
# - Add an information hyperlink (a circled question marks) to a new section of the help page.
# See the mod's wiki article for a more complete description of the changes.
$tngModNames['Gedcom Import Monitor']['admin_dataimport.php'] = 3; #Register the mod

# This program has been modified by the Gedcom Import Mediatype mod to:
# - Define a mod parameter with the Mediatype (photos, documents, etc.) 
#   to be used for all new Media Items created by the Gedcom Import.
# - Define a new control on the form that kicks off the Gedcom import so that the 
#   user can confirm that default Mediatype.
$tngModNames['Gedcom Import Mediatype']['admin_dataimport.php'] = '2a'; #Register the mod

(I'll note parenthetically that I almost always start PHP rest-of-the-line comments with # rather than // so that my comments can be easily distinguished from Darrin's.)

In this example, admin_dataimport.php would have been modified by

  1. Gedcom Import Purge, version 1 (perhaps gedcom_import_purge_v10.0.0.1),
  2. Gedcom Import Monitor, version 3 (perhaps gedcom_import_monitor_v10.1.0.3), and
  3. Gedcom Import Mediatype, version 2a (perhaps gedcom_import_purge_v10.1.0.2a).

And, since admin_dataimport.php originally started with

<?php
include("begin.php");

each mod would have used a .cfg file target location such as

%target:admin_dataimport.php%
include("begin.php");
%end:%
%insert:before%
# This program has been modified by the Gedcom Import Mediatype mod to:
# {additional notes...}
$tngModNames['Gedcom Import Mediatype']['admin_dataimport.php'] = '2a'; #Register the mod

%end:%

Registration in Function Libraries

One mod may modify several files, of course, and those files can be separate programs, function libraries, configuration files, etc. You can register the mod in each file, or not, as you wish. If mod X modifies getperson.php and genlib.php, for example, registering the mod at the beginning of genlib.php would be redundant with registering it with getperson.php for the purpose of displaying mods that affect getperson.php. However, other programs that use genlib.php could also be affected by mod X. So it should generally be useful to either

  1. register mod X at the beginning of genlib.php, or
  2. register mod X in each modified function.

Registering mod X at the beginning of genlib.php would ultimately have the effect of listing mod X as affecting every program that Includes genlib.php (which is probably overkill), whereas registering mod X in each modified function would have the effect of listing mod X as affecting only those programs that call those same functions (and that execute the line of code where mod X is registered).

Displaying the Mod Names

To display the names of all mods that have been registered by a program, a mod that modifies that program should target a statement as close to the bottom of the program as practical, and insert the PHP Include statement

include_once ('showmodnames.php');

Along with a comment that makes this insertion unique, and, of course that describes what's going on.

If several mods that use this mechanism all modify program Y, then program Y will have multiple instances of the necessary include_once statement. But, by the nature of include_once, the code in showmodnames.php will be included only once in program Y, and will be executed only once.

Placing the Mod Names on the Page

End-User Programs

TNG end-user programs typically use TNG templates to display page footers, and those templates are typically invoked through the statement

tng_footer( $flags );

or some variant such as tng_footer( "" );

So, for end-user programs, it is generally quite easy to know when you have reached the bottom of the content area of the page. Here's an example, which adds an end-of-line comment that

  1. makes the insertion unique,
  2. flags the insertion as coming from a mod, and
  3. describes its purpose.
%location:%
tng_footer( $flags );
%end:%
%insert:before%
include_once ('showmodnames.php'); ### Show Branch Members Location 4: Output the names of mods that affect this program
%end:%

Remember that, using the default options in Show Mod Names, end users will not see the mod names (nor the button that may be hiding them), since the code in showmodnames.php will output the mod names to an HTML comment.

Admin Programs

Administrative programs are less consistent in how they lay out the page. For most Administrative programs, the page footer consists of only a TNG copyright statement, and the HTML that lays out the page isn't part of a template. Some administrative programs put a table inside a form element, and the form element is the wrapper for the content area. Other administrative programs use a <div&rt; or a table, or a table cell. So you'll just have to look at a particular program and try to figure it out.

In the example started above, using the program admin_dataimport.php, each of the mods that modifies admin_dataimport.php uses the following target location:

%location:%
</td>
</tr>
</table>
%end:%
%insert:before%
<?php
include_once ('showmodnames.php'); ### Gedcom Import Mediatype Location 5: Output the names of mods that affect this program 
?>
%end:%

Note that we had to switch into PHP mode and then back out because the PHP file was in HTML Mode before and after the PHP code we needed to insert.

Also note that admin_dataimport.php winds up with three copies of the include_once statement, like this:

<?php
include_once ("showmodnames.php"); ### Gedcom Import Monitor Location 5: Output the names of mods that affect this program
?>
<?php
include_once ('showmodnames.php'); ### Gedcom Import Mediatype Location 5: Output the names of mods that affect this program 
?>
<?php
include_once ("showmodnames.php"); ### Gedcom Import Purge Location 6: Output the names of mods that affect this program
?>

But that's unavoidable and OK, since the include_once statement will only work once.

The CSS Code

This mod places the following CSS code in css/genstyle.css

/* This style is for a hyperlink that looks like a button */
#modnamebtn {border: 1px solid gray; text-decoration:none;
   padding:1px 2px 0 2px;
	-moz-border-radius: 4px;
	-webkit-border-radius: 4px;
	border-radius: 4px;
}
/* Use a larger font outside of the hyperlinks so commas between the hyperlinks don't look like periods. */
#modnamelist {font-size:12px;}
/* For the mod name/wiki hyperlinks */
#modnamelist a {
	font-size:11px;
	text-decoration:underline;
	white-space:nowrap;}

Mod Change History

Mod Version TNG Versions Date Note
10.0.0.3 10.0-11.0.1 18 Jul 2016 The "Show Mods" button does not print, since it is superfluous when printed. Also tweaked the style classes added to genstyle.css so that I could use them in other mods.
10.0.0.2a 10.0-11.0 20 Mar 2016 Tested in TNGv11 and fixed a couple of glitches - It wouldn't display, hide, and then display the mod names again, and there was a possible inaccurate warning message.
10.0.0.2 10.0-10.1.3 13 Feb 2016 Completely rewritten to use an include file (and include_once), to write the mod names to an HTML comment in most case, and to require the installation of Show Mod Names
10.0.0.1 10.0-10.1.3 6 Dec 2015 New mod.

Sites using this mod

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

URL User Note Mod-Version TNG-Version User-language
Robin Richmond's Genealogy Database Robin Richmond Mod developer 10.0.0.2 10.1.3 English
MOTYER Family Genealogy John Mark Motyer Public site see here see here EN, DE, RU
R G Strong Family Genealogy Russell Strong Public site 10.0.0.2b 11.0.0 EN, DE, FR, NL