Difference between revisions of "Mod Manager Syntax"

From TNG_Wiki
Jump to navigation Jump to search
m (21 revisions: Mod Manager Updates for TNG V10.0.3)
Line 177: Line 177:
  
 
[[Mod Guidelines]]  
 
[[Mod Guidelines]]  
 +
 +
[[Mod Manager Syntax]]
  
 
[[Mod Developer Quick Reference]]
 
[[Mod Developer Quick Reference]]
Line 190: Line 192:
 
[[Notepad++ Mod Manager Language]]
 
[[Notepad++ Mod Manager Language]]
  
[[Category:Programmer]]
 
 
[[Category:TNG Mod Manager]]
 
[[Category:TNG Mod Manager]]

Revision as of 14:13, 13 June 2014

This article attempts to explain the Mod Manager config file structure and syntax

High-Level Structure

A TNG mod is implemented through a "config file", which is a text file with the file name extension ".cfg". Mod config files consist of a mod heading or introduction, and then several "sections". Each section refers to a "target", which is a file to be modified.


TNG version: 10.0.3

Starting with TNG V10.0.3, the new keyword %target:files% identifies a section that contains instructions to copy files and or create new files without changing an existing module.

Within a section, a mod can

  • Specify Mod Parameters, which allow the installer to control aspects of the behavior of the mod.
TNG version: 10.0.3

Note that only one target file can have parameters.

  • Specify locations where changes are to be made, and the new text to be places at each location,
  • Specify new files that are to be copied from a subfolder that must be supplied along with the mod.
  • Specify new files whose contents are contained in the mod itself.

TNG mod commands, known as "directives", always start and end with a percent sign. A colon following the keyword directive is required and should not be followed by a blank. Many directives have one or two arguments.

The mod 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 are

  • %name:{some name}%, where the name often consists of two or three words. The corresponding filename would use underscores to separate the words, and be all lower-case.
  • %version: {4-part version number}%, 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.
  • %description:description text%, which can be several lines long and include HTML commands. The description should include the author's name and a hyperlink to a TNG Wiki article about the mod.

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<br>
TNG Wiki article: 
<a href="http://tng.lythgoes.net/wiki/index.php?title=Cemeteries Admin List" 
target="_blank">Cemeteries Admin List</a>%

Note that this version number 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. The description must be followed by a colon and be terminated by a percent sign.

Mod Sections

The target, that is, a file to be changed, is identified by the %target keyword, which takes a filename (typically a php module) as a parameter. For instance, to indicate that you want to change the file placesearch.php in the main TNG folder, specify:

%target:placesearch.php%</nowiki>

Mod Parameters

TNG version: 10.0.3

One section (one target file) in each mod may have Mod Parameters, which allow the person installing the mod to determine some of the mod's functionality. See Mod Manager - Edit Parameters.


TNG version: 10.0.3

Starting with TNG V10.0.3, more than one target file can have edit parameters. It is also no longer necessary to specify location and action directives for the parameters to be processed.

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 by some text (the search text) that is in the file, followed by %end:%. Note that the search text must be unique; it must identify a single location in the file. A mod cannot, for example, change all occurrences of "this" to "that".

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%
%location:%
/* Classes for TNG Mods to be added below */
%end:%

Note that the target directive specifies the path and file name relative to the TNG main folder. The mod expects the text /* Classes for TNG Mods to be added below */ to be somewhere in css/genstyle.css.

Note that there should be no white space in this 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.

Action Directives

New text (typically PHP and/or HTML code) can be place before or after the search text, or it can replace the search text. A mod file placement directive that determines how the code text is to be inserted MUST be placed below the %end:% keyword that terminates the location search text, and also terminated with an %end:% keyword

  • inserted before %insert:before%
  • inserted after %insert:after%
  • replaced with %replace:%

If you want text to be replaced within a line in the target file, you can use the directives

  • %triminsert:before%
  • %triminsert:after%
  • %trimreplace:%

To finish the example just above, in order to place a CSS comment and a new CSS rule in genstyle.css, specify:

%target:css/genstyle.css%
%location:%
/* Classes for TNG Mods to be added below */
%end:%
%insert:after%
/* New styles for the Abracadbra Mod */
.magic {font-style:italic; display:none;}

%end:%

Note that three lines (including a blank line) will be inserted after the comment /* Classes for TNG Mods to be added below */

Multiple Target Locations

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

  1. the %location:% keyword, followed by search text
  2. an %end:% keyword,
  3. a placement directive, followed by insertion text, and
  4. a second %end:% keyword.

As noted in the "Comments in Mod Files" section below, you may place blank lines, or even annotation between locations in your mod config file as comments. There is no comment directive but text used between keywords is ignored.

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. The former method is most common. Significantly, 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. If you want to modify an existing file - even replace all of its contents, you must use a %target% section with search text and replacement text.

Within any mod file section, you may include the

  • %copyfile: to copy files to the TNG root folder
  • %copyfile2: to copy files to another folder

Using %copyfile%

The only file specification in the %copyfile: directive is a reference to the file being copied. Note: that %copyfile always copies files to the TNG root folder, which is not specified.

%copyfile:copy_file_name.php% identifies a file that is to be copied from your TNG mods subfolder to your TNG root folder.


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 the Local Copy of the file is Missing

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

Using %copyfile2%

  • %copyfile2:some_file.gif:extensions\new_file.gif%
The %copyfile2: directive MUST specify the source filepath and name immediately after the first colon, and then include a second colon, and the target path and file.

You may distribute one or more files to the mods folder, and copy them, but, to keep each site's mod folder under control, you should put all new files in a subfolder with the same base name as the mod.

The copyfile2 copies files to a subfolder structure, where again the TNG root folder should not be specified.

Using %target:files%

TNG version: 10.0.2
TNG version: 7.1

In these older versions of TNG, a %target% directive MUST refer to an existing filename and is required before you can specify any copyfile directives. You must make at least one change to the target file, and then you can apply %copyfile% or %copyfile2% directives in that mod file section.


TNG version: 10.0.3

TNG 10.0.3 added a %target:files% directive which creates a mod file section that cannot have %location% directives. It can only have %newfile%, %copyfile%, and %copyfile2% directives. The %target:files% directive was added to allow creating mods that only add new files to TNG by either creating them or copying them.

It can also be used before existing %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. That is, Mod Manager will not create folders; it will only create files in existing folders. But such an error can be suppressed by the Mod author by placing an @ symbol at the beginning of the %filecopy% or %filecopy2% source filename. 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.

Creating New Files

To create a new file containing text specified in your mod file, 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%

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 TNGv9.1.0, and it is the mod's second version, the %fileversion:% directive should be set as follows

%fileversion:v9.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 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:v9.1.0.2%
... new file content ...
?>

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

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

If the the commented version number is missing from the new file content, or 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:v9.1.0.2%
<?php
// %version:v9.1.0.2%
echo "hello world!";
?>
%fileend:%

Comments in Mod Config Files

The Mod Manager does not use php syntax for comments. However it will ignore any text (or blank lines)

  • before the mod heading's %name:% directive,
  • after the % that terminates the heading's %description directive, and before the first %target:% directive,
  • after the %end:% that terminates insertion text, and before the next %location:% or %target:% directive.

So you can effectively add comments between those sets of parameters. It is very useful for you to insert, for example, a row of asterisks before each target, and the location number and a description before each location. (Note that the config file does not, by itself, use the concept "location number", but mod manager error and status messages do number the locations.)

You cannot, however, comment out parts of a config file by adding the double-slash php comment character to the changes you do not want included in a config file. You need to remove any sections or locations you do not want.

Related Links

Mod Guidelines

Mod Manager Syntax

Mod Developer Quick Reference

Avoiding Mod Manager Conflicts

Mod Manager - Creating Config Files

Mod Manager - Edit Parameters

Mod Manager - Interpreting Status

Notepad++ Mod Manager Language