Mod Manager

From TNG_Wiki
Jump to navigation Jump to search
Ambox notice.png Starting with TNG V8 the Mod Manager is built into TNG. The information on this page pertains to the Mod Manager provided in TNG 10.1 and above. For previous information, see Mod_Manager_-_prior_to_TNG_10.1
TNG 10.1.0


Purpose of the Mod Manager

The TNG Mod Manager is intended to provide a more integrated way to install/remove and manage modifications (mods) to the TNG software package using config files that have been coded to work with the mod manager and are stored in the mods folder.

Mod Manager works strictly with text. Aside from its own rules for processing CFG files, MM is not aware of the syntax for other programming languages. It must depend on mod developers to keep their changes within the rules governing the programming language of the files they are enhancing. Since it works with text, MM can be used to modify PHP, HTML, CSS, JS, TXT or even CFG files. It can also be used to create or copy files from a mod support folder to the TNG root, language folders, or elsewhere.

Bear in mind, modifying a language file can be tricky for languages other than English. For example, a CFG file is capable of inserting new text into a German language support file; however there are two German files, one UTF-8 and one ANSI. The CFG itself will be one or the other format, usually ANSI. It will successfully insert text into the German ANSI file, but inserting that same text into a the German UTF-8 file will result in the file having a mix of ANSI and UTF-8, and even worse, the file will be saved in ANSI format, resulting in garbled text. One way around this is to create your own ANSI and UTF-8 support files and have the CFG copy them to the appropriate language folders. Then incorporate them in your scripts along with the standard TNG language files at runtime.

TNG mods

A TNG mod is a package of files that implements a particular TNG modification. It consists of

  1. A configuration file, using the file name extension .cfg, contains instructions that the Mod Manager uses to modify TNG files, and
  2. Optionally, one or more files (which should all be in a subfolder) that are to be installed by the mod.

Mods are almost always packaged in a Zip archive, and made available through a page on the TNG Wiki. When the mod is downloaded and unzipped or extracted into the proper Mod folder, the Mod Manager will automatically find it. It takes just two clicks to install the Mod and just two clicks to uninstall it if needed. There may be instances where other changes need to be completed either before or after the installation of a Mod, so it is important to read the TNG Wiki article on a mod before trying to install it.

The Mod Manager Syntax articles shows authors of mods how to compose a script which incorporates their modifications into the TNG system.

Advantages

The Mod Manager has the following advantages:

  • automates the installation, removal, and management of TNG modifications
  • eliminates the need to manually track TNG mods by line number, since the changes are now contained in a config file
  • allows tracking stylesheet and configuration changes

Developer

The Mod Manager was originally developed by Brian McFadyen and updated by Sean Schwoere to work with the Joomla TNG Component.
The TNG V10.1 Mod Manager combines the Mod List and Batch Updates provided in TNG 10.0.3 and is intended to provide a more integrated way to install, remove and manage modifications to the TNG software package that have been coded to work with this manager. The Mod Manager is connected into the TNG Administrative page for easy access.

Enhancements Credits

Updates were made in TNG V9 by Bart Degryse, Linc Haymaker, and Ken Roy to prevent clean up attempts when the mod cannot be installed.

TNG version: 10.1.0

Several enhancements were made in TNG V10.1 by Rick Bisbee, Jeff Robison, Robin Richmond, and Ken Roy with extensive testing provided by Bryan Larson, Linc Haymaker, Martin Pannier, Roger Mitchell, Roger Moffat, Warren Gilbert, Graham Chamberlain and Wendel Voight.

TNG version: 12.0.0

Several enhancements were made in TNG V12 by Rick Bisbee with extensive testing by Graham Chamberlain, Warren Gilbert, Lincoln "Linc" Haymaker, Bill Herndon, Erik Hoppe, Ron Krzmarzick, Roger Moffat, Robin Richmond, Jeff Robison, Ken Roy with testing and translation by Mogens C. Fenger, Ron Krzmarzick, and Bernard Wortelboer

Requirements

Folders

TNG V10.1 and above provides three subfolders:

  • mods which are where you are expected to save the .cfg files you extract or unzip from the zip files provided on the TNG Wiki mod pages.
The mods folder provides the input .cfg files and related subfolders for mods that contain multiple files that are copied.
TNG version: 11.0.2

The mods folder can be renamed after TNG 11.0.2

  • extensions where some of the mod extensions that are installed by other Mod Manager config files will be created.
The extensions folder is an output folder used by the Mod Manager to write code snippets and other files installed by the Mod Manager. See the Add Files section in the Mod Guidelines article for examples.
TNG version: 11.0.2

The mods folder can be renamed after TNG 11.0.2

  • classes which contains the new Mod Manager object oriented classes.
In analyzing the original modmanager class, it became clear that it encompassed logically separate operations. In other words, installing a mod is different from removing or listing it. To simplify maintenance, we divided the modmanager class into four new classes -- modlister, modinstaller, modremover, and modeditor. Then we added a couple of library classes with common functions and data, similar to genlib.php or globallib.php in TNG. Where TNG 'includes' its libraries, the Mod Handler library classes are extended by the top level classes that use them. .


TNG version: 11.0.1

NOTE even though TNG provides a folder rename capability on the full install to rename the extensions directory, please do not rename this folder at this time. Several mods have hard-coded includes for their code snippets from the extensions folder.


TNG version: 12.0.0

The $modspath and $extspath can now be used in the %description section of the mod cfg file.

Custom Styles and Text

Note that some of the mod config files include changes to styles that are saved in mytngstyle and custom text that is saved in the languages/English/cust_text.php and languages/English-UTF8/cust_text.php.

The following are required for your mods to show an OK to install:

  • your cust_text.php files must have a php terminating statement which is the ?> since the mod config files typically specify that line for the verify location before which in needs to insert the code
  • your mytngstyle.css file must contain the TNG distributed lines (note that a line feed was inserted for readability in the text below)


/*your custom style goes in this file*/
/*if   you're overriding style blocks from genstyle.css, you only need to   include the attributes you're overriding, not the whole block*/

Mod List

The Mod List now combines the previous Mod List and Batch Updates that was added by Rick Bisbee in TNG 10.0.3 to provide the capability to execute the same action against multiple mods. The Description and extended status can be displayed by clicking the right arrow in the Status column. Hovering over the + plus sign will display the Affected Files list, that is the files modified, created, and copied by this mod.

Mod Handler list.png

Wiki

The Wiki column contains an icon if the mod developer has added the new %wikipage: tag to their mods. You can click on the W icon to display the TNG Wiki article for that mod in another tab or window.

Status

Only a single line status is displayed. You can click the right arrow or anywhere in the line to get the mod Description and the extended status and the action buttons applicable to that particular mod status:

  • OK to Install has an Install and Delete button
  • Partially Installed has a Clean Up button
  • Cannot Install has a Delete button
  • Installed has an Uninstall button
  • Installed with Options has an Uninstall and Edit Options button
TNG version: 12.0.0

TNG v12 displays the content of the %note: and %private: keyword note text to the status line.

TNG v12 added a Details button to the OK to Install and Installed status that works as a toggle to list the mod cfg file details.

Files

The Files (or Affected Files) column contains a plus sign that will display the Affected Files list as you hover over the + for the mod.

View Log

The View Log tab allows you to view the Mod Manager transaction log.

Mod Manager log.png

Options

The Mod Manager provides options that allow you to control its behavior. Two options were added that allow you to delete a previous version of a mod that you forgot to delete before installing the current version.

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

Both options are set to No since they normally should not be needed and should only be changed to Yes when you need to delete previous versions of mods from your system. The options are helpful to the mod developer when creating new versions of the mods.

Mod Manager delete options.png

Analyzer

The Analyzer tab is an optional tab that allows you to access the Mod Analyzer that was previously provided as part of the Mod Developer Tools

See Using the Mod Analyzer for additional information.

Mod Manager Status

For examples of the Mod Manager Status screens and how to interpret the various statuses, see Mod Manager - Interpreting Status

TNG version: 8.1.3
  • Clean Up required in TNG V8 that becomes Unable to Install in TNG V9
TNG version: 9.0
  • TNG V9 removes the Clean Up button for cases where a clean up will not work and issues the Unable to install this mod message which is proceeded by another message that provides the reason why the mod cannot be installed. See Unable to Install for additional details. This includes the following cases:
    • Missing Target keyword
    • Missing Target file
    • Bad Target
    • Missing source copy file
  • TNG 10.0.3 removes the Delete button from Installed mods
TNG version: 10.0.3
This action was taken to prevent users from deleting the mod before uninstalling it.
  • TNG 10.1.0 Adds an Option to allow the Delete button for Installed mods to allow removing the previous version of the mod without having to uninstall the current version to delete the previous version.
TNG version: 10.1.0
This option defaults to NO and should be returned to NO after the previous version of the mod is uninstalled.

Using Mod Manager to update NON-TNG Files

You can also use TNG's Mod Manager to update files that are NOT part of TNG. E.g. if your TNG site is running under WordPress, and there are some files that you need/want to modify, you can create a Mod Manager file to make these changes. For the "Location" parameter, you need to specify the relative path to the file from the TNG root directory. This example shows the location path for one of the many files that makes up the NextGen Gallery image display plugin. The setup here is that TNG is in a folder called "tng" and WordPress is in a folder at the same level called "wp"

%target:../wp/wp-content/plugins/nextgen-gallery/products/photocrati_nextgen/modules/nextgen_basic_singlepic/templates/nextgen_basic_singlepic.php%

The rest of the Mod Manager rules are applicable.

Related Links

Mod Manager

Mod Manager Controls

For Mod Developers

Technical

Developer Tools

Example Mods

The Mod Manager Guide pertains to articles related to the TNG Mod Manager.