Important Notices
PHP 8 Dynamic Properties Deprecation warnings
If you are using an early version of Mod Manager with PHP 8, you may find you're getting a lot of deprecation warnings, something like:
Warning: Creation of dynamic property is deprecated...
While perfectly legal in previous versions of PHP, they now throw warnings and will soon lead to fatal errors.
To continue using earlier MM code with PHP 8, you can tell PHP not to enforce this rule by placing the following comment in the classes/modbase.class.php file, just above the class declaration, like this:
#[AllowDynamicProperties]
class modbase {
New in TNGv15 - Case Insensitive Instructions
Mod Manager instruction names are now case insensitive. For example %range:0:3% is the same as %RANGE:0:3%
Definitions
Argument
An argument is a piece of data required by a Mod Manager instruction to complete
its task. Arguments are placed in the instruction immediately after %instruction_name:
(percent+instruction_name+:) and if more than one argument is required, they are separated from each
other by colons. The Instruction itself is terminated with a percent sign.
For example, %instruction_name:arg1:arg2:arg3%.
Block
As found in a target file, a block of text begins on its own line and ends on its own line. If it begins or ends in the middle of a line it is not a block, it is a fragment.
Codeblock
A codeblock is a block of text or code beginning after a %location or text altering instruction such as %insert:before%. A codeblock must be rendered exactly as it appears in a mod configuration file.
Conditional Instruction
A conditional instruction is used by the mod parser to test for a
specific condition such as the existence of a file, and jumps to a named %label to continue building the
parse_table if the condition is true. If false, the parser drops through to the next instruction to continue building the parse table. The table will only include instructions within the conditional path. However, the parse table will show which jumps were made and to where in the mod config file which may be useful when debugging a mod.
Datapack
A datapack is an array, one for each instruction found in the mod configuration file, containing the line number in the mod configuration file, the name of the instruction, arguments to the instruction, processing flag (if any), status key and, if there is an error, the line number in the processing module where it occurred. Each row in the parse table is a single instruction datapack.
Instruction
Mod Manager uses instructions (or directives) from a mod configuration file to
modify the website. Instructions are highly structured, have strict rules and can have a number of
arguments, depending of the specific instruction. They may or may not be processed in the order given
in the file. Only instructions in a mod configuration file are processed by Mod Manager.
Open target file
An “open” file is a file whose contents have been read into a working “buffer"
– a string variable within Mod Manager in which changes, if any, are made and written back out to the
target file when finished.
Parameter
A parameter is a PHP variable in an operational script whose value is changeable by a user via
the MM mod editor.
Parse Table
The Mod Manager parser examines a mod configuration file, builds a table (array)
of instructions and their arguments, and makes it available to other downstream processes for listing,
installing and removing a mod. Only the Modparser works directly with the mod configuration file.
Other processes work from the parse table. Each row of the parse table is an instruction datapack.
Status Key
The status key (statkley) is a bitwise field in an instruction datapack (and parse table)
containing data about the instruction’s status. It is calculated and placed in the parse table by
Modvalidator.
Text Altering Instruction
A text altering instruction modifies text within a targeted file, as opposed to an instruction that copies a file or makes a directory. %insert:before and %trimreplace are examples of text altering instructions. They must always follow the codeblock of a %location instruction.
General
Mod Manager Class Objects
Mod Manager basic services are provided by OOP objects defined by their specific class files. The names of the classes suggest their functions. So we have Modparser.class.php, Modvalidator.class.php, Modlister.class.php, Modinstaller.class.php and Modremover.class.php. In referencing them we often shorten their names to Modparser, Modvalidator, etc.
A helper class, Modbase, contains definitions and functions used by all the other classes, and it contains a "data dictionary" -- $proclist -- that has the names of valid Mod Manager instructions and the common name for their processing methods (functions) found in each of the main processing classes. Two exceptions are %modvar and %exit, which are preprocessing instructions to the parser. In other words, those instructions must be executed before the parser can validate instruction names in the $proclist.
In General, MM objects all use the same architecture for process instructions: the next argument is read from the mod configuration file or parse table, and a "dispatcher" sends it to an instruction-specific function that processes it according to the purpose of the class object - validates, lists, installs, removes, etc.
[back to top]
Mod Manager Instruction Format
- A Mod Manager instruction must be formatted as follows: %name:(arg:)(arg:)(arg)%.
- An instruction must begin and end with a percent sign (%).
- An instruction name must be terminated with a colon and may be followed by up to three “arguments” separated by colons. The number of arguments is determined by each instruction based on its needs.
- An instruction must begin on its own line with nothing except white space (spaces
and tabs) preceding it. If any other characters are placed before an instruction, it will be treated
as a comment and ignored by MM. This means an instruction can be "commented out" using // or # (or any other character) in front of it.
- Mod Manager instructions are case-insensitive beginning with TNGv15.
- Text between instructions is ignored as commentary unless it is a codeblock. A codeblock
must begin on the line immediately following certain instructions such as %location or %insert:after, and must be terminated with an
%end:% instruction. A %newfile instruction codeblock must be terminated with %fileend.
- An argument may span multiple lines. The %description instruction often spans multiple lines.
- An instruction such as %description that must use the termination character as text, may escape it with a backward slash (\%) to prevent Mod Manager treating it as a terminator.
[back to top]
Flags
Mod Manager instructions that deal with files or directories may include a flag character prepended to
the first argument.
For example, take the following -- %target:@myfile.php%. @ tells Mod Manager that this instruction is optional -- if the target file is missing, bypass the instruction without throwing an error. This might happen if your mod inserts new text to a bunch of different language files, one of which may be have been deleted by the site owner. One of the site's language files may be missing, but we still want Mod Manager to install the rest of the mod.
Please note that any target file whose file name begins with a @ flag may not be found by MM, which will strip it as a flag, then look for a file named without it.
The ~ protected flag tells Mod Manager that the file or directory is protected; do not remove or over copy it. This flag is useful, for example, on a data configuration file. If the mod is removed and reinstalled, you do not want to set up your configuration again, so just leave it. Mod Manager tells you in the logs and listing that the file is protected and must be removed manually.
The ^ provisional flag tells mod manager that certain elements acted upon by the mod may not be present until after the mod is installed. Mod Manage will allow the mod to be listed without error, but will require it during installation.
The ^ provisional flag is very similar to the @ optional flag, except that the mod will still install if the optional element is missing. If a provisional element is missing while being installed, the mod will not install and will throw an error.
Only one flag may be used per instruction. Multiple flags on the same instruction are forbidden.
[back to top]
Logging and Errors
Mod Manager maintains a log reflecting as much as possible the result of processing Mod
Manager instructions and the overall status of the mod. Errors and status will also be displayed in the
mod listing.
The MM log can be accessed through a tab - View Log - on the mod listing page.
[back to top]
Parsing
Modparser extends Modbase and has one public function that creates a parse table containing rows of processable instruction datapacks.
$Modparser_object->parse($cfgpath)
The mod parse table is available to all extending classes via a protected property - $this->parse_table.
Modparser:
- Reads files into working buffers and standardizes line endings to CRLF (\r\n) before processing them. Mod Manager “pointer” processing may use either \r or \n to locate a line ending, depending on direction of search – forward or backward.
- Validates instruction using the Mod Manager dictionary ($proclist) defined in Modbase.
- Creates a parse table (array) of all instructions and their arguments found in a mod configuration file if they are informational like %name, %version or %descriptions, or would in anyway change the content of a TNG website.
- Passes the parse table to all “extending” Mod Manager classes and is used by them as the basis for further processing — validating, listing, installing, removing a mod, or editing a mod’s parameters.
- Will not modify text within a codeblock.
- Resolves TNG path variables $modspath and $extspath included in any instruction arguments (codeblocks are not within an argument).
- Process %modvar instructions prior to parsing a mod configuration file by substituting placeholders (first argument) with their value (second argument). %modvar instructions will not appear in the parse table.
- Tests conditional instructions and only includes in the parse table operational instructions within the conditional path, except when the table is requested by Modremover, in which case all instructions, conditional or not, are included.
- Confirms that the minimal number of arguments are provided with each instructon and reports missing arguments as errors. Mod Manager may not be able to distinguish if extra arguments have been included or not. Adding extra arguments to an instruction may result in appending them to the previous arguments, causing the instruction to fail.
- Replaces escaped terminators (\%) found in instruction arguments with HTML character codes.
- Permits the use of double or triple instruction terminators (%% or %%%) to protect unescaped terminators (%) within its arguments.
- Considers all text that is not part of a Mod Manager instruction as comment. You can use /* or // to identify text as comment in a cfg file, but no specific text is required. Using comment characters just clarifies intent.
[back to top]
Mod Validation
Modvalidator has two public functions. One validates each instruction in the parse table, confirms it can actually be executed against existing files and text, adds the resulting status codes to the parse table datapacks and returns the updated parse table.
$updated_parse_table = Modvalidator_object->validate($cfgfile)
A second public function returns mod status array ($mm_data) containing status for a single mod or all the mods in the mods directory.
$mm_data = Modvalidator_object->check_status($create_mm_datafile=false, $cfgpath='')
If the first argument is true, Modvalidator will also produce a file -- mm_data.php -- containing the status information as an array -- $mm_data -- so other scripts can `include` it and process the data.
If no $cfgpath is given, function creates an $mm_data array with status of all mods in the mods directory.
[back to top]
Mod Removal
When removing a mod, Modremover will attempt to remove all possible installed elements, including conditional elements that may or may not have been installed.
In removing a mod, when an element is not found, Modremover will note that fact without error in the log and continue processing until all remaining elements are removed.
Modremover is used to clean up “Partially Installed” mods and attempts to leave them completely uninstalled and in “OK to Install” status.
Where it makes sense, mod elements are removed in reverse order of their installation. For example if a mod creates a directory and then copies files, then when removing it, it will remove the files first and then removes the directory. This is done by rearranging the parse_table datapacks which are then processed in the new order.
[back to top]
Parameter Editing
- Modeditor does not write variable statements that will crash PHP.
- Modeditor operates on the first, and only the first instance of a variable assignment statement in a target file ($variable = value).
- Does not recognize “commented out” variable assignments in a target file.
- Will match data types when inserting parameter values — string, numbers and booleans.
- Will not allow single quotes (or apostrophe) within single-quoted strings.
- Will not allow double quotes within double-quoted strings.
- Provides for the use of HTML quote characters to avoid crashing PHP.
- Provides for the use of HTML character for the mod terminator — the percent sign — within an instruction argument.
- Allows developers to restrict user input to specified values, beginning with TNG15.
Tip
If you want to use a parameter whose value can either be a variable or a user-defined string, surround the parameter value in the target file with double quotes.
[back to top]
Mod Manager Instruction Set
%author:name:optional_link%
name - author's name (do not use quotes.)
optional_link - creates link out of author's name to anywhere the author desires. Note that the link contains colons (MM argument separators). Because this instruction can only have two arguments, MM does not parse colons inside the second argument, so they are safe.
Example: %author:Rick Bisbee:https://tng.lythgoes.net/wiki/index.php?title=User:Kazooter%
- do not use quotes.
- displays name of mod's author in the mod listing. If the optional link is defined, the displayed name can be clicked to open the link.
- This instruction may be used multiple times within a mod configuration file. Each time it is used it adds an author to a list of authors displayed in the mod listing.
- Use separate %author instruction for each author. Do not try and combine them into one instruction.
[back to top]
%choices:choice1, choice2, choice3, etc%
choice1, choice2, choice3 - only one argument, a comma separated list of the allowable choices to be entered in a mod editor input field.
Purpose is to allow mod developers to restrict parameter input values in the Mod Manager Options Editor to a list of allowable values.
Example:
%parameter:$PRO_DISPLAY:No%
%CHOICES:Yes,No%
%desc:Display errors on screen.<br /><br />
Set this parameter to display actual errors and notices to the screen for development and testing.<br />
Yes=display real errors to screen.<br />
No=do not display real errors to screen<br />
default: (No)%
- Do not use quotes.
- %choices may assign strings, numbers or booleans, depending on the type of variable in the target file. If the choice is false and the target parameter is a boolean it will be assigned as false. However if the choice is false and the target variable is a string, it will be assigned as "false".
- If used, this instruction must be positioned between a %parameter and a %desc instruction.
- If input is not one of the listed choices, it is rejected. The input field in the Modeditor continues to show the previous value; no updates are made and no errors are displayed or logged.
- Items from %choices list is case-insensitive for user input, but the value assigned to the parameter variable uses the exact case in the %choices list. If one of the choices is Yes, but the user enters yes, the input will be accepted, but the parameter variable will be assigned the string value "Yes".
- The default value for the parameter must be one of the listed choices.
[back to top]
%copyfile:source_file:destination_file%
Second argument (destination_file) has been optionally allowed since TNG12
source_file - path to the file to be copied, relative to the mods directory.
destination_file - only available since TNG12. optional, path to the destination file to be copied, relative to the TNG root directory.
Purpose is to copy a file from one location to another. This is usually to copy a file from a mod support folder in the mods directory, to a location on the website.
Examples:
%copyfile:~mod_support/control.php% <-- notice the 'protected' flag on the first argument
%copyfile:mymod_v21/languages/Esperanto-UTF8/text.php:languages/Esperanto-UTF8/text.php%
- The protected flag in the first example means that if the file already exists it will not be over-copied, and upon removal of the mod, the file will not be removed.
- %copyfile may have one or two arguments.
- The first argument is the source file and it is required. The examples show a file to be copied from a mod support folder in the mods directory to the TNG root directory.
- The source file must exist on the server, except when flagged Optional (@) or Provisional (^).
- The second argument is optional and may contain the path and name of the destination file. If the second argument is not provided, MM will attempt to copy the source file to the TNG root directory using the same name as the source file.
- The destination file need not have the same name as the source file.
- If flagged ‘Protected (~)’ %copyfile will not over write or delete the destination file if it already exists.
[back to top]
%copyfile2:source_file:destination_file%
Second argument (destination_file) is optional since TNG12.
Previous to TNG12 a destination file (second argument) was required.
Since TNG12 this instruction is the same as %copyfile (qv). It is maintained for backward compatibility.
[back to top]
%desc:parameter_info%
parameter_info - Information about the parameter to be displayed in the Modeditor next to the input field. It may span several lines and must include a parameter default value given in parentheses.
Examples:
%desc:Enter the number of backup copies to keep (0-4)<br>
Default is (1)%
%desc:Show the profile in the report?<br />
0 = Don't Show the profile><br >
1 = Show the profile<br />
default is (1)%
- If more than one set of parentheses is found in the parameter_info, the last set is considered to contain the default value.
- A default value may be left empty () except if a %range or %choices instruction is used; then it must contain a value in the range or choices list.
- %desc will only be processed if there is a target file open.
- Each %desc must follow a %parameter instruction, a %parameter and %choices instruction or a %parameter and %range instruction.
[back to top]
%description:text%
text - descriptive information to place in the mod listing about the mod's purpose and use.
Examples:
%description:This mod places '[X]' beside each mod in the listing. Clicking on it retires a mod and its support folder to a sub-directory created in the mods folder and <b>it will no longer appear in the mod listing</b>.%
%description:Mod checks the status of mods in the '$modspath' directory. It also checks for unescaped \% characters in the text.%
%description:Mod checks the status of mods in the '$modspath' directory. It also checks for unescaped % characters in the text.%% <-note double terminators
Note behavioral differences below.
- Prior to TNGv12, %description did not resolve path variables $modspath and $extspath in the description text. It also required you to use the html character code for any '%' character used internally in the description.
- Starting with TNGv12, Mod Manager resolves %modspath and %extspath in the %description. It also resolves '\%' anywhere in the mod config file buffer, replacing it with html character '%'.
- Beginning in TNGv12, as an alternative to escaping '% characters, Mod Manager allows the use of double (%%) and triple instruction terminators (%%%) for text strings. Using a double terminator (%%) allows unescaped single '%' within the text. A triple terminator (%%%) allows unescaped double '%%' inside the text.
- Beginning with TNGv15, Mod Manager recognized that any text inside a codeblock must not be changed by MM, so resolving paths and special character '\%' no longer applies inside any codeblock, but it still applies everywhere else.
- Do not use quotes around the %description text.
- %description is a required instruction.
- %description argument accepts text, including HTML tags, allowing for links and styling to be included.
- %description may be defined more than once in a mod configuration file; a %description instruction replaces any previous %description. Used in conjunction with conditional testing, %description may provide detailed explanation of error condition. For example, it can be used to notify user that the mod is intended for a different version of TNG.
[back to top]
%end:%
- %end has no arguments and is not included in the parse table.
- This instruction is intended to terminate blocks of code, which can contain any possible characters, so a simple termination character (%) will not suffice. All codeblocks except that used by %newfile must be terminated with this instruction.
[back to top]
%fileend:%
- Similar to %end:%, but only terminates a %newfile codeblock.
- %fileend hase no arguments and is not included in the parse table.
[back to top]
%fileexists:file_path:label%
Conditional Instruction
file_path - path to file which will be tested to see if it exists.
label - forward label in the mod config file to which, if the file exists, the parser will jump and continue parsing from that point. If the file does not exist, the parser will continue parsing with the next instruction following %fileexists.
Example:
%fileexists:languages/Esperanto/text.php:is_esperanto%
- The label may skip any number of instructions, but it must be defined like this: %label:is_esperanto%
- Information about the instruction and resulting jump to another location within the mod configuration file is included in the parse table to assist in debugging.
[back to top]
%fileoptional:%
Example:
%target:languages/Esperanto/text.php%
%fileoptional:%
- %fileoptional takes no arguments.
- This instruction follows a %target instruction to make opening the file Optional.
- Since TNGv12 %fileoptional can be replaced by prepending an 'Optional flag' (@) to the target file path argument - same end, less typing.
%target:@languages/Esperanto/text.php%
[back to top]
%fileversion:version%
version - version of the %newfile being created.
Example:
%newfile:languages/Esperanto/text.php%<br>
%FILEVERSION:v14.0.5.1%
[Content of the new file]
%fileend:%
- %fileversion immediately follows a %newfile instruction.
- The version must match a commented %version instruction inside the created file, for example:
//%version:14.0.5.1%.
- Mod Manager will not create a new file unless the versions match each other and will throw a fatal error for the mod.
[back to top]
%goto:label_name%
label_name - Unique name of the label to jump to.
Purpose is to allow mod configuration file processing to jump over instructions, usually as the result of a conditional test.
Example:
%goto:do_copy%
...
...
%label:do_copy%
- label_name must match the argument of a %label:label_name% instruction further on in the mod configuration file.
- %goto directs the parser to jump forward to the matching %label to continue processing, skipping over any instructions in between.
- %goto will not jump backwards in the script (possibly causing an infinite loop).
- Each %label instruction argument shall be unique.
[back to top]
%insert:after%
after - tells mod manager to insert the codeblock into the target file after the preceding %location codeblock. The only other possible value for this argument is 'before'.
Purpose is to insert a codeblock of text after a block of existing code in an open target file.
Example:
insert:after%
[block of code to insert]
%end:%
- Mod Manager will not list or execute this instruction if its target file cannot be opened.
- This instruction must be placed immediately after a %location:% codeblock in the mod config file.
- %insert:after must be followed on the next line by a codeblock containing the text or code to be inserted.
- The required codeblock must be unique in the target file; if not, if the code would create a duplication in the target file, Mod Manager will throw an error in the Mod Listing with a status of Cannot Install.
- To ensure the inserted codeblock will start and end on its own line, %insert:after will insert a CRLF and then the codeblock immediately after the target file codeblock provided in the preceding %location instruction.
[back to top]
%insert:before%
before - tells mod manager to insert the codeblock into the target file before the preceding %location codeblock. The only other possible value for this argument is 'after'.
Purpose is to insert a codeblock of text before a block of existing code in an open target file.
Example:
insert:before%
[block of code to insert]
%end:%
Example:
insert:before%
[block of code to insert]
%end:%
- Mod Manager will not list or execute this instruction if its target file cannot be opened.
- This instruction must be placed immediately after a %location:% codeblock.
- %insert:before% must be followed on the next line of the mod config file by a codeblock containing the text or code to be inserted.
- The required codeblock must be unique in the target file; if not, if the code will create a duplication in the target file, and Mod Manager will throw an error in the Mod Listing with a status of Cannot Install.
- To ensure the inserted codeblock will begin and end on its own line, %insert:before% will insert the codeblock and CRLF immediately before the target file codeblock provided by the preceding %location instruction.
[back to top]
%label:label_name%
label_name is the name of the label and is required.
Purpose is to provide a landing place for skipped MM instructions.
Examples:
%label:done%
%label:skip_cenproc%
%label:132%
- The argument’s label name must be unique.
- %label serves as a target for the %goto or other conditional instructions.
- %label location must be after targeting location. Attempts to target a label before the targeting location will result in an error.
[back to top]
%location:note%
note is optional and places a small note with the %location instruction in the Mod Manager Mod Listing.
Purpose - to provide some code in the target file that can be used as an anchor for inserting or replacing text (new code). It must be followed on the next line by a unique block or fragment of code from the target file, and terminated on the next line with an %end instruction.
Examples
%location:set first parameter%
%location:%
- The argument is optional, a note introduced in TNGv12 to be dispayed in the TNG Mod Listing.
- %location, its codeblock and the following instruction and codeblock will all be bypassed if there is no open target file.
- %location must be followed by a codeblock matching code in an open target file.
- The %location codeblock and any included white space (tabs and spaces) must exactly match code and white space in the target file, and it must be unique (only one occurrence) in the target file; otherwise Mod Manager will throw an error in the log and in the mod listing.
- In TNGv15, Mod Manager does not compare leading or trailing white space. However, white space within a codeblock must match exactly. You should keep this in mind when considering backward compatibility of your mods.
- A %location codeblock must be immediately followed by a text altering instruction.
[back to top]
%mkdir:dir_path%
dir_path is a TNG root-relative path to the folder being created.
Purpose is to recursive create a directory. The deepest directory will be created along with any directories preceding it if they do not already exist.
Examples:
%mkdikr:admin2%
%mkdir:languages/Esperanto%
- %mkdir requires one argument – a directory path.
- The directory path will be created relative to the TNG root directory.
- The first part of the past may already exist and will not be affected.
- %mkdir will create a new directory path that may be several levels deep.
- Parts or all of the path may already exist without causing an error.
- When uninstalling, %mkdir will remove directories starting with the deepest, and only then if they are empty, if they contain no files or other directories. In the second example given above, the language folder already exists with content. The instruction will create a new folder named 'Esperanto' and the mod will presumably copy files to that folder. When removed, Mod Manager will remove the copied files from 'Esperanto' and then the 'Esperanto' folder. It will not remove 'languages' because it still contains content.
- Status of directories removed or left intact will be noted in the MM log.
[back to top]
%modvar:target-string:replacement-string%
target-string is a string to be replaced everywhere in the file with the replacement-string.
replacement-string is a string to replace all occurrences of the target-string.
Example:
%modvar:{{version}}:v15.0.1.2%
%copyfile:mymod_{{version}}/favicon.ico:img/favicon.ico%
As an instruction %modvar is more of a pragma in that it directs the parser to do all the replacements prior to parsing the mod config file.
If a mod configuration has many %copyfile instructions which require a mod version number, for example, and other text containing the mod version number, using %modvar in place of the actual version number simplifies upgrading to a new version and ensures none of them will be overlooked. Just change the value in argument two and it's done.
- Requires two arguments
- Arg 1 can be any unique string
- Arg 2 will replace any occurrence of Arg1 by MM prior to parsing.
[back to top]
%name:mod_name%
mod_name is the name of the current mod.
Purpose is to provide a name for the Mod Manager Mod Listing and all other users who need to refer to it.
Examples:
%name:Living Color%'
%name:image_captcha mod%
- %name is a required instruction; if missing, Mod Manager will throw a fatal error in the mod listing with a status of “Cannot Install”.
- mod name may contain spaces.
- For clarity, the mod name and the mod configuration file name should be alike.
- Do not use quotes.
[back to top]
%newfile:file_path%
file_path is a path to a new file, relative to the TNG root directory. The folders in the path must exist; if they don't use the %mkdir instruction to create them.
Purpose is to allow Mod Manager to create a brand new file with custom content. When the mod is uninstalled the new file will be removed.
Example:
%newfile:languages/Esperanto/text.php%
%fileversion:v14.1.0.0%
<?php
//%version:v14.1.0.0%
$text['hello'] = "saluton mondo";
$text['bye'] = "ĝis revido";
?>
%fileend:%
- %newfile requires one argument, the file path for creating a new file.
- The %newfile instruction must be followed immediately by a %fileversion instruction, and %fileversion must be followed immediately by a codeblock with the contents of the new file.
- The codeblock must contain a comment with the file version in the form of a %version instruction.
- The file %version argument must match the %fileversion argument; if not, Mod Manager will throw a fatal error and the mod listing status will be “Cannot Install.”
- The codeblock must be terminated with an %end:% instruction.
Important Note: Using %newfile may be problematic if you are creating language support files. Files are created using the website's character set, which may not suit the language in the support file. In this case it is best to create and save language support files in the correct character set for the language, then use %copyfile to place them in the languages folder. Copying them will not change their encoding.
[back to top]
%note:text%
text is a short message that will be included in the Mod Manager Mod Listing.
Purpose is to allow developer to show a short note in the Mod Manager Listing on an unopened (unexpanded) Mod. It is very similar to the %private instruction, except it doesn't tag the mod as being private.
Example:
%note:Not published%
- The %note instruction requires one argument – the text of the note to be placed in the mod listing.
[back to top]
%parameter:$variable:value%
$variable is the variable as found in the target file whose value assignment will be updated;
value is the value assigned to the $variable in the target file.
Purpose is to provide a way to modify a target file, normally with a flag whose value will determine a course of behavior. It is also used to set operating parameters, such as the number of days to keep a dated log file.
Example:
%parameter:$startyear:2005%
%desc:First year of copyright [no quotes]</br>
Defaults to none ()%
- A parameter is defined as a PHP variable in an open target file whose value may be changed by a user via the Modeditor.
- A %parameter instruction requires two arguments: the variable to acted upon in an open target file, and the value assigned to it.
- A %parameter must be an assignment statement in the target file in the form of $variable = value.
- If there are several assignment statement in the same target file, only the first one will be targeted for change. The same variable in any other context will not be recognized.
- A parameter $variable in a target file may be native to the file, or may be placed there using an appropriate Mod Manager instruction.
[back to top.
%private:text%
text is a short message to be placed after the word Private in the unopened, unexpanded listing for a mod.
Purpose is to allow a developer to identify his mod for his own 'private' use. A short note can be added.
Examples:
%private:%
%private:Do not release%
- %private may have zero or one argument.
- %private shall insert a highlighted text – “Private” into the description of the mod in the mod listing.
- If present, an argument will contain additional text for the listing.
[back to top]
%range:low_limit:high_limit%
low_limit is the range's lower limit (inclusive).
high_limit is the range's upper limit (inclusive).
Purpose is to allow a mod developer to specify a list of allowable entries into a Mod Manager Options Editor field. Values outside the range will be ignored, thus preventing nonsensical values to be assigned to target file variables (parameters).
Example:
%parameter:$PRO_ERRLEVEL:9%
%RANGE:0:9%
%desc:Set Error Level for Reporting. Error Level indexes are additive. To show Errors, Warnings and Deprecated, enter 5 (0+1+4).<br /><br />
0 == ERRORS<br />
1 == WARNINGS<br />
2 == NOTICES<br />
4 == DEPRECATED<br />
9 == ALL<br />
default (0)%
- %range is an optional instruction to restrict Modeditor within a range of numerical values.
- If used, a %range instruction must be placed between a %paramter and its %desc instruction, and will serve to restrict to that particular parameter’s input in the Modeditor.
- If user enters a value outside the range, Mod Manager ignores it and keeps the previous value with no explanation or warning.
- Naturally the default value for the parameter must fall withing the specified range.
- Do not use quotes.
[back to top]
%replace:%
Purpose is to replace one block of code in a target file with another. %replace always follows a %location code block.
Example
%replace:%
[block of code]
%end:%
- The %replace instruction must immediately follow a %location instruction and its codeblock, consisting of an entire block of text to be replaced in the open target file.
- %replace is a content altering instruction requiring a codeblock to immediately follow it on the next line of the mod configuration file.
- Mod Manager will replace the %location codeblock with the %replace codeblock in an open target file.
- Mod Manager does not compare codeblock leading and trailing spaces and tabs. The same codeblocks in the target file with different leading spaces and tabs will not be considered unique.
- If there is no open target file, Mod Manager will ignore this instruction in the mod listing.
[back to top]
%target:file_path:note%
file_path is the TNG root relative path to a file to be opened, possibly for revision.
note (TNG12) is optional, but can contain a short message to be added to the mod item in the listing.
Purpose is to open a target file for Mod Manager processing -- installing or removing code. A target file must be opened before any instructions that modify it can be executed.
Examples:
%target:@languages/English-UTF8/text2.php:may not exist% <-- note the 'optional' flag
%target:admin.php%
- Optional note (argument 2) introduced in TNG12.
- If the target file is missing or inaccessible and is not flagged Optional or Provisional, Mod Manager throws a fatal error and shows “Cannot Install” in the mod listing.
- file_path may be flagged Optional (@file_path) or Provisional (^file_path). See Flags for more information.
[back to top]
%tngverson:low_limit:high_limit:goto_label%
low_limit is lowest acceptable TRNG version (inclusive).
hight_limit is the highest acceptable TNG version (inclusive)
Conditional
Purpose is to allow a mod to determine if it can be installed in the user's current version of TNG. If the version is outside the limits, the mod will usually create a new %description instruction with the information about why it cannot be installed.
- %tngversion is a conditional instruction that examines the current TNG version number to determine if it falls within the range given in arguments one and two. If it does, processing will jump to the %goto label; if not it will drop through to the next config file instruction.
- The label must exist in the mod configuration file after this instruction; if not found, Mod Manager will throw a fatal error in the listing.
- This instruction converts the actual TNG version into a four-digit number for comparing against the requested range.
[back to top]
%textexists:goto_label%
goto_label is the argument to a %label instruction to which the instruction will jump if the condition is true - that the text exists in the open target file.
Purpose is to determine if a block of text exists in the currently open target file; in otherword, it must come after a successful %target instruction.
This instruction must be followed immediately by a codeblock or fragment expected to be in the open target file and then terminated with %end:%
Example:
%textexists:skip_insertion%
if($count) {
echo $count;
}
%end:%
...
...
%label:skip_insertion%
- %textexists must have one argument and must be followed by a codeblock, followed by an %end instruction.
- %textexists is a conditional instruction that checks to see if the associated codeblock is found in the open target file. If it is, processing jumps to the label given as argument one; otherwise, processing drops through to the next instruction after its codeblock in the mod config file.
- If no target file is open, this instruction will be ignored (bypassed).
- The goto label must exist in the mod configuration file after this instruction; if not found, Mod Manager will throw a fatal error in the listing.
- If the codeblock exists in the open target file, the parser jumps to the goto label to continue building the parse table.
- If the codeblock does not exist, the parser continues building the parse table from the next instruction after the codeblock %end instruction in the mod configuration file.
[back to top]
%triminsert:after%
Purpose is to insert a text fragment into a unique string of code in an open target file.
Example:
%location:%
global $admtext
%end:%
%insert:after%
, $state
%end:%
In the example, if the original text is
global $admin;
the new text will be
global $admin, $state;
- This instruction must immediately follow a %location instruction.
- %triminsert:after is a text altering instruction. It has one argument to tell Mod Manager to insert a text fragment after the %location text with no separating CRLF.
[back to top]
%triminsert:before%
Purpose is to insert a text fragment into a unique string of code in an open target file.
Rule: Mod Manager trims trailing spaces after code fragments.
It does not trim leading spaces in fragments.
Example:
%location:%
$admtext, $user, $tngrole;
%end:%
%insert:before%
$rootpath,
%end:%
In the example, if the original text is
global $admtext, $user, $tngrole;
the new text will be
global $rootpath,$admtext, $user, $tngrole;
Even if you insert a space after the code fragment ($rootpath, ), Mod Manager trims the trailing space, so that the first and second arguments run together in the result. Operationally, this works fine, but it may not be satisfying code. Mod Manager does not trim leading spaces in your target code, so to overcome this, we can include the leading space in front of the target fragment.
%location:%
$admin, $user, $tngrole;
%end:%
%insert:before%
$rootpath,
%end:%
Notice the leading space in the target code before $admin. Now the resulting code will be:
global $rootpath, $admtext, $user, $tngrole;
- This instruction must immediately follow a %location instruction.
- %triminsert:after is a text altering instruction. It has one argument to tell Mod Manager to insert a text fragment after the %location text with no separating CRLF.
[back to top]
%trimreplace%
Purpose to replace a unique target file code fragment with a different fragment.
Example:
%location:%
$admtext, $user, $email
%end:%
%trimreplace:%
$admtext, $rootpath, $user, $email
The original and resulting strings might look like this:
original: global $admtext, $user, $email, $country;
replacement: global $admtext, $rootpath, $user, $email, $country;
- %trimreplace is a file text altering instruction. It has no arguments, but must have a codeblock (fragment) immediately following it.
- The replaced code must be unique in the target file. Otherwise Mod Manager would not know which fragment to uninstall.
- This instruction must immediately follow a %location instruction.
- %trimreplace replaces the %location text “inline” with its own text with no separating CRLF added at the beginning or end of it.
[back to top]
%version:mod_version%
mod_version is the version of the current mod.
Purpose is to identify different versions of the same mod and handle them appropriately.
Example:
%version:14.0.5.8%
- For clarity, the version number should contain the version of TNG it was developed under and the sequential version of the mod itself. In the example, the mod was developed using TNGv14.0.5, and is the 8th version or release of the mod. This version may or may not be backward compatible with previous versions of TNG. That information can be provided in the mod %description and/or in the TNGWiki article from which it is downloaded.
- This is a required instruction. If missing Mod Manager will display a “Cannot Install“ error in the mod listing.
- Do not use quotes.
[back to top]
%vinsert:after%
Purpose is to allow a variable assignment ($var='value';) to be inserted into a target script and subsequently, still recognize it as installed, even if it's value has changed. Mod Manager will only search for the variable ($var =) and ignore the value to determine if it has been installed. Using the %insert instruction would show the variable as not installed if its value has changed, resulting in a "Partially installed" mod.
- %vinsert:after inserts parameter variables into an open target file.
- %vinsert:after requires one fixed argument – `after` – to locate the code insertion point in the target file.
- %vinsert:after must immediately follow a %location instruction.
- Validation of %vinsert:after variable assignments will not consider the value of the assignment, only the assignment string up to and including the equals sign (=).
- %vinsert:after must be immediately followed by a codeblock containing the text to be inserted after the %location codeblock in the open target file.
- %vinsert:after codeblock may contain multiple variable parameter assignments; however,
- parameters must each be on a line by themselves and must be first thing on the line other than white space, both here and in the target file.
- arguments must be variable assignment statements only, for example, $var=1. Other lines with code or comments are ignored.
[back to top]
%vinsert:before%
Purpose is to allow a variable assignment ($var='value';) to be inserted into a target script and subsequently, still recognize it as installed, even if it's value has changed. Mod Manager will only search for the variable ($var =) and ignore the value to determine if it has been installed. Using the %insert instruction would show the variable as not installed if its value has changed, resulting in a "Partially installed" mod.
- %vinsert:before inserts parameter variables into an open target file right before the code in the %location instruction.
- %vinsert:before requires one fixed argument – `before` – to locate the code insertion point in the target file.
- %vinsert:before must immediately follow a %location instruction.
- Validation of %vinsert:before variable assignments will not consider the value of the assignment, only the assignment string up to and including the equals sign (=).
- %vinsert:before must be immediately followed by a codeblock containing the text to be inserted before the %location codeblock in the open target file.
- %vinsert:before codeblock may contain multiple variable parameter assignments; however,
- parameters must each be on a line by themselves and must be first thing on the line other than white space, both here and in the target file.
- arguments must be variable assignment statements only, for example, $var=1. Other lines with code or comments are ignored.
[back to top]
%wikipage:wiki_title%
wiki_title is the URL title of a TNGWiki article from which the mod may be downloaded.
Purpose is to provide a link to a download pager where the mod is explained in detail. Clicking on the wiki link, a big 'W' in the Mod Manager Mod Listing, opens the article in the TNGWiki.
Example:
%wikipage:Living_Color_Mod%
- Instruction is optional.
- This instruction requires a single argument – the title of a TNGWiki article.
- The URL of the TNGWiki is automatically prepended to the article path, so only the path on the TNGWiki is required.
- Mod Manager converts the argument into a URL link to the named article in the TNGWiki.
- The link will be displayed in the mod listing as a clickable icon in the Wiki column.
[back to top]
