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 with 23 mods, and all possible Mod statuses (for illustration). Fortunately, though many sites will have more than 23 Mods, site administrators will rarely have to deal with more and 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".
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, and the the Install and Delete buttons are displayed when the status cell is expanded. Note that (unless certain mod options are set), only mods that are completely uninstalled can be deleted.
For example, let's look at the 2nd mod on the list - Admin Media Search. To see the details of the mod target file status or to take action on a mod, you must open the mod's Status table cell by clicking on it. As should be true of all mods, the mod header, which is shown in the opened status cell, contains the mod name and file name, a brief description, a reference to the mod Author, and a link to the mod's Wiki article. The white text-on-dark background block in the status table cell gives information about
- The code modifications (i.e. the "target locations"), though not the target files,
- The files to be copied from a /mods folder subfolder to another location,
- The file to be copied from inside the config file to another location, and
- The errors.
The details of the target location statuses are not shown because the status "OK to Install'" can only exist if all of the target location and file statuses are not installed.
What to do with this status - pretty simple - either install the mod, or delete it.
If all of the mod's target locations and file operations have the status "installed", then the mod is completely installed, and the Uninstall action button is displayed.
For example, let's look at the 1st mod on the list - Admin Media Predefined 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, the mod name and filename, a brief description, a reference to the mod Author, and a link to the mod's Wiki article. As with the mod with status "OK to Install", the details of the target location status are not shown. In this case, that is because all of the target locations and files a Installed.
What to do with this status - pretty simple - All you can 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 188.8.131.52 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_v184.108.40.206.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.
- 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