View source for Mod Manager

{{TNGver||ver=10.1.0|notes='''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]]
*[[:Category:Mods_for_TNG_v13|Mods for TNG v13]] identifies the mods that apply to TNG V13
*[[:Category:Mods_for_TNG_v12|Mods  for TNG v12]] identifies the mods that apply to TNG V12.  
}}
{| style="margin-right:0.5 em;" align="right" 
| __TOC__
|}

== 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
# A configuration file, using  the file name extension .cfg, contains instructions that the Mod Manager uses to modify TNG files, and 
# Optionally, one or more files (which ''should'' all be in a subfolder) that are to be install ed 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.  <br />
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 10.1.0|and after}}
Several   enhancements were made in TNG V10.1 by [[User:Kazooter|Rick Bisbee]],   [[User:Jefr58|Jeff Robison]], [[User:Robinrichm|Robin Richmond]], and  [[User:KenRoy|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 12.0|and after}}
Several [[Mod Manager Enhancements TNG v12|enhancements]] were made in TNG V12 by [[User:Kazooter|Rick Bisbee]] with extensive testing by [[User:Hiraeth|Graham Chamberlain]],  [[User:WarrenGilbert|Warren Gilbert]], [[User:lhaymaker|Lincoln "Linc" Haymaker]], [[User:Wrherndon|Bill Herndon]], [[User:XerxX|Erik Hoppe]], [[User:Tngrlkrz|Ron Krzmarzick]],  [[User:TheKiwi|Roger Moffat]], [[User:Robinrichm|Robin Richmond]], [[User:Jefr58|Jeff Robison]], [[User:KenRoy|Ken Roy]] with testing and translation by Mogens C. Fenger, [[User:Tngrlkrz|Ron Krzmarzick]], and [[User:Bernard57|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 11.0.2|and after}} 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 11.0.2|and after}} 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. <!-- For a more detailed, graphical   explanation see our [[Mod Handler Overview]] -->.

{{TNG 11.0.1|and before}}
'''<span   style="color: red">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</span>'''   '''extensions''' folder.

{{TNG 12.0|and after}} 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)


<syntaxhighlight lang="php" >
/*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*/
</syntaxhighlight>

== 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.

[[File: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 12.0|and after}}
TNG v12 displays the content of the %note: and %private: keyword note text to the status line.<br />

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.

[[File: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.

[[File: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]]

* [[Mod_Manager_-_Interpreting_Status#1._Ok_to_Install|OK to Install]]
* [[Mod_Manager_-_Interpreting_Status#2._Installed|Installed]]
* [[Mod_Manager_-_Interpreting_Status#4._Partially_Installed|Partially_Installed]]
**[[Mod_Manager_-_Interpreting_Status#Variation_of_same_mod|Variation   of the same mod]] will show one as requiring cleaning.  You probably   should delete the version you are not using to avoid   confusion.**[[Mod_Manager_-_Interpreting_Status#New_Version_of_mod|New   Version of Mod]] will show existing mod as Installed and new one as   requiring Cleanup. The correct action is to Remove the existing version,   install the new version, and then delete the old version of the mod.
{{TNG 8.1.3|and before}} 
* Clean Up required in TNG V8 that becomes Unable to Install in TNG V9
**[[Mod_Manager_-_Interpreting_Status#Code_has_changed|Bad   Target  indicates possible code change]] Mod developers should verify   that the  config file is coded correctly and update the code to be   verified  appropriately.
**[[Mod_Manager_-_Interpreting_Status#Code_Modified_by_other_mod|Same    code is modified by another mod]] will show as requiring Cleanup.   Mod   developers show attempt to fix by changing the location of one of  the   mods in conflict. 
{{TNG 9.0|and after}}
* 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   [[Mod_Manager_-_Interpreting_Status#Unable_to_install|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 10.0.3|and after}}
: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  10.1.0|and after}}
: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"

<syntaxhighlight lang="php" >
%target:../wp/wp-content/plugins/nextgen-gallery/products/photocrati_nextgen/modules/nextgen_basic_singlepic/templates/nextgen_basic_singlepic.php%
</syntaxhighlight>

The rest of the Mod Manager rules are applicable.

== Related Links ==

{{: Mod Manager related links}}

[[Category:Mod Manager]]