Mod Manager Syntax

From TNG_Wiki
Jump to: navigation, search
Caution Note that the Mod Manager deals strictly with text. It does not understand PHP or any other code. Caution


This article explains the method of writing config files for the Mod Manager.

A config file is a text file with extension .cfg prepared with a simple text editor such as Notepad++ (not Word). It provides an automated method of making changes (mods) to the TNG system which can easily be reversed if the changes are not required or when upgrading your system.

Overview

TNG mods are distributed as zip archives, The distributed zip archive must always contain a .cfg file, and may contain a subfolder with other files that can be copied to TNG folders. The zip files should be uploaded to the TNG wiki so that the mod will not be lost if your site goes away. If you want to track downloads of your mod then install Bart Degryse's Click Counter II add on on your site. See Using Click Counter II

Mod config files consist of a mod heading or introduction, and then one or more sections which relate to different files.

Syntax is strict but flexible. It uses a series of directives which all start and end with a "%" character. Directives start at the beginning of the line and apart from the "description" directive, they are limited to one line. They consist of a keyword followed by ":" and other text. e.g. %target:getperson.php%

Extra text or layout characters can be used in most places in the file to explain and guide the human reader: in fact almost everywhere except in the lines:

  • between a %location:% directive and the %end:% following it.
  • between an %insert:%, %replace:% or %newfile:% directive and the %end:% following it.

These two sets of "brackets" enclose all the text that is to be searched for or inserted into the php and other files by the mod manager. There are no "comment" symbols.

Each section starts with a "%target:%", which is a file to be modified. There must be at least one target in the file.

TNG version: 11.0.2
Starting with TNG 11.0.2, if the %target is the extensions folder, you can use the TNG variable for the extensions folder which allows the folder to be renamed to specify the target as
%target:$extspath/myscript.php%

The config file heading

The heading specifies the module's name (which should be closely related to the module's filename), the mod version number, and a description. The corresponding directives are

  • %name:mod name%, where the name often consists of two or three words and should match the TNG Wiki article for the mod.
  • %version:x.x.x.y%, where the first three period-parts represent the lowest TNG version number supported by the mod, and the final number represents the mod version number. e.g. 10.0.3.1.
  • %description:description text%. The description can be (really, should be) a few lines long, and include HTML commands. The description should include the author's name.
TNG version: 12.0.0
the $modspath and $extspath can be specified in the description text to allow module to be executed from either the mods or extensions directory
TNG version: 10.1.0
  • %wikipage:name_of_TNG_Wiki_article% places an icon in the mod listing that serves as a link to a supporting article in the TNGWiki. Any spaces between words in the title of the article be replaced with underscores. Thus, Living Color Mod must be rendered as Living_Color_Mod.
TNG version: 12.0.0
TNG v12 added new heading tags:
  • %author:name:TNG_wiki_link% which can replace the Mod Developer line in the %description:
shown in the first line of the expanded mod status before the %description
multiple %author: tags can be specified and will be combined in one line
the TNG Wiki URL is optional
  • %note: note text% can actually be any place in the cfg file
will show as part of the top line of the mod status
  • %private: with not text% can be used to flag a Private or personal mod that is not distributed.
Also shown in the top line of the mod status

Note that each directive - even the multi-line description - starts with %, includes a colon immediately after the keyword, and is terminated by a percent sign (%).

Heading Example

%name:Cemeteries Admin List%
%version:v9.2.0.3%
%description:This mod adds columns to the Cemetery selection table in the Cemeteries admin function, 
and adds fields to the search form to control what gets displayed.<br/>;
Mod developer is Robin Richmond.%
%wikipage:Cemeteries_Admin_List%

The version number of 9.2.0.3 indicates that the minimum TNG version supported by the mod is v9.2.0, and that this is version 3 of the mod. The description - as is typical - identifies the mod author on a separate line, and links to the mod's Wiki article with a simple HTML hyperlink. Note the percent sign at the very end of the heading that terminates the description.

Mod Sections

Each "section" of the mod config file starts with a %target keyword, which has one parameter that is generally a filename (typically a php module). To indicate that you want to change the file placesearch.php in the main TNG folder, specify:
%target:placesearch.php%

You can modify many files with one mod; that is, you can have as many sections in a mod as you need.

A section ends when a new section is encountered or end-of-file is reached. There is a dummy target designated %target:files% used for other file operations. See Copying Entire Files below.

If the file that you are trying to modify is optional (i.e. if it is ok if the file is missing), then you should place the '%fileoptional:% directive just below the %target: specification to avoid generating an error that the file does not exist. This is common with translations.

TNG version: 12.0.0
The optional flag @ can be used before the path/filename instead of the %fileoptional:% directive.

TNG v12 also allows a note to be added to the %target: section keyword that will be printed in the status column detail.

Locations of change

A place within the target file where a change is to be made is known as a location, and is identified by the keyword %location:%, followed on a new line one or more lines of text (the search text) that is expected to be in the file being changed, followed on a new line by %end:%.

Very Important! Your search text must be unique in the target file so Mod Manager knows where to install the modification, and your inserted text must be unique in the target file so Mod Manager knows what to uninstall. If they are not unique, the Mod Manager will flag up the problems and refuse to install the text.

Note that although the search text is on a separate line or lines in the config file, it doesn't have to start or finish at the end of the line in the target file. It could identify a single word in the middle of a line. But it must single out one location in the target file. A mod cannot, for example, change all occurrences of "this" to "that".

For example, a simple target and location specification, commonly used to identify an insertion point in the main TNG style sheet, genstyle.css, is

%target:css/genstyle.css%
**** genstyle.css location 1 ***
%location:%
/* Classes for TNG Mods to be added below */
%end:%

Note that

  1. The target directive specifies the path and file name relative to the TNG main folder.
  2. The line between %target: and %location is simply a mod comment.
  3. In this case, the search text is a single line of text. The mod expects the text /* Classes for TNG Mods to be added below */ to be somewhere in css/genstyle.css.
  4. There should be no white space in the %target:value% expression. While Mod Manager is somewhat forgiving, the following -- %target: css/genstyle.css% (space after the colon) -- is considered to be a syntax error and will be so flagged by the Mod Developer Tools mod syntax checker and may prevent installation of the mod in the future.

In comment space above each  %location: directive, the mod programmer should include a comment that at least lists the location number within the target file, and that, ideally, describes the change succinctly. See Mod Comments below.

TNG version: 12.0.0
TNG v12 also allows a note to be added to the %location: keyword that will be printed in the status column detail.

Placement Directives

A mod file placement directive instructs the Mod Manager to place new text before or after the search text, or to replace the search text. It must be placed after the %end:% keyword that terminates the search text. The new text must also be terminated with an %end:% keyword. The inserted text must be unique within the target file. If necessary, add an end-of-line comment in the text to achieve this.

The placement directives are of two types -- block (complete lines) and inline (starting in the middle of a line without causing a line break).

Important: for every location there must be exactly one directive. If you want an insert:before and an insert:after a location then you will need two %location:% statements.

Block Directives
  • %insert:before% inserts text before the lines
  • %insert:after% inserts text after the lines
  • %replace:% replaces complete lines

Mod Manager will insert text before (above) or after (below) the lines containing the most recent location string found. The new text will be placed on its own line(s) even if the location string is not a complete line.

However, when replacing text, the target must consist of complete lines of text, not partial lines, or Mod Manager will issue an error.

Example of a block operation:

%target:genlib.php% 
%location:%
    initMediaTypes();
%end:%
%insert:before%
//== Inserted by mod living_color ==//
$title = preg_replace("#(<(span.*?)>|</span>)#i", "", $title);
//== end of living_color insertion ==//

%end:%

Note that four lines (including a blank line) will be inserted before the indented location in target genlib.php. Also notice the optional PHP comments (starting with double forward slashes) to explain how the text got there.

Caution: The %replace:% option should be avoided if possible as it can potentially bring a mod into conflict with other mods which reference the same text.

Inline Directives
  • %triminsert:before% inserts text before the matched text
  • %triminsert:after% inserts text after the matched text
  • %trimreplace:% replaces the matched text

Inline directives are used for modifying part of a line of text. e.g. adding an extra parameter to a list.

If you include surrounding whitespace in the location it must exactly match the text string in the target file. Mod Manager does not delimit text with quotes or other markers. Spaces at the beginning of the either location or insertion are clear—they can be seen. But at the end of a line they are not visible, and may not even be there. So avoid including a trailing space, either in the location or in the op text section of your cfg file.

For example, given a fragment of a line:

type 1, type 2, type 3, type 5, type 6" 

where you want to insert the missing value, "type 4, " in the list, don't choose as your target:

type 1, type 2, type 3, 

or you are asking for trouble, because that space after the 3, could easily disappear.

Instead, make your target

type 1, type 2, type 3

then %triminsert:after%

, type 4

at the end. No trailing spaces needed.

Putting it all together:

%target:extensions/random_numbers.php
%location:%
type 1, type 2, type 3
%end:%
%triminsert:after%
, type 4
%end:%
TNG version: 11.0.2
Starting with TNG 11.0.2, if the %target is the extensions folder, you can use the TNG variable for the extensions folder which allows the folder to be renamed to specify the target so the example would be
%target:$extspath/random_numbers.php
%location:%
type 1, type 2, type 3
%end:%
%triminsert:after%
, type 4
%end:%

will result in the modified text being "type 1, type 2, type 3, type 4, type 5, type 6".

TNG 10.1 is a bit more strict, so you may have to update some of your earlier mods to change %triminsert: or %trimreplace to use the block operands (%insert: or %replace:) so that your mod text segments are installed and removed correctly.

As a simple rule:

  • use %trim (inline) only when dealing with partial lines in the %location:
  • use %insert or %replace (block) when dealing with full lines in the %location
  • inserted text string must be unique. See Mod Manager gotchas on how to deal with this requirement

Multiple Target Locations

You may repeat the search text/ placement directive/ new text sequence as many times as necessary to make all of the required changes to the target file. Each location requires

  1. %location:%
  2. text to find
  3. %end:%
  4. a placement directive
  5. new text
  6. %end:%

Remember that any other text before %location:% or the placement directive is ignored.

Translations

If languages other than English are supported by mods, then it is necessary to make modifications to two sets of files: those in the languages/xxx-UTF8/ folder and those in the languages/xxx/ folder, where 'xxx' is a language such as 'German'. These generally are added in the corresponding cust_text.php file. For languages that contain characters outside the normal ASCII range, e.g. 'é', it's not possible to have a text file with two different encodings. There are two possible solutions:

  1. Use html entities such as &eacute; consistently throughout both texts.
  2. Construct only the version that you are normally using, whether it be the UTF or ISO-8859-1 (or ANSI encoding in Notepad++) and use a tool such as the UTF-8 translator to provide the UTF-8 or ISO-8859-1 versions.

Note that you must save the .cfg file in the correct encoding (UTF-8 without BOM or ANSI in Notepad++) for the legible accents not to get mangled on install.

Note also that TNG alltext.php includes the English or English-UTF8 cust_text.php file if the language specific file cust_text.php is not found. So if a language is omitted, then it will get the English version by default.

Copying Entire Files

A mod may create new files two ways - either by copying them from a subfolder that is distributed with the mod config file, or by specifying their contents directly in the mod file.

Whichever method you use to create files, Mod Manager can only create new TNG files where none existed before. You cannot overwrite an entire existing file (or Mod Manager would have no way to reverse its action). If you want to modify an existing file - even replace all of its contents, you must use a  %target% section with search text and new text.

TNG version: 10.0.3

New files must come after the first %target:% directive. As it was impossible prior to TNG v10.0.3 to have a config file with only entire files copied, there is now a special version, %target:files%, which allows you to do this. It can also be used to place the file copy section before any other mods.

Within any mod file section, you may include these three directives:

  • %copyfile:file1.ext% — copy a file to the TNG root folder
  • %copyfile2:file1.ext:file2.ext% — copy a file to another TNG folder
  • %newfile:file.ext% — copy text from the cfg to the TNG root folder

Using %copyfile%

The only file specification in the %copyfile: directive is a reference to the file being copied, e.g.

%copyfile:abracadabra/magicwand.php%
will copy the file magicwand.php from the abracadabra folder (inside the mods folder) to the main TNG folder. The folder name abracadabra is an appropriate name for new file subfolder associated with a TNG mod called Abracadabra, where the mod config file's name would be something like abracabra_v10.1.1.5.cfg, and the corresponding distribution file would be abracadbra_v10.1.1.5.zip.


TNG version: 10.0.3
NOTE: If you attempt to copy a file to a different folder using the %copyfile: directive, you will get an error message that indicates that the Local Copy of the file is Missing

Similarly, if you specify the path using a backslash (Windows path syntax) rather than a forward slash (web path syntax), you will also get the Local Copy of the file is Missing error message.

In either case, the file being copied should be in a subfolder (below the mods folder) that was zipped up with the distributed config file. (It is possible for the distributed zip file to place a new file or two directly in the mods folder, and some older mods work this way. But, to keep each TNG site's mods folder under control, all new files to be installed by mods should be in subfolders.)

Using %copyfile2

With  %copyfile2, you specify the source path and filename and the target path and filename. Use a colon to separate the two file specifications. The source path is relative to the mods folder, and the target path is relative to the main TNG folder.

For example,

%copyfile2:abracadabra/magicwand.gif:gifs/magicwand.gif%
will copy the file magicwand.gif from the abracadabra folder (within the mods folder) to the gifs/ folder in the main TNG folder.
TNG version: 11.0.2
Starting with TNG 11.0.2, if the destination folder is the extensions folder, you can use the TNG variable for the extensions folder which allows the folder to be renamed to specify the copyfile2 destination as
%copyfile2:abracadabra/magicwand.php:$extspath/magicwand.php%

Using %newfile

Besides using %copyfile:% or %copyfile2% to install new TNG files, the Mod Manager also allows you to specify the contents of a new text file (e.g. a PHP or CSS file) within the mod config file. To do, use the %newfile directive, which must specify the path and filename of a new file. The path is relative to your main TNG folder. For example, to create a file named 'myscript.php' in the extensions folder, specify:
%newfile:extensions/myscript.php%
TNG version: 11.0.2
Starting with TNG 11.0.2, you can use the TNG variable for the extensions folder which allows the folder to be renamed to specify the newfile as
%newfile:$extspath/myscript.php%
A %fileversion:% directive MUST come next, to give the created file a version number that the config file can track. In practice, you should use the same version number as the mod version. For instance, if your mod was developed and tested for TNGv10.1.0, and it is the mod's second version, the %fileversion:% directive should be set as follows
%fileversion:v10.1.0.2%

Content for the new file is added after the %fileversion:% directive. Somewhere near the top, the new file content must contain a PHP or HTML comment line with a %version:% directive and the same version number as the %fileversion:% number given above. A new php module would look like this:

<?php
// %version:v10.1.0.2%
... new file content ...
?>

If you are creating a pure HTML file the comment would look like this:

<!-- %version:v10.1.0.2% -->

If the commented version number is missing from the new file content, or if it does not match the %fileversion:% directive, Mod Manager will throw an error and won't finish installing the mod.

Finally, content for the new file must be closed with a %fileend:% directive.

Here is a complete example of how to create a new file with Mod Manager:

%newfile:extensions/myscript.php%
%fileversion:v10.1.0.2%
<?php
// %version:v10.1.0.2%
echo "hello world!";
?>
%fileend:%
TNG version: 11.0.2
Starting with TNG 11.0.2, the complete example can be specified as
 %newfile:$extspath/myscript.php%
%fileversion:v10.1.0.2%
<?php
// %version:v10.1.0.2%
echo "hello world!";
?>
%fileend:%

Using %target:files%

As mentioned above, the %target:files% directive creates a mod file section which can have  %newfile%, %copyfile%, and %copyfile2% directives. It cannot have %location:% or %insert:% directives. With the  %target:files% directive, mod authors can create mods that don't change any existing files, and only add new files to TNG.

%target:files% is also useful to isolate all %newfile%, %copyfile%, and %copyfile2% directives especially if the preceding section contains a  %fileoptional:% section which would bypass the installation of the file creation or copy.

Suppressing Copy Errors

TNG version: 10.0.3

Some site administrators pare down their TNG site by removing language or templates folders they do not use. If a mod contains files that are intended for a particular language or template folder that does not exist on such a site the mod manager will generate an error. i.e. Mod Manager will not create folders; it will only create files in existing folders. Such an error can be suppressed by the Mod author by placing an @ symbol at the beginning of the %copyfile% or  %copyfile2% source file name. The @ symbol indicates that the file is optional, and if the site on which the mod is being installed doesn't have a place to put that file, fine; the file is ignored.

%copyfile2:@abracadabra/magicwand.gif:gifs/magicwand.gif%
TNG version: 10.1.0

Starting with TNG 10.1, the @ optional operand can be used with the copyfile or copyfile2 to resolve a problem when a font file cannot be removed because it is in used by the web server on a Windows environment. For example, the following can be used in the Google Maps - More Place Levels mod to prevent or suppress the error when removing the LiberationsSans-Regular.ttf font that Windows will not allow you to remove because it is in use.

%copyfile2:@gmaps_add_4_placelevels/LiberationSans-Regular.ttf:font/LiberationSans-Regular.ttf%

The above will also allow you to install the mod, even though the font file is still present on the system.

Edit Parameters

Edit Parameters, which are associated with a specific target file, allow the person installing the mod to control some of the mod's functionality. They are only updated from the mod manager after a module has been installed. What they allow the user to do is to update the first assignment to a particular variable in a php file by filling in a different value.

They are implemented using two extra directives: %parameter and %desc. Here is an example:

%target:bot-trap/settings.php% 
%fileoptional:% 

        Allow editing of Bot-Trap mod options 
%parameter:$mail_on_add:false% 
%desc:<div style="text-align: left;"><font color="blue">Send an email alert when a new IP 
address is ADDED to the bot-trap.</font><br />Yes: true<br />No: false<br />default: (false)</div>% 

In this case, the settings.php file is installed as part of the mod, so it is declared optional so that installation can proceed. The parameter is "$mail_on_add" and its current (initial) value is false.

After installation, an extra "Edit Options" button will appear in the mod's box. Clicking on this will allow you to change the options.

Modmanager option.png

The user may then change 'true' to 'false' in the box (see below) to suspend the sending of emails and click the 'Update' button. This updates the first occurrence of "$mail_on_add" in the settings.php file to:

$mail_on_add = false;

and also changes the .cfg file to reflect the new value. This means that if a user uninstalls and reinstalls the mod, the setting will remain unchanged.

Modmanager choicebox.png If the value in the box is a string, the Mod Manager will put quotes around it in the assignment statement. It does not apply any other checks to the value so the programmer should be careful with the choice.

Clicking on the "Restore Default" button uses the string enclosed by the first parentheses in the description, in this case indicated by "Default: (true)".

TNG version: 10.1.0

before

Starting with TNG 10.0.3 there are no limitations to the number of parameters for any particular file, or the number of files with parameters. Before 10.1 it was also necessary to specify at least one edit action for that file. See Mod Manager - Edit Parameters - prior to TNG 10.1 for details.

Updates

TNG version: 10.0.3
Starting with TNG 10.0.3, the Mod Developer Tools Syntax checker can be used to find syntax errors in mods, such as a white space after a colon that could prevent the mod from being installed in a future version of the Mod Manager


TNG version: 10.1.0
With TNG 10.1, the Syntax Checker from the Mod Developer Tools was incorporated into the Mod Manager and the syntax rules were tightened. You can now only use %trim... directives on a single line within a file. See Mod Manager gotchas that provide more information on where you may need to update your mods.

Related Links

Mod Manager

Mod Manager Controls

For Mod Developers

Technical

Developer Tools

Example Mods