Mod Manager - Creating Config Files

Introduction

The purpose of this page is to provide some helpful hints for the mod developers so they can create the appropriate Mod Manager Config file for their mods, using the instructions below and examining the existing config files in the various TNG Mod articles.

Operation

The Mod Manager examines the mod_folder and reads each "cfg" file that it finds. The "cfg" files are directive files that describe the mod, the files and locations to be modified, and the code that is used in the modification.

The Mod Manager checks the following:

• ensures the user is logged in
• examines each code location and change
  • ensures the location can be found
  • ensures the target location is unique
  • identifies whether the target location has already been installed
• identifies new files to be created
  • if the new file already exists, it examines the version level
• if the mod is not yet installed and the target locations can be identified, then the option to install is presented
• if the mod is completely installed, the option to remove the Mod is presented and the option to edit parameters if any exist
• if the mod is partially installed, the option to clean the Mod is presented. A Clean operation will attempt to remove any inserted code, restore and replaced code, and remove any created file.

Creating Mod Configuration Files

Mod Developers should create config files to be used with Brian's Mod Manager. The following are some hints on how to use some of the keywords.

• use %triminsert:before%, %triminsert:after%, or %trimreplace:% to insert or replace within a line of code
• use %insert:before%, %insert:after%, or %replace:% to insert or replace complete lines of code
• use %copyfile:filename.ext% to copy files from the mod_folder to the TNG installation directory
• use %copyfile2:filename.ext:extensions\filename.ext% to copy files from the mod_folder to a TNG subdirectory, such as extensions or admin
• only include English/cust_text.php variables in config files, but provide instructions for users to create equivalent entries in their other language cust_text.php files, or provide translations where available

The following are recommendations on the config file naming:

• use lowercase letters only since Linux systems are case sensitive
• use a vn.n designator in the file name to indicate the version.release (or vn.n.n for version.release.mod)

You might consider saving or creating your code snippets in the extensions directory, so mods are isolated from the TNG code and using a conditional include @include to bring the code snippet into the TNG module. Certain scripts will continue to execute best from the TNG installation directory or the TNG admin subdirectory.

You should also include an == Automated Install == section in the article that describes how to install your TNG mod as was done for the Admin Header Mod and provide a zip file of the config file that installs your mod and all its components.

See Understanding the Mod Manager config file syntax

See Mod_Manager_-_Installing_Config_Files for an example on the steps required to install using the Mod Manager.

Also see the Mod Manager Syntax article.

Example Configuration File

Here is an example of a very, very simple Mod Manager configuration file. Note that the % character at the beginning of a line starts a Mod Manager command, and Mod Manager commands always end with another % character. (Note that some Mod Manager commands, such as the mod description at the beginning of the command file, can be more than one line long. But like one-line commands, multi-line command arguments always end with a percent sign.)

 %name:Example Mod%
 %version:v12.0.0.1%
 %description:Insert the description of your mod here.
 You can say anything your want, and include HTML code, but not Javascript or CSS.
 A percent sign marks the end of the description
 %

 %target:some_existing_filename%
 %location:%
   A %location% command is followed by search text that determines the location of a change to be made to the file filename.php.
   An %end:% command terminates the search text.
   Most of the time, the search text consists of PHP code, but it is not interpreted as code; it is just text.
   This text can simply identify where new text will be inserted, or it can be
   replaced by new text, depending on the command that follows the %end:% command.
 %end:%
 %insert:before%
   This is the new text, which in this case, is inserted below the search text.
   As with the %location% command, the insertion text is terminated with %end:% 
 %end:%  

The %location% command can be repeated as often as necessary to edit multiple locations in the file, and the %target command can be repeated as often as necessary to edit multiple files.

Here is a slightly more complicated example that

1. Uses the %private% command to identify the mod as private. The Mod Manager will display the word "Private Mod" in this mod's status cell.
2. Has two target locations in the file it modifies.
3. Defines a new file that is placed in the main TNG folder.
4. Copies a new file from a mod subfolder into the main TNG folder.
5. Copies a new file from a mod subfolder into the TNG images folder.

 %name:Sample Mod 2%
 %version:V12.0.0.1%
 %description:This mod makes 2 changes and installs 3 new files% 
 %author:John Doe:{web address}%
 %private:%

 %target:media_program.php%
 %location:%
   include "(begin.php)";
 %end:%
 %insert:before:%
  ###This file has been modified by the mod "Sample Mod 2"###
 %end:%

 %location:%
 $maxlistlength = 200;
 %end:%
 %replace:%
 $maxlistlength= 500; //Modification by Sample Mod 2
 %end:%

 %newfile:findbrokenmediarecords.php%
 %fileversion:2.0%
 The contents of the file start here. It must have this comment:
 // %version:2.0%
 If the file already exists, it will be overwritten only if the version number in the existing
 file's version comment is lower than the version number in the Mod Manager %fileversion% command.
 The file can be as long as you need for it to be, and like search, insertion, and
 replacement text, the Mod Manager just treats it as text, not as PHP, Javascript, or CSS code.
 The new file content ends with the Mod Manager command %fileend:%.
 %fileend:%

 %copyfile:subfoldername/new_program.php%
 %copyfile:subfoldername/new_icon.gif:img/new_icon.gif%

Note that

1. The first target location simply adds a PHP comment that flags the fact that this file has been modified.
2. The replacement string in the second target location contains a PHP comment that distinguishes the edit from native TNG code. Without such comments, it can be very hard for administrators, and especially other mod authors, to know whether a line of code is native or has been inserted by a mod.
3. In the %copyfile% commands, the subfolder name should be the same as the Mod Manager command file, without the .cfg suffix.
4. The first %copyfile command has only one file specification, so it just copies the specified file to the main TNG folder.
5. The second %copyfile command has two file specifications (separated by a colon), and it copies the file to the specific location below the main TNG folder.

Additional Directives

• %fileoptional:% - used after a %target:% keyword to indicate that if the file does not exist, no error should be generated. The %fileoptional:% keyword is currently only supported for describing edit parameters in a file that will be created during the mod
• %parameter - see cfg files for examples or contact the author. This keyword triggers the Mod Manager to present the option to EDIT parameters after a mod has been installed. The Edit screen will use the %desc keyword to provide a label describing a parameter edit field.

The Default value should not be specified as a quoted value within parentheses as part of the %desc keyword, such as Defaults to (png) in the example below. The default value must be specified within parentheses to be used to restore the default value when the user clicks the Restore Default button

When a user wants to clear the value of a variable, they can simply erase the value in the edit parameter field.

Note that once entered, then parameter value will be stored in the target script and will also cause the config file to be updated. Thus when testing the Edit of parameters, you should make sure they are set to the correct defaults before creating the zip file for the .cfg file.

• %desc - used to provide a description for the %parameter that can be edited on the Edit screen

The following example below shows how the parameters are used in the Signature Display mod for the Edit screen displayed when you click the Edit button once the mod is installed allows changing the extension for signature display files. The variable being changed is in a file that does not yet exist but is created by the installation of the mod.

%target:$extspath/signature.php%
%fileoptional:%
%parameter:$signaturext:png%
%desc:Extension for signature file. Defaults to (png) to allow transparent signature files to be created. <br />
Can be <em>png</em>; <em>gif</em>; or <em>jpg</em>.<br /> If cleared or erased, the mod will use the $photosext in General Settings >> Media >> Photos Extension as previously.<br />Do <strong>not</strong> use any quotes.%
%end:%

Note that the string parameters must be specified without using quotes as shown in the %parameter:$signaturext:png%

Note that the Default value must be specified within parentheses such as Defaults to (png) above. Do not use any quotes. Do not use parentheses within the %desc directive for any other reason other than specifying the default.

See Mod Manager - Edit Parameters for information on Editing parameters within the Mod Manager.

Zip Files

Content

Your mod .cfg file should be in the root of the created zip file and not in a mod name folder. Some TNG users extract the zip file directly to the TNG mods folder. The Mod Manager expects the mod .cfg file and any associated sub folders to reside in the TNG mods folder and not in a sub folder. If you use a mod name folder to create your zip file, then the Mod Manager will not find your mod when unzipped directly to the mods which will also result in unnecessary issues being reported on the TNG Community Forum or the user2 email list.

Mod Zip Files created for the Mod Manager .cfg files and associated folders should normally contain:

• only the .cfg file for the mod itself
• associated folder if the mod provides scripts that are copied using the %copyfile or %copyfile2 directives

See Dealing With Different Zip Files that were not created using the above guidelines.

Upload to the TNG Wiki

Your mod zip file should be uploaded to the TNG Wiki using the Tools, Upload File link at the bottom of the left nav sidebar.

If you host your mods on your own site and your site disappears, TNG users can no longer download your mods and other developers will not be able to take over supporting your mods.

Thankfully Bart Degryse's mods were all uploaded to the TNG Wiki so that other TNG mod developers can continue to support his wonderful mods.

You should upload new versions of your mod to the TNG Wiki before you update the mod article. Failure to do this results in a TNG User getting the File Upload dialog instead of the mod zip file.

Download Name Display

If you use Bart Degryse's Click Counter II to track the downloads of your mods, you should display the actual zip file name in the download link. If you do not use the actually zip file name you uploaded to the TNG Wiki or you point the Click Counter to your own site and your site goes away, we may not be able to find the zip file for your mod so that the TNG Wiki can be updated to point to the file location on the TNG Wiki

If you do not display the actual zip file name for your mod on the TNG Wiki as the download link, then you are also causing additional work for the TNG Wiki sysops who will try to find your mod so your mod page can be updated to allow other TNG users to download your mod when your site goes away.

You should use the HTML comment characters to indicate the zip file name in your TNG mod article to make it easier in case your site goes away.

If you host your own web server and power off the server because you are away for an extended period of time, then users are not be able to download your mods when you use the Click Counter to track downloads, whether the mod zip file is on the TNG Wiki or not. You should update the TNG Wiki articles for your mods to use mod-file_version.zip before you power down your server because you will be away for an extended period of time.

Click Counter Email Notify

The Click Counter Email Notify mod has been updated to allow downloads from sites that require login and when the mod developer's site is in TNG Maintenance Mode

Guideline Summary

The following guidelines should be followed:

• Your TNG Mod zip files should reside on the TNG Wiki - use the Tools, Upload file in the bottom left nav sidebar to upload your mods to the TNG Wiki

• Your TNG Mod zip files should be uploaded before you update your mod article on the TNG Wiki.

• Your TNG mod zip file name display should match the actual file name uploaded to the TNG Wiki, so that the zip file can be found if your site goes away

• Your mod cfg file should be in the root of the zip file.

See Dealing With Different Zip Files for zip files created on a MacIntosh that contain the mod folder name and MacOS data

Related Links

Mod Manager

• Overview
• Why Use It ?
• Installing Config Files
• Batch Updates
• Interpreting Status
• Editing Parameters
• Deleting Mods

Mod Manager Controls

• Mod Manager Options

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

• Technical Overview
• Technical Directives
• Quick Reference
• Inside Mod Manager v12

Developer Tools

• Notepad++ Mod Manager Language

Example Mods

• Managing Configuration Files
• Managing Stylesheet Overrides