Mod Manager - Interpreting Status
This page pertains to TNG 10.1 and above of the Mod Manager. See Mod Manager - Interpreting Status - prior to TNG 10.1 for previous versions of this page. |
|
The status of a Mod is determined by looking at the status of each change that the mod makes. See Mod Manager - Interpreting Status - prior to TNG 10.1 for previous versions of this page.
Determining Target Location status
The Mod Manager examines the mods folder and reads every mod config file (that is, files with the filename extension .cfg) that it finds. It performs the following analysis of each config file to assign status values to the target locations and files:
- It reads the directives in the file header
- Some syntax errors will cause a mod "Cannot Install" error.
- It examines each target file.
- It examines any mod parameters for that target file, looking for syntax error.
- It examines each change location for that target file. Each change location must have search text, an insertion/replacement directive, and insertion text.
- If the insertion text is found in the target file, the location is "Installed".
- Otherwise, if the search text is not found in the target file, the location is "Not Installed".
- If neither text string is found, the location is marked as "Bad Target".
- It examines each file to be created by the mod.
- If the destination file already exists, the file is marked as "Installed".
- If the destination file doesn't exist, but the source file does, the file is marked as "Not Installed"
- If the source file doesn't exist, the file is marked as is "File Missing".
(This is a somewhat simplified approximation of the algorithm that Mod Manager actually performs, but it should paint a reasonable picture.)
Here's a screenshot of the Mod Manager showing 9 mods, and all all possible Mod statuses. Fortunately, though many sites will have more than 9 Mods, site administrators will rarely have to deal with more than one or two mods with the status "Partially Installed" or "cannot install" at a time. Most mods will be cleanly "Installed or "OK to Install".
NOTE: You must click on the right arrow in the Status column to expand the status cell to find out the real error message that is causing the mod to show as Partially Installed or Cannot Install status. When reporting problems with a mod on the TNG Community Forum, you need to provide the error message that causes the Cannot Install status
Mod Status Values
1. Ok to Install
If all target locations and file operations have the status "Not installed", then the mod can be installed or deleted.
For example, let's look at #12, Admin Places Date. The message "Requires database setup" in the "Status" column comes from a %note tag in the mod's .cfg file. To see more information about the mod, or to take action (e.g. Install, Uninstall) on it, you must open the Status cell by clicking on it. In the expanded status cell, shown in the screen clip below, you can see
- The mod status and note that were visible in the minimized Status cell,
- Three action buttons:
- "Install",
- "Delete", which deletes the mod .cfg file and subfolder from the TNG site. This operation is safe because, since the mod is uninstalled, no TNG programs have been affected by it.
- "Detail", which shows or hides the status of each of the target locations and copy commands in the mod's .cfg file. You can see the beginning that detailed list at the bottom of the screen clip.
- The author's name, with a hyperlink to a page about the author (usually the author's page on the TNG Wiki). The author's name is displayed only if there is an %author tag in the heading of the mod's .cfg file.
- A description of the mod. This description can (and in this case, does) include HTML tags, and can be as detailed as the author wants it to be.
- The box that mentions the Creation Date field, and that provides a link to the program that sets up the database field, is part of the description.
- A legend describing the three flags that can be used with %copyfile and %target commands. (Admittedly, this legend is kind of pointless when none of these flag are used within a mod.)
- A list of all of the mod's target locations and %copyfile commands, and their statuses.
- In TNG 12, Mod Manager displays the status details by default, and the "Detail" button hides the details. But in a mod that is "OK to Install", none of the target locations or copy commands have error states, so there isn't much point displaying the list. So, in a future version of TNG, the details of an "OK to Install" mod may be hidden first, and then displayed by the "Detail" button.
- The white text-on-dark footer gives information about
- The total number of target locations (across all of the target files)
- The number of files that will be copied from the mods folder to TNG working folders when the mod is installed.
- The number of files that are defined within the config file, and will be created when the mod is installed.
- The number of new folders that will be created by %mkdir commands in the .cfg file, and
- The number of errors, which has to be zero in a mod with the status "OK to Install"
What to do with this status - pretty simple - either install the mod, or get rid of it.
2. Installed
If all of the mod's target locations and file operations have the status "installed", then the mod is completely installed, and about all that we can do to it is to Uninstall it. For example, let's look at Admin Cemeteries Search. When you click on the status table cell to open it, you'll see similar information to that shown for the "OK to Install" mod, that is,
- Action buttons - in this case, only two buttons, "Install" and "Detail".
- As before, the author's name, with a hyperlink to a page about the author.
- A description of the mod. This mod's description contains HTML, and is so long that much of it has been clipped out of the image.
- The same legend describing the command flags.
- A list of all of the mod's target locations and %copyfile commands, and their statuses.
when none of these flag are used within a mod.)
- The same footer as in the "OK to Install" mod.
What to do with this status - pretty simple - All you can really do is uninstall the mod.
Note: If the mod is a previous version of the mod that you forgot to uninstall before installing the current version, you can enable the Allow Delete of individually Installed Mods option to Delete the mod without having to uninstall the current version of the mod in order to delete the previous version. You should revert the Allow Delete of individually Installed Mods back to No after deleting the previous version of the mod. See Mod Manager Delete for additional details.
3. Installed (Options)
If a fully-installed mod has mod parameters, then [Options] is shown after the Installed status and in addition to the Uninstall button, an Edit button is displayed.
For example, let's look at mod 18 on the list above - Living Color Mod. The [Options] after the Installed in the status table cell and the Edit' button shown on expansion indicate that there are mod parameters. Also note that the mod description for this particular mod happens to include a list of files that this mod modifies. That information is required in the Wiki article but no longer needed in the descriptions since with TNG 10.1 and after, the Mod List Tab's "Files" column displays that information when you hover over the + plus sign.
What to do with this status - pretty simple - either uninstall the mod, or edit the mod options.
See Mod Manager - Edit Parameters for details on editing the mod parameters.
4. Partially Installed
If at least one underlying target location or file operation has the status "installed" and at least one other underlying target location or file operation has the status "Not Installed", then the mod is Partially Installed, and the Clean Up button is provided. A Clean up operation will attempt to remove any inserted or replaced code, restore the original code, and remove any created or copied files.
"Partially Installed" is an error condition, but often a temporary one that can be dealt with easily. A very common cause of a "Partially Installed" status is when a mod is being updated to a new version, and both the old and the new version are present in the mod list at the same time. For example, look at mods 6 and 7 in the list at the top of this page. The mod name Burials-More Details appears twice; once as version 9.2.0.7 and once as version 10.1.0.8. The old version has been uninstalled, and the new version has been installed. As a result of the installation of the new version, some of the target locations in the old version are showing as Installed, since they exist in both versions of the mod. I have opened the status window of burials_more_details_v9.2.0.7.cfg to illustrate. Note that all of the target locations in the mod are listed along with their statuses. Some of the statuses are Installed and some are Not Installed
What to do with this status What action your take depends on the reason the mod is shown as partially installed:
- In the case where it is a previous version of the same mod, it's pretty simple; just Delete the old mod.
- Note: this two-version-of-a-mod temporary-Partially-Installed situation is almost identical to similar situations that occur if two versions of a mod are created for slightly different circumstances and both happen be present on the same TNG site.
- Partially Installed is also shown after a TNG upgrade where you did not remove your mods prior to upgrade. In this case the action required is Clean Up rather than Delete which most often will then allow the mod to be installed. If the mod status changes to Cannot Install instead of OK to Install after a Clean Up, then the mod developer needs to provide a new version of the mod since the code location has changed.
5. Cannot Install
If at least one underlying target location has a "Bad Target" error, then the mod cannot be installed or uninstalled. The Delete button will be displayed, as the mod is considered to be completely uninstalled.
The "Cannot Install" status is an error condition that is usually caused by
- files that were not copied to the TNG mods subfolder associated with the mod but instead were copied to the TNG mods folder or the subfolder was not copied (FTPed) at all
- the location targeted for the change has been updated to use different code in the TNG module
- the location was updated by another mod thus causing a conflict between two mods - that is, when two mods that may be trying to accomplish completely different things target the same piece of HTML or PHP code and do different things with it. There is not necessarily a simple way to fix a "Bad Target" error within a mod.
For example, consider Mod 12 from the Mod list at the top of this article - Compact Person Media. When I expand the Status table cell for that mod, you can see all of that target location (and file) statuses for the mod. Only one location has the status Bad Target. The mod status information does tell you which Target File has the bad target, but there is absolutely no indication of what caused the Bad Target in Compact Person Media.
Note that in the following screen capture the Bad Target is indicated as a conflict, when in reality the Bad Target is caused by a code change in TNG 10.1, so a new version of the mod is required from the mod developer.
What to do with this status - The action to take depends on the reason for the Bad Target:
- If it is caused by a TNG code change, then the mod must be updated by the mod developer
- If it is caused by a mod conflict, the conflict must be isolated and resolved. Both mods might require updating to resolve the conflict.
- If the Cannot Installed reason is that Files are missing, then you may need to ensure that the folder associated with the mod was copied to the TNG mods folder.
Well, if we see the conflict and decide that it's too much trouble to resolve the conflict, we could just delete Compact Person Media. But, assuming that you downloaded Compact Person Media because it does something you want on your site, you'll need to address the conflict.
Theoretically, when you encounter a Bad Target error in a mod, you might be able to uninstall the last mod you installed, under the assumption that its installation caused the conflict. However, the Mod Manager does not remember the status of each mod - much less the status of each target location, so it is not easy to tell whether the mod you just installed has caused any conflicts. By the time you notice that a "Cannot Install" status exists for a particular mod, you often don't know which mod's installation caused that error.
Typically, when TNG Administrators get Bad Target errors and cannot readily figure out which mod is in conflict, they do a screen-shot of the Mod Manager status cell, showing all of the mod's locations, and send that screen shot to the mod's author, using contact information provided in the mod's Wiki page.
The "Mod Analyzer" (a fourth tab within the Mod Manager that is disabled by default, but that can be enabled through a Mod Option) can help tremendously with this situation. When you select the Analyzer tab, the Analyzer displays a list of TNG files that are modified by any of your mods. This list could be anywhere from say, 20 to well over 100 files. As noted above, the mod status does tell you which file (or files) the conflict occurred in. So if you select that file (in this case, personlib.php) in the Analyzer's file list, Analyzer will tell you exactly which mods affect that file. It doesn't tell you which mods affect that specific file location and, thus, it doesn't tell you exactly which mod is in conflict, but it gets you a whole lot closer. When you see which mods might be in conflict, you can more readily decide whether to a) just give up on one or the other of the mods, or b) contact one or both mod authors to see if they can update their mod to remove the conflict.
Related Links
Mod Manager
- Overview
- Why Use It ?
- Installing Config Files
- Batch Updates
- Interpreting Status
- Editing Parameters
- Deleting Mods
Mod Manager Controls
For Mod Developers
- Mod Guidelines
- Mod Manager Syntax
- Creating Config Files
- Config File Creation Example
- Avoiding Mod Conflicts
- Using the TNG File Analyzer
- Mod_Manager_Enhancements_TNG_v12
Technical
Developer Tools
Example Mods