Mod Manager - Creating Config Files

From TNG_Wiki
Jump to: navigation, search

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.

Typical Configuration File

The following outlines a typical configuration file and the associated keywords. Note that the % character is used to assist in delimiting the fields and keywords.


%name:Insert Mod Title Here%
%version:V8.1.0%
%description:Insert the description of your mod here.
Include any special notes or even links to your support page.
The percent sign marks the end of the description%

%target:filename_to_change.php%
%location:%
  This must be a unique section of code in the target source file.  
    If you have a choice, select snippits that are likely to be the 
  same from TNG version to version.  It is all the code between the %location:%
  and the %end:%.  White space before and after this section will be trimmed
  before trying to locate it in the source file.
    You may repeat the  %location:% -- %end:%  %insert:before% -- %end:%
  sequences for each segment of code you wish to change in the same target.
    You can also have as many %target% sections as required.
%end:%
%insert:before%
  This is the new code that will be inserted immediately before
  the %location:% code.  The directive can be %insert:before%,  %insert:after%, or %replace:%

  If code is being replaced in-line and you do not want line breaks to interfere with the code, 
  you can also use the directives  %triminsert:before%,  %triminsert:after%,  %trimreplace:%.
%end:%  


%newfile:placesearchform.php%
%fileversion:2.0%
This would be the contents of a new file to be created.    
The fileversion above is used to compare against a possible version number
in the newfile if it already exists. The new file contents will be
everything between the %fileversion:$ directive and the %fileend:% directive.
The new file should have a %version:% directive as shown below.
// New File Contents
// More Comments
// %version:2.0%
Code
Code
%fileend:%
%copyfile:new_icon_file.gif%

The %copyfile: directive is used to copy a file from mod_folder to the main TNG folder.

%copyfile2:new_file.gif:extensions\new_file.gif%

The %copyfile2: directive is used to copy a file to an alternate 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 also be specified as a single-quoted value within parentheses as part of the %desc keyword, such as Defaults to ('png') in the example below. The single-quoted value within the parentheses will be used to restore the default value.
When a user wants to clear the value of a variable, they will need to provide 2 single-quotes 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:extensions/signature.php%
%fileoptional:%
%parameter:$signaturext:'png'%
%desc:Extension for signature file. Defaults to ('png') to allow transparent signature files to be created. The previous mod version used the $photosext as defined in General Settings >> Media >> Photos Extension.<br />
Can be <em>'png'</em>; <em>'gif'</em>; or <em>'jpg'</em>. If cleared (by typing two single quotes), the mod will use the $photosext as previously.<br />
The default can be restored by clicking the <strong>Read Existing Values from TNG files</strong> button.%
%location:%
    $signaturext =
%end:%
%trimreplace:%
    $signaturext =
%end:%


Note also that the string parameters must be specified using single-quotes as shown in the %parameter:$signaturext:'png'% and Defaults to ('png') above.

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

Related Links

Mod Manager

Mod Manager Controls

For Mod Developers

Other Uses of Mod Manager: