Mod Manager Enhancements TNG v12

From TNG_Wiki
Jump to: navigation, search
TNG version: 12.0.0

The following Mod Manager enhancements were made in TNG v12:

  • new options
    • renamed Analyzer tab to Analyze TNG Files
    • added a View Parse Table tab
    • added a Recommended Updates tab
    • added delete folder capability when deleting a mod
  • added Select to the filter pull down list
  • added a Delete button to the Select filter list
  • added new processing tags
  • added conditional processing tags
  • added new processing flags
  • added support for $modspath and $extspath in %description:
  • tightened syntax and better error detection


New Options

New options were added to the Mod Manager for TNG v12 that require that you update the mmconfig.php file. The first time you access the Mod Manager you will be prompted to update the Mod Manager Options by opening the Options tab and doing a Save.

Analyze TNG Files

The Analyzer tab was renamed to Analyze TNG Files.

View Parser Table

When a mod is having a problem, the first thing we need is to look at the parser table to see if mod tags are being handled correctly.

Mod Manager in TNG v12 provides a simple utility that is invoked from View Parser Table tab to analyze how the Mod Manager is parsing the mod cfg file. You can select a mod from the list and view the parser table results.

Note that you must enable the Show Other Developer tools in the Options screen to display the View Parser tab.
Note that the parser table for an individual mod can be displayed by clicking the Mod Name in the Mod List, if the option is enabled.
Note that mod developers who do not follow the Mod Guidelines of using all lower cases for the cfg file name may make it a challenge to find the correct cfg file since it does not match the name in the Mod List.

Delete Folder

The updated Mod Manager will now delete the folder associated with a mod when deleting the mod

Note that you must enable the Allow Delete support folder when mod is deleted in the Options, Other section for the folders to be deleted.

For example, the Delete | Cousin_marriages | File deleted | Admin User will show the following in the View Log

  • Deleting cousin_marriages_11.0.0.0q.cfg
  • Folder cousin_marriages Deleted
  • cousin_marriages_11.0.0.0q.cfg File deleted

To avoid problems, mods should use a folder name that ties the folder to a given mod version as indicated in the Mod Guidelines


Select Filter

The Select filter allows a user to select only specific mods to be returned in the Mod List. The Lock check box is automatically checked when you click the Go button to go to the Select list from which you select the mods you want to display in the list.

File:Mod Manager 12 select mods.png

Returns a screen with only the selected mods that you want to work on

File:Mod Manager 12 selected mods.png

While the implementation is different, this is a good replacement for the Mod Manager Latest mod.

Delete Button on Select List

The Select filter list can be used to Delete mods in all status provided that you have updated the Options in the Other section to Yes for

  • Allow Delete Selected of Partially Installed Mods
  • Allow Delete of individually Installed Mods

The Delete capability on the Select filter list provides the developers a handy way to clean up their developer sandbox where they might have multiple versions of the same mod installed.
TNG Users may not want to enable the above options. If you also want to delete the support folder associated with the mod, you also need to enable

  • Allow Delete support folder when mod is deleted
Delete on Select screen with confirmation

New Tags

note tag

The %note: tag can be used to define messages that are displayed in the un-expanded Status column of the Mod Manager list. It is typically used to alert the user to mods that have special characteristics or that have conflicts and other relationship with other mods.
The %note: tag can be in any place in the mod .cfg file, for example above the %location:% that causes a conflict. It can also be used with the %private: tag

The Select Filter screen shots above happens to show such a message, and more specific examples follow.

  • A simple message indicating that the mod coordinates with another mod. Details of that relationship would be found in the expanded Mod Manager List status cell, or in the mods's Wiki article
%note:Coordinates with the Admin Places Search mod%
which generates the message shown on line 6 in this screen clip:
Mod Manager 12 note1.jpg
  • Another simple message indicating the the mod changes the database and has a database setup program.
%note:DB Setup%
This message appears in the un-expanded status cell, and is still visible at the top of the cell when the status cell is expanded, as shown here. Note that the mod description displayed in the expanded cell provides more information about the mod's database setup.
Mod Manager 12 note0.jpg
You can click on the [Expand] link on the right to display the hidden section or [Collapse] to hide the section.

Styling can be applied to %note tag messages, as shown in the following examples, which show how you might convert some of the tags that were defined in the TNGv11 Mod Manager Note Tags mod.

  • ConflictsWith message - Used when the mod is known to conflict in some way with another mod.
%note: <strong><span style='color:red;'>ConflictsWith:</span> Mobile Site Enhancements <span style='color:blue;'>which must be installed first</span></strong> %
which generates the Status column message shown in line 13 here:
File:Mod Manager 12 conflict note.png
  • DependsOn message - when a mod depends on another for certain functionality to work.
%note: This mod will suppress the Geocode globe if placelevel is == "-1" (Do not geocode). 
<strong><font color=red>DependsOn</font> the Admin Places Geocode</strong> to set the Do not geocode%
which generates the message in line 13 in this screenclip:
File:Mod Manager 12 dependson note.png
  • PreReqs message - For other mods that must be installed before this mod in order for this mod the work.
%note: <strong><span style="color: red">PreReqs</style></strong> You <strong>MUST</strong> have the Ancestors Map Mod <strong>AND</strong> the Google maps - Add 4 more Place Levels Mod installed before installing this mod.%
which generates
PreReqs You MUST have the Ancestors Map Mod AND the Google maps - Add 4 more Place Levels Mod installed before installing this Mod.
File:Mod Manager 12 prereq note.png

While the implementation is slightly different, the %note: tag replaces most of the tags that were implemented by the Mod Manager Note Tags mod in TNGv11.

author tag

The %author: tag is used to provide information about the author of the mod. It should be used to replace the Mod Developer is string previously used in the %description section. It has has two parameters:

  • The author's name, and
  • An optional URL, which is used to turn the author's name into a hyperlink. The URL can refer to the author's TNG Wiki profile page, or any other page that provides information about the author's mods.
%author:Robin Richmond:https://tng.lythgoes.net/wiki/index.php?title=User:Robinrichm%
The author's name is shown in the 'expanded Mod Manager List status cell, just below the action buttons:
Mod Manager 12 note0.jpg

If more than one person worked on a mod, then you can

  • Display each name as a hyperlink by specifying a separate %author: tag for each author, or
  • List as many names as you want as the first parameter of a single %author: tag, though with at most one URL.

The many different representations of the 'Author' or 'Mod Developer' in the %description section of the mod's .cfg file can all be replaced by the the %author: tag. The TNGv12 %author: is only slightly different from the !@#author: tag that was implemented by the Mod Manager Note Tags mod in TNGv11.

mkdir tag

The %mkdir tag can be used to create new directories (folders) needed for the mod. If you use copyfile2 to copy files to a directory that you just created, you should use the new 'Provisional flag' (^) so that the %copyfile2 commands that follow the %mkdir tag be flagged with a 'Cannot Install' error. (See the example in the Provisional flag section below.

private tag

The %private: tag is used to flag private mods, and optionally to display a message in the un-expanded status cell, if one is provided. A "private" mod is simply a mod that is not intended to be published on the TNG Wiki server. The %private: can be specified with an argument (message) or not. It can also be combined with a %note: tag, in which case the note is displayed after the Private Mod. In this example, the %private: tag contains a formatted message that describes a private modification to a published mod.

%private: my changes to Graham Chamberlain's mod applies after topmenu split after installing <strong>Z-9 Template 4 - Accordion Menu</strong>%

which generates

File:Mod Manager 12 private note.png

If you are content with just seeing "Private Mod" in the status cell, you can simply enter the tag with no argument, like this:

%private:%

All three of the mods in this screen clip have identical %private: tags, and the mod on line 64 also has the tag "%note:incomplete%" (except that incomplete now shows after the word Private Mod).

Mm12 enhancements-private.jpg

vinsert tag

Note that since TNG v12 moved the Template Settings to the tng_templates table, the usefulness of this tag is now questionable.

The %vinsert: tag can be used when inserting template variables in the templateconfig.php file that can be dynamically changed by the user in the Admin > Setup > Template Settings for the template. When changes were made previously the mod showed as Partically installed and the template variables section showed as Not Installed since the lines no longer matched.

The new %vinsert: is a block-type optag that allows inserting variables into config files whose values TNG or other parties may rearrange or modify independently of the Mod Manager. It is similar to a %location% tag, but it only checks the insertion point for the variable names and not the values

When installed, modlister only checks for the existence of the variables in the target file and ignores their values.

When uninstalled, modremover deletes the variables and their values, whatever they are at that time.

Conditional Processing Tags

The Mod Manager in TNG v12 adds some conditional processing tags

  • to check on the existence of a file
  • to check on whether a text string exists
  • to check the TNG version
  • to exit the test a goto tag is provided

Along with the %note: that allows you to warn users of conflicts or install dependencies, the conditional processing tags provide the tools to possibly resolve the conflicts by taking different paths in the mod cfg file when installing or verifying that code is installed. The following screen capture shows both situations where the %note tag is used to indicate an install sequence and conditional tags used to resolve the conflict and install sequence.

Note that by using the %textexists tag the conflict was resolved in the Mobile Site Enhancements mod and the message in the conflicting Add DNA Test Results mod updated to show what version of the Mobile Site Enhancements mod must be installed.

Allows Conflict Resolution

fileexists tag

The %fileexists:filename:label% tag is a conditional tag (essentially an If/GoTo statement) that can bypass other tags, such as tags that would try to create or copy a file that may already exist. With a %fileexists tag:

  1. The first argument must be a filename using a relative path, just like a %target or %copyfile command,
  2. The second argument must be a label, using the new %label tag, described below, and
  3. The newfile or copyfile tags between the %fileexists tag and the %label tag must use the new 'protect' flag, the tilde (~), described below.


The following is how the Census Plus International mod implemented the new %fileexist: tag to preserve the user's settings across uninstall and install of the new version of the mod.

%fileexists:$extspath/cp_settings.inc:skipit%
%newfile:~$extspath/cp_settings.inc%

...file contents...
%fileend:%
%label:skipit%

Mod Manager processing works as follows

  • if the file does not exist, the Mod Manager uses the %newfile and %filend tags to create it.
  • if the file exists, the Mod Manager goes to the %label:skipit% and bypasses creating the file.
  • when uninstalling the mod, the ~ (tilde) in the %newfile directive prevents the file from being deleted. The protect flag by not deleting the file on an uninstall or clean up, thus preserves the mod settings to be used when the mod is installed again.

The Parser Table entry will display the following information when evaluating the %fileexists: conditional

Mod Manager 12 fileexists.png

textexists tag

The %textexists:label% tag is a conditional tag (essentially an If/GoTo statement) that can be used to test whether the code has been modified so that two or more paths could be taken and the conflict between two mods can be resolved and not show a Partial Installed status for the conflict area With a %textexists: tag

  1. The first argument must be a label, using the new %label tag, described below
  2. The %textexists: tag must also follow a %target: tag, that is be within a %target:script% section

The %textexists tag allows you to test for two or more different versions of a location. That is be done by daisy chaining two or more %textexists tags. In other words, if first version of location does not exist, test for the second version; if the second versions does not exist, try to install over the TNG factory version. If that does not exist you will get a bad location error (the line number will show you the bad location text in the mod config file). Pseudo code it would look like this:

  • test for version 1 and goto processing label-1 if it exists
  • test for version 2 and goto processing label-2 if it exists
  • try to install default location (over TNG factory location)
You can click on the [Expand] link on the right to display the hidden section or [Collapse] to hide the section.

The following is an example on how the code was changed in the Mobile Site Enhancements mod to resolve the Partial Install - Bad Target conflict when the Add DNA Test Results mod is installed. Notice that line 12 and 28 show a note that was added to the %location: to indicate what path is being taken by the Mod Manager when installing the mod

 1 	/****  Start of conditional logic to determine if conflicting mod is installed or not
 2 
 3 %textexists:DNA-test_installed%
 4 			$persontext .= "<td valign=\"top\" class=\"fieldnameback fieldname\" rowspan=\"$num_tests\">{$admtext['dna_tests']}$toggleicon</td>\n";
 5 %end:%
 6 
 7 %textexists:DNA-test_notinstalled%
 8 			$persontext .= "<td valign=\"top\" class=\"fieldnameback fieldname\" rowspan=\"$num_tests\">{$admtext['dna_tests']}&nbsp;</td>\n";
 9 %end:%
10 
11 %label:DNA-test_notinstalled%
12 %location: <span style="background-color:yellow;color:black">DNA Test Results mod not installed condition</strong></span>%
13 			$persontext .= "<col class=\"labelcol\"/><col style=\"width:{$datewidth}px\"/><col />\n";
14 
15 			$persontext .= "<tr>\n";
16 			$persontext .= "<td valign=\"top\" class=\"fieldnameback fieldname\" rowspan=\"$num_tests\">{$admtext['dna_tests']}&nbsp;</td>\n";
17 %end:%
18 %replace:%
19 			$persontext .= "<col class=\"labelcol\"/><col class=\"eventdatecol\"/><col />\n";
20 
21 			$persontext .= "<tr>\n";
22 			$persontext .= "<td valign=\"top\" class=\"fieldnameback fieldname\" rowspan=\"$num_tests\">{$admtext['dna_tests']}&nbsp;</td>\n";
23 %end:%
24 %goto:continue%
25 
26 //  Add DNA Test Results installed
27 %label:DNA-test_installed%
28 %location: <span style="background-color:yellow;color:black">Add DNA Test Results mod installed condition</strong></span>%
29 			$persontext .= "<col class=\"labelcol\"/><col style=\"width:{$datewidth}px\"/><col class=\"takenbycol\"/><col class=\"haplogroupcol\"/><col />\n";
30 
31 			$persontext .= "<tr>\n";
32 			$persontext .= "<td valign=\"top\" class=\"fieldnameback fieldname\" rowspan=\"$num_tests\">{$admtext['dna_tests']}$toggleicon</td>\n";
33 %end:%
34 %replace:%
35 			$persontext .= "<col class=\"labelcol\"/><col class=\"eventdatecol\"/><col class=\"takenbycol\"/><col class=\"haplogroupcol\"/><col />\n";
36 
37 			$persontext .= "<tr>\n";
38 			$persontext .= "<td valign=\"top\" class=\"fieldnameback fieldname\" rowspan=\"$num_tests\">{$admtext['dna_tests']}$toggleicon</td>\n";
39 %end:%
40 
41 	/****  End of conditional logic
42 %label:continue%
43 ...

The Parser Table will display the following when evaluating the %textexists conditional

Mod Manager 12 textexists.png

tngversion tag

The %tngversion: tag allows checking for a TNG version that falls between a start and end range of versions specified. If the user's version of TNG falls with the range, the conditional is true and processing jumps to the label.

%tngversion:range_start:range_end:label%

The %tngversion: tag has 3 arguments:

  • the first TNG version to which the code applies
  • the last TNG version to which the code applies
  • the goto label for the Mod Manager processing

The range of version numbers includes both the low and high numbers provided. Only digits and decimal points are allowed for the range. Decimal points are removed and the number is padded with trailing zeros to four places for comparison purposes. That makes the examples below possible.

Examples

  •  %tngversion:1100:1111:skip_error%
  •  %tngversion:11.0.0:11.1.1:skip_error%
  •  %tngversion:11:12:skip_error% (1100 to 1200)
  •  %tngversion:10.2.0:11.1:skip_error% (1020 to 1110)

The next tag, where processing continues if the user's TNG version is outside the provided range, might be/could be: %description:This mod will not work with your version of TNG. Please goto [url for TNGWiki page] to download the correct version of the mod.% // This will be the second %description tag in the mod configuration file and it will override the first one in the listing. If the mod falls within the correct range, process skips this and proceeds to normal processing.

Of course there can be other reasons for testing the TNG version, perhaps to detect the correct target text.

You can click on the [Expand] link on the right to display the hidden section or [Collapse] to hide the section.

The following is an example on how the code was changed in the Citation Master mod to support more than one TNG version. Notice that the following example uses the note on the %location: tag in lines 9 and 32 to indicate which path the Mod Manager will take when processing this mod

 1 	/* TNG version condition logic starts here
 2 
 3 %tngversion:1110:1111:Use_TNG11.1.0%
 4 %tngversion:1112:12:Use_TNG11.1.2%
 5 %description: This version of TNG may not be supported by this mod%
 6 
 7 %label:Use_TNG11.1.0%
 8 
 9 %location: <span style="background-color:yellow;color:black">TNG 11.1.0-11.1.1 version </strong></span>%
10 if( $foffset ) {
11 	$foffsetstr = "$foffset, ";
12 	$newfoffset = $foffset + 1;
13 }
14 else {
15 	$foffsetstr = "";
16 	$newfoffset = "";
17 }
18 %end:%
19 %insert:after%
20 // BEGIN: Citation Master
21 // get a formatted source and insert it as the 'Preview' field
22 $pretty = citem_getFormattedSource($sourceID);
23 $sourcetext .= showEvent( array( "text"=>"Preview", "fact"=>$pretty ) );
24 // END: Citation Master
25 
26 %end:%
27 
28 %goto:continue%
29 
30 %label:Use_TNG11.1.2%
31 
32 %location: <span style="background-color:yellow;color:black">TNG 11.1.2-12 version </strong></span>%
33 if( $foffset ) {
34 	$foffsetstr = "$foffset, ";
35 	$newfoffset = $foffset + 1;
36 }
37 else {
38 	$foffsetstr = "";
39 	$newfoffset = 0;
40 }
41 %end:%
42 %insert:after%
43 // BEGIN: Citation Master
44 // get a formatted source and insert it as the 'Preview' field
45 $pretty = citem_getFormattedSource($sourceID);
46 $sourcetext .= showEvent( array( "text"=>"Preview", "fact"=>$pretty ) );
47 // END: Citation Master
48 
49 %end:%
50 
51 %label:continue%
52 ...

The Parser Table will display the following when evaluating the %tngversion conditional

Mod Manager 12 tngversion.png

label tag

%label:xxx% requires a label as an argument, and is used for the goto destination on the %fileexists: or %tngversion conditional tags.

goto tag

%goto:label% requires a label as an argument, and is used skip over sections of code when using the %textexists: or %tngversion conditional tags to resolve conflicts between mods.

New Flags

Mod Manager 12 has new one-character flags that must be placed immediately after the first colon in certain Mod Manager tags:

  • optional
  • provisional
  • protected
Mod Manager 12 flags legend.png

Optional flag

In previous versions of the Mod Manager, the optional flag (@) could be used on %copyfile or %copyfile2 tags, and now can be used on %target tags.

@ - optional. MM will bypass missing components and install the mod without them.

It can be added to %target: in lieu of placing a %fileoptional:% tag immediately below a %target tag.
//Skip this entire target section if the Spanish help file does not exist
%target:@languages/Spanish/places_help.php
%location:%
si no existen otros lugares.
%insert:after%
hay mucho más que decir..
%end:%
...
//Skip this entire target section if the Spanish UTF help file does not exist
%target:@languages/Swedish/places_help.php
...

Provisional flag

^ - provisional.

This flag is useful in mods that create a directory (using the new %mkdir tag), and then uses %copyfile2 tags copy files to that new directory.
  • When Mod Manager analyzes the mod, this flag prevents Mod Manager from generating a 'Cannot Install' message that would otherwise be generated because the folder that will be installed is missing
  • During installation, if the folder is still missing, the %copyfile2 commands will generate an error.
The provisional flag essentially asserts that a directory will exist when a %copyfile2 command is executed during installation of the mod.
This example, for the Textplus Charts mod, copies images used by a help file into a new folder below the English language folder:
//Copy a help file to the language folder
%copyfile2:textplus_charts_v12.0.0.14/textplus_help.php:languages/English/textplus_help.php
//Create a subfolder for image files
%mkdir:languages/English/textplus%
//Copy the image files to the new subfolder 
//Note the 'provisional' flag, the caret (^), that prevents the %copyfile2 commands from 
//generating an error when the mod is being analyzed before installation.
%copyfile2:^textplus_charts_v10.1.0.13/English/descend1.png:languages/English/textplus/descend1.png%
%copyfile2:^textplus_charts_v10.1.0.13/English/pedigree1.png:languages/English/textplus/descend1.png%
etc.

Protected flag

~ (the tilde) is used to protect a file, that is to prevent the Mod Manager from removing the file when uninstalling the mod.

  • The protected flag can be used to preserve configuration settings used by the mod like the Census Plus International mod as shown in the %fileexist section above so the user's preferences that are different from what is provided as a default by the mod can be re-used when a new version of the mod is installed.
Note that if you use the %fileeixst directive in this manner and decide not to use the mod that protects a file on uninstall, you will need to manually delete the file.
  • This new flag can be used with the new %fileexists tag to allow multiple mods to share a module that any of them can install.
If the file has already been installed by one mod, the %fileexists tag will cause Mod Manager to skip the relevant %copyfile or %newfile commands during a subsequent installation of a different mod. Then, when either mod is unnistalled, the ~ flag will prevent the file from being deleted, thus leaving it available to other mods that need it.
This flag does allow a file to remain installed after all mods that use it are uninstalled, but the presence of an unneeded file is far preferable to the absence of a needed file.
Note that if you use the %fileeixst directive in this manner and decide not to use the mods that share a file, you will need to manually delete the file.
%fileexists:$extspath/mod_settings.inc:skipit%
//The file does not exist, so copy it from the mod's subfolder.
%copyfile2:~mymod_v12.0.0.1/mod_settings.inc:$extspath/mod_settings.inc%
//where the ~ (tilde) in the %copyfile command is the 'protected' directive.
%label:skipit%

$modspath and $extspath

TNG version: 12.0.0

TNG v12 adds the capability to use $modspath and $extspath within the %description section of the mod. This allows the HTML code in the mod's %description block to invoke scripts that are stored the 'logical' mods and extensions folders even on sites where the TNG administrator has renamed those folders.

The following are examples on how to provide hyperlinks or action buttons that execute files from the mods or extensions folders:

  • A highlighted hyperlink:
<p style="font-weight:bold; color:red; border:thin solid red;padding:.5em;">
This mod adds several fields to the Branches table. <em>After Installation</em>, 
<a href="extspath/branch_timestamps_dbsetup.php" target="_blank">Set up or Remove the new database fields</a>.
</p>
<input class="button space" type="button" style="color:green;font-weight:bold" value="Run Checks" onclick="window.open('$modspath/bot-trap_v12005/bt_check.php','_blank');" /><br /><br />
<input class="button space" type="button" style="color:red;font-weight:bold" value="Delete the tables" onclick="window.open('$modspath/cousins_12.0.0.3/delete_table.php','_blank');" /><br />

This new capability allows the script to be run whether the mod is installed or not. This new capability might be handy to create or update needed tables. Of course the executed script might need to be updated to run from the mods/subfolder instead of the TNG root folder.


TNG version: 11.0.2

The $modspath and $extspath can be specified in the %target, %newfile and %copyfile2 in TNG v11.0l2 and after.

Error Detection

The Mod Manager now include better error detection and will return new error messages for

  • invalid actions
  • no access
  • does not change anything
  • folder not found

Invalid Actions

Invalid actions like using %insert:replace:% now returns Action Tag invalid error message

No Access

The Mod Manager now returns Unable to install this mod. Mod updates are required. Parameter line shows no access if the mod does not contain write access.

  • Mod manager needs access to write to mods that provide parameters. Mods with Parameters require that the mod cfg file be written back out by the Mod Manager and now return an error message if the mod cfg file is read only.
  • The error will also be returned if your mod .cfg file permission is 644 and the web server runs under a different user than the owner.

Does Not Change Anything

The Warning: Does not change anything in TNG! error status was added to show that mods using conditional processing did not modify any TNG files. In other words there are no files in the Affected List.

Mods folder not found

If the user renames the mods folder without updating the TNG Admin > Setup > General Settings > Paths and Folders, the Mod Manager will now return an error message.

Mod Manager 12 updated options.png