Mod Developer Quick Reference

From TNG_Wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Rules

  • Mod Manager (MM) tags must begin on their own line.
  • tags begin and end with a percent sign (%).
  • A colon separates arguments from the tag name and from each other.
  • Any text in the MM config file not part of a tag, or not enclosed in a target or newfile section is considered a comment. Although it's not required, many developers follow the PHP convention and prepend a double slash to their comments to clearly distinguish them as such.
  • Target text must be unique in the target file so Mod Manager knows where to install the modification and inserted or replaced text must be unique in the target file so Mod Manager knows what to uninstall.

Formats

There are three allowable tag formats:

  • %tagname:% -- a tag with no arguments
  • %tagname:argument% -- A tag with one argument
  • %tagname:argument_1:argument_2% -- a tag with two arguments
TNG version: ≥ 12.0.0

TNG v12 added a 3rd argument for %tngversion conditional processing tag

  • %tngversion:begin_range:end_range:label%

Types of Tag

Meta Tags

  • %desc:%
  • %description:%
  • %fileversion:%
  • %name:%
  • %version:%
  • %wikipage:%

Sectioning Tags

  • %target:file_to_be_modified%
  • %target:files%
TNG version: ≤ 11.1.2

The %target:files% is no longer necessary in TNG V12 and later

Delimiting Tags

  • %end:%
  • %fileend:%
  • %location:%

Conditional Processing Tags

TNG version: ≥ 12.0.0

TNG v12 added conditional processing tags. For each conditional test, if the result is true, processing will jump to the label provided; if not, processing continues with the next line of the CFG file. By properly ordering them, you can test for various conditions and process the mod accordingly.

If you have View Parser table set up in Mod Manager, you can click on the mod name and view the processing map in the parser table to see how each conditional test is or will be resolved for installing the mod.

Labels

A label is used to indicate where a jump in the CFG processing should land. The CFG can use a %goto:label% directive, or can jump to a label as a result of conditional testing. This is very similar to the GOTO command in Basic. Sytnax for inserting a label into the CFG file is 

%label:ANYWORD%

where ANYWORD can be any descriptive string of letters or numbers -- no spaces. Labels do not need to be all in caps, but capitalizing them makes reading the CFG a little more clear.

GOTO Jumps

%goto:DONE%

This directive is like the GOTO command in Basic. If placed in a CFG file, Mod Manager processing will jump to the label (DONE) and continue processing from there. There must be a valid label or else an error will be thrown. As a general rule, do not place labels before the %goto: directive to avoid endless looping. Labels do not have to be in caps, but capitalization makes the CFG file a bit easier to read.

Test for existence of a file

%fileexists:filename:label%

If 'filename' exists, jump to 'label'; otherwise continue processing with next line in the CFG file.

Test for text in open file

%textexists:DONE%
text-string-to-find
%end:%

Prior to this instruction the file to be searched must be opened with a %target: directive. If the text is found, processing will jump to the label, in this case DONE.

Test for which TNG version is in use

%tngversion:1110:1111:Use_TNG11.1.0%

Checks to see if the running version of TNG is included in the range 11.1.0 to 11.1.1; if it is in range, then jump to the label 'Use_TNG11.1.0'; otherwise continue processing with the next line of the CFG file.

Example of Conditional Processing

%fileexists:fgw_userconfig.php:CHECKIT%
%goto:DONE%

%label:CHECKIT%
%target:fgw_userconfig.php%
%textexists:DONE%
$options['pid_prefix']
%end:%
%location:%
$options['treelist']
%end:%
%insert:before%
$options['pid_prefix'] = "I";
$options['fid_prefix'] = "F";
%end:%

%label:DONE%

Conditional Tags

  • %fileoptional:%

Conditional Flags

TNG version: ≥ 12.0.0

TNG v12 added conditional flags

  • @ - for optional which can be used instead of %fileoptional in the %target file directive
  • ^ - for provisional meaning the file must be available when processes such as a %copyfile to a new directory created by the %mkdir:% directive
  • ~ - for protected meaning the file will not be deleted when the mod is uninstalled

See Mod Manager Enhancements for TNG v12 for examples

Code Modifying Tags (Directives)

  • %insert:after%
  • %insert:before%
  • %replace:%
  • %triminsert:after%
  • %triminsert:before%
  • %trimreplace:%
TNG version: ≥ 12.0.0

TNG V12 added for inserting in TNG configuration files maintained by the Setup dialog

  • %vinsert:after%
  • %vinsert:before%

Vinsert stands for variable insertion. They only affect the removal of a mod. Upon removal, these directives allow vinsert-ed variables to be removed regardless of their current value assignments in the script. For example, suppose your mod inserts a supporting variable, say $myvar=1, into some setup configuration file. Then at some point your mod setup changes the assignment in the config file to $myvar=0. Having used %vinsert to install it, $myvar=0 will also be entirely removed from the config file, even though the statement is not exactly what it was when the mod installed it.

File Handling Tags

  • %copyfile:%
  • %copyfile2:%
  • %newfile:%

TAGS (In Alphabetical Order)

%copyfile:source_file_path%

Copies source file to the TNG root. Source_path is relative to the mods folder. If source_file_path is prepended with an @ character, the copy operation is optional and generates a notice (but no error) if the file is missing or cannot be copied. Requires one argument. 

Example: %copyfile:my_mod_folder/my_file.php%

%copyfile2:source_file_path:destination_file_path%

Copies source file to destination path. Source_file_path is relative to the mods folder. Destination_file_path is relative to the TNG root. Requires exactly two arguments.

If source_file_path is prepended with an @ character (example 2 below), the copy operation is allowed to fail with only a warning if the source file is missing or the destination path is not accessible. Useful when copying language files to a folder that may not exists on the user's website. 

Example 1: %copyfile2:my_mod_folder/my_file.php:languages/English/my_file.php%
Example 2: %copyfile2:@my_mod_folder/my_file.php:languages/English/my_file.php%

%desc:text%

Required to follow a %parameter: tag. Displays the informational text about the parameter in the Mod Editor. This is a multi-line tag. The text may contain html, but must not contain raw Mod Manager tags. If it is necessary to use Mod Manager tags in the text, the percent signs must be replaced with the % character.

The desc must also contain the default value for the parameter enclosed in parentheses for instance (0) in the example below. The default value is used to replace the parameters when the Restore Default Parameter Values button is clicked which reads the value from the config file
. Important Note about default value. The default value must be the LAST set of parenthesis in the desc of the parameter !! It would be better to use parentheses within the desc ONLY for the default value 

Example: 
%desc:Referrer Option. 
[0)=Do not include referrer;
1=Include the referrer info, 
default:(0)]%

%description:Descriptive_text%

Required. Displays the text in the MM mod listing to remind users of its purpose. This is a multi-line tag. The informational text may contain html, but must not contain raw MM tags. If it is necessary to use MM tags in the informational text, the percent signs must be replaced with the HTML special character % symbol. This is a required tag. One argument. 

Example:
%description:<a href="http://tng.lythgoes.net/wiki/index.php?
title=FGW_Tabs_Mod" target="_blank">FGW Tabs</a> 
was written by Rick Bisbee based on idea proposed by Chuck Bush. 
It adds a tab to personal and family group pages to open a
pre-populated Family Group Worksheets for user input.%

Note: There is no space between the colon and beginning of the descriptive text.

%end:%

Locates the end of a block of code, either in a config file target section, or in a Code Directive tag section. No arguments.

See the %target for example of use.

%fileend:%

Locates the end of a new file section in which a file is created using text from the MM config file. No arguments.

See %newfile for example of use.

%fileoptional:%

Designates the target file or new file as optional. If it does not exist or cannot be created it is ignored. It must be the first tag after a %target tag or a %newfile tag. No arguments.

See %newfile for example of use.

%fileversion:version_number%

Use in a %newfile section to designate the official version of the new file to be created. One argument. 

Example: %fileversion:v10.0.3.0%

%insert:after%

Push the lines following the target code down and insert the new lines of code after the target. Will not break a line of target code for the insertion. This is useful if you want to insert after a block of code, parts of which may have been altered by another mod. One argument.

Visualize
target: 1234567890
location: 1234567890 (or 5678)
new code: abcd
result:
1234567890
abcd

%insert:before%

Push the lines containing the target code down and insert the new code above them. Will not break a line of target code for the insertion. This is useful if you want to insert before a block of code, parts of which may have been altered by another mod. One argument.

Visualize
target: 1234567890
location: 1234567890 (or 5678)
new code: abcd
result:
abcd
1234567890

%location:%

Locates a block of code in the target file to be modified or used as a reference for insertions. Must be inside a target section. The %location:% block would look like this: 

%location:%
//code to find in target file
%end:%
%insert:after%
//insertion code
%end:%

No arguments, but must be followed by some target code, followed by %end:%, followed by a directive, followed by new code, followed by %end:%.

%name:mod name%

Required. Should be the first tag in the MM config file and provides the name of the mod that will appear in the MM listing. This is a required tag. One argument.

Using spaces in the mod name rather than underscores is encouraged, even though Mod Manager may generate a warning (will be removed in the future.) Underscores in the mod name can cause it to sort after those without them in the main Mod listing. 

Example: %name:Login Messages%

%newfile:new_file_path%

One argument. Begins a section containing the text for a new file to be created by Mod Manager. The new_file_path is relative to the TNG root. If you want to create a file in the TNG extensions folder, new_file_path would be: extensions/new_file_name. The %fileversion and %version tags are required here, and the text for the new file must be terminated with %fileend:%. 

Example:
%newfile:extensions/hello_world.php%
%fileoptional:%
%fileversion:v10.0.3.1%
<?php
// %version:v10.0.3.1%
echo "Hello, World!";
?>
%fileend:%

%parameter:variable_name:value%

Placed inside a target section to set editable parameters (variables) in the target file to control behavior of the mod. Parameters trigger MM to create an edit screen for the mod in the MM list where the user can set or reset options.

Mod Manager will allow a %target:% section to contain only parameters, assuming the associated variables already exist in the target file. If a targeted parameter does not yet exist, you will have to use a %location block after the the %parameter settings to insert it.

%parameter has two arguments -- name of the variable, and value -- but the second (value) can be empty as in example 2 below. 

Example 1: %parameter:varname:myvalue%
Example 2: %parameter:varname:%

%replace:%

Replace the block of target code with the code that follows. A code fragment may not be used as a target or it will generate an error. No arguments.

Visualize
target: 1234567890
location: 1234567890
new code: abcd
result:
abcd

Visualize
target: 1234567890
location: 5678
new code: abcd
result:
Error: fragment not allowed here!


%target:file_path%

Required. There must be at least one target section (either type) in a mod file. A target section ends when another target section begins or the end of the configuration file has been reached. One argument.

Begins a section to modify code in a TNG or other file. The file_path is relative to the TNG root. Section must contain at least one %location and/or %parameter tag. 

Example: %target:tng_file.php%

%target:files%

Begins a section for file operations only: copyfile, copyfile2 or newfile. Contains one argument which is always "files". 

Example: %target:files%

This directive allows you to have a mod which does nothing but copy files if you need to.

%triminsert:after:%

An inline directive to concatenate new code to the end of the target code. One argument.

Visualize
target: 1234567890
location: 5678
new code: abcd
result: 12345678abcd90

%triminsert:before:%

An inline directive to concatenate new code to the beginning of the target code. One argument.

Visualize
target: 1234567890
location: 5678
new code: abcd
result: 1234abcd567890

%trimreplace:%

Replace the target code fragment with the new code. No arguments.

Visualize
target: 1234567890
location: 5678
new code: abcd
result: 1234abcd90

%version:version_number%

Required. Follows the name tag. Contains the version number shown in the MM listing. Also used in a newfile inside a PHP or HTML comment to identify the newfile version. MM checks to see that this version number is the same as the fileversion in the config file. If the version of the newfile is changed, the old version of the file must be replaced. One argument. 

Example: %version:v10.0.3.0%

See %newfile for example of using %version when creating a new file.

Related Links

Mod Manager

Mod Manager Controls

For Mod Developers

Technical

Developer Tools

Example Mods

Retrieved from "https://tng.lythgoes.net/wiki/index.php?title=Mod_Developer_Quick_Reference&oldid=78650"