Mod Guidelines

From TNG_Wiki
Jump to navigation Jump to search
Ambox notice.png The following Mod Guidelines pertain to the new Mod Manager in TNG 10.1 and later.

See TNG Mod Version Numbers for Beginners for an explanation on the mod version number meaning.

TNG 10.1.0



TNG mods are distributed as zip archives, The distributed zip archive must always contain a mod .cfg file, and may contain a subfolder with new files that are to be copied to TNG folders. See Dealing With Different Zip Files on behavior quirks of zip files created in one environment and processed in a different environment.

See Mod Guidelines - Prior to TNG 10.0.3 for previous guidelines

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

Name

The Mod Name in the %name:mod name% directive used in the TNG mod config file should immediately follow the colon and should be the same as the TNG Wiki article page name. The word Mod or mod should generally not be used in the name. Exception on using Mod in the name might be for example the Custom Menu Hook Mod where there is an article that describes the TNG Custom Menu Hook, and the mod provides an example of how to implement the hook if using the Mod Manager.

There should be no blank or white space immediately following the colon. The name should also be kept as short as possible to make it easier for reporting. It is recommended that the name be less than 30 characters. Since the MediaWiki software also capitalizes the first character of an article, you should use %name:Name and not %name:name so the mods will sort in the correct order in reports.

The config file names should also closely correlate with the %name: parameter to avoid confusion when referring to a mod in the TNG Forum or on the user2 list when requesting help.

Version Numbering

The mod version number reflects 1) the minimum TNG version with which it is compatible and 2) the current version of the mod..

The format for a TNGv10 mod version number is v10.x.y.z where 10.x.y is the minimum compatible TNG version, and z is the one-up version of the mod within the TNGv10 series.

  • v10 is the TNG version
  • x is the TNG release,
  • y is the TNG release modification number, and
  • z is the TNG mod number used when having to make changes to the mod between versions, starting with 0.

The first released version of a mod for use with TNG V10.0.0 would be mod_name_v10.0.0.0, where the final digit -- the "z" digit -- is 0. This tells us it is the first version of the mod in the TNGv10 series, and that it is compatible with TNGv10.0.0 and later.

It is not necessary to create a new mod for each new TNG release if it still installs and works correctly. If the latest TNG is version 10.0.3 and mod_name_v10.0.0.0 still works with it, the TNGWiki article will indicate it in the download area

MIN TNG: 10.0.0
MAX TNG: 10.0.3.

The following table illustrates the use of the mod version numbers.

TNG Mod Version Mod File name z value Meaning of the TNG Mod number
10.0.0 %version: v10.0.0.0% filename_v10.0.0.0.cfg 0 first mod for a new TNG version
10.0.0 %version: v10.0.0.1% filename_v10.0.0.1.cfg 1 fixed a bug in the Mod
10.0.0 %version: v10.0.0.2% filename_v10.0.0.2.cfg 2 fixed another bug in the Mod
10.0.1 %version: v10.0.0.2% filename_v10.0.0.2.cfg 2 no change required to the mod for new TNG release
10.0.2 %version: v10.0.2.3% filename_v10.0.2.3.cfg 3 change required for new TNG update
10.0.2 %version: v10.0.2.4% filename_v10.0.2.4.cfg 4 added new feature to mod
10.0.3 %version: v10.0.2.4% filename_v10.0.2.4.cfg 4 no change required in mod
10.1.0 %version: v10.0.2.4% filename_v10.0.2.4.cfg 4 no change required in mod
10.1.1 %version: v10.1.1.5% filename_v10.1.1.5.cfg 5 change required for new TNG release

Note that the TNG Mod v10.x.y.z is never higher than the TNG Version it applies to when compared at the first 3 digits and the z value is incremented continually across all TNG releases within a TNG version

Note that if you include %newfile you should also update the version numbers in those new files being added.

Config File Name

The config file name should use all lower cases since it affects the sort in the Linux hosting environment. While the z portion of the file name was initially indicated as optional, since it affects the collating (or file sort) sequence on Windows where v10.1.1.cfg would sort before v10.1.cfg, it was decided to use v10.1.0.0.cfg showing all elements of the version number even if they are zero.


TNG version: 12.0.0

Using only lower cases for the file name is especially important in the Mod Manager starting with TNG v12 for the new View Parser Table since the files are listed in file name collating sequence and using mixed cases impact the sort.

Related Mods

Configuration files for related mods can also be named so they sort together rather than by the TNG Wiki article name, for example:

Description File Name TNG Wiki Article
Living Flag Backup / Restore living_flag_backup_v10.0.0.0.cfg Living Flag Backup / Restore
Living Flag Display living_flag_display_v10.0.0.0.cfg Living Flag Mod

Related Mods with Install Sequence

and if an install sequence on related mods needs to be designated, it could be entered as media-2 through media-4 as shown as illustrated below (media-1 is not shown since it is obsolete with TNG V8 where Bret Rumsey's Image Viewer is now part of TNG.

Description File Name Redirect Article TNG Wiki Article
Media - Show Table media-2_show_table_v8.1.0.cfg Media - 2 - ShowTable Mod ShowTable Mod
Media - Body Text for Translation media-3_body_text_V8.1.0.cfg Media - 3 - Body Text for Translation Body Text for Translation
Media - Tooltip media-4_tooltip_v8.1.0.cfg Media - 4 - Tooltip Mod Tooltip Mod
Media - Image Map Message media-5_image_map_msg_v8.1.0.cfg Media - 5 - Image Map Message Mod Image Map Message Mod

Note that TNG Wiki article redirects should also be created as was done for the above media mods.

Subfolder for additional files

TNG version: 12.0.0

The TNG v12 of the Mod Manager now deletes the folder associated with a mod, if you enable the Allow Delete support folder when mod is deleted in the Options, Other section.

Note The mod subfolder should include the mod version number so it does not overlaid previous mod subfolders


If a mod contains one or more files that need to be copied during the Mod Manager install, it is recommended that you use a subfolder with the same name or a name that can be associated with the mod cfg file to contain the file(s) that are copied so the files can be deleted when the Mod Manager deletes the folder on a mod delete request.

Individual files copied from the mods folder will not be deleted on a mod delete.

Note: If you share the subfolder name with more than one version of the mod, you could encounter some problems.

Description

The %Description: statement should be kept as brief as possible. However, it should provide information on who the mod developer is. Optionally, some mods might require other installation actions. It is no longer necessary to identify which modules are affected since the Mod Manager screen now provides that information since TNG 10.0.3.

Mod Developer

The mod developer should be identified in the description.

TNG version: 12.0.0

TNG v12 of the Mod Manager adds a %author: tag that can be used to replace the Mod Developer section of the %description.

Multiple %author: tags can be used to show that more than one person worked on a mod. The Mod Manager will combine them into a single line above the %description for the mod.

See the author tag section of the Mod Manager Enhancement article for additional details.

TNG Wiki Article Link

A link to the TNG Wiki article, which uses the same value as specified in the %name: parameter for the mod should be included in the description using the target="_blank" as part of the URL so that article will open in a different window. This makes it easier for the TNG Users to check whether a new version of the mod exists.


TNG version: 10.1.0

With TNG 10.1, you should use the %wikipage:wiki_article_name% directive for providing the TNG wiki link. Note that underscores should be used instead of blanks or spaces in the article name.

Installation Actions

If there are actions that must be taken either before or after installation of the mod, only a brief description of the required actions should be included in the mod description. Detailed steps for these actions should be documented in the TNG Wiki article, such as shown in After Installation Actions for the [[Template Settings - Multi-language Mod]] rather than creating readme files for the mod.

TNG version: 12.0.0

TNG v12 of the Mod Manager parses the TNG variable for the mods folder ($modspath) and the extensions folder ($extspath) which now allow you do provide action buttons that execute files from the mods or extensions folders, such as

<input class="button space" type="button" style="color:green;font-weight:bold" value="Run Checks" onclick="window.open('$modspath/bot-trap_v12005/bt_check.php','_blank');" /><br /><br />
<input class="button space" type="button" style="color:red;font-weight:bold" value="Delete the tables" onclick="window.open('$modspath/cousins_12.0.0.3/delete_table.php','_blank');" /><br />
  • or the Census Plus International mod which now allows the table update to be done either before or after the mod is installed
<li>Update the CPI Label table <input class="button space" type="button" style="color:green;font-weight:bold" value="Update CPI Label Table" onclick="window.open('$modspath/censusplus_v12007/cpmakelabel.php','_blank');" />

wikipage

TNG version: 10.1.0

TNG 10.1 added a %wikipage:wiki_article% that provides a URL link to the TNG Wiki article for the mod. The wiki_article should match the TNG Wiki article title= where blanks are replaced with underscores for the actual URL link.

Custom Text

Both English folders

If your mod provides custom text, you must provide the $text variables for both

  • languages/English/cust_text.php
  • languages/English-UTF8/cust_text.php

You should use both English and English-UTF8 when constructing a .cfg file since you don't know whether a mod user will be installing your mod on a system running as ISO-8859-1 (English) or UTF-8 (English-UTF8).

Note that users should not delete the languages/English folder on their site, since the Admin Help files are also contained in the English folder only and mods that provide custom text entries will require this folder.

If you support additional languages, TNG v10 now provides the equivalent of the Custom Text Files Mod that allows display of new text variables in English until you have can create the appropriate translations.


Coding recommendations

It is recommended that your text variable definitions be preceded by a comment line stating your Mod name and version. Likewise, add a comment line to end your list of variables. See example below.


TNG version: 12.0.0

To avoid problems for users who manually modify the cust_text.php files it is recommended that text variables be inserted before the new comment at the top of the cust_text.php as shown in the code fragment below, where your code will replace lines 15-19 and 27-31.

10%target:languages/English/cust_text.php%
11%location:%
12//Mods should put their changes before this line, local changes should come after it.
13%end:%
14%insert:before%
15
16// (Mod name), (mod version)
17$text['something'] = "these words";
18$text['something more'] = "etc.";
19// End of (Mod name)
20%end:%
21
22%target:languages/English-UTF8/cust_text.php%
23%location:%
24//Mods should put their changes before this line, local changes should come after it.
25%end:%
26%insert:before%
27
28// (Mod name), (mod version)
29$text['something'] = "these words";
30$text['something more'] = "etc.";
31// End of (Mod name)
32%end:%

18 Mar 2024 Bob Carver In order to conform to the coding recommendation above it's important to run the update noted in the Mod Manager's "Recommended Updates" tab (Update cust_text.php files) to ensure cust_text.php files include the line "//Mods should put their changes before this line, local changes should come after it."

Containing other languages

Mods containing other language custom text should include the %fileoptional:% parameter so that the installation will be bypassed if the user deleted the language folder.

Note that %newfile, %copyfile, or %copyfile2 cannot follow the %fileoptional section so these parameters should follow the English cust_text.php sections or use the %target:files% directive added in TNG V10.0.3

Containing Foreign Accents

If you create custom text that includes foreign accented characters, you should use the HTML special character so that the change can be installed in both the French and French-UTF8 cust_text.php for example and display correctly whether you are using ISO-8859-1 or UTF-8 for your TNG charset.

It is impossible to create a file containing both ISO-8859 and UTF-8 characters. In addition, the Windows Notepad editor adds a non-recommended "Byte Order Mark" (BOM) at the beginning of a UTF-8 file which will interfere with PHP execution . You should use the Notepad++ or the PSPad ASCII text editors on windows environments. The BOM is not generated by Mac or Linux editors or files created by PHP.

To avoid the foreign accented characters getting mangled on display when installed on an ISO-8859-1 or UTF-8 site, you should use one of the following approaches:

  • Code the foreign accented characters using HTML entities
  • Translate the file using the UTF-8 translator
  • Create ANSI and UTF-8 versions of the cfg file

The alternative is creating both an "ANSI" and UTF-8 file, which is probably a valid alternative for installing cust_text.php changes for your own site languages that you are not publishing.

Style additions

Starting with TNG 8.1.0, since

  • TNG supports selecting the template to be used on the site from the Admin >> Setup >> Template Settings
  • each template has its own mytngstyle.css override
  • there is not an independent style sheet override capability,

mods that contain style changes or additions can provide the change in one of two ways:

  • target the change not only for the default css/mytngstyle.css but also for each templates/templateN/css/mytngstyle.css where N is the template number
  • target the change to the TNG genstyle.css since you don't know what template the mod installer will be using.

Target mytngstyle.css

If you want to keep your style additions or changes to the documented override mytngstyle.css, you should use as target

  • css/mytngstyle.css
  • templates/template1/css/mytngstyle.css for all TNG distributed templates from 1 through 21

Mods created for your own site that are not published for others to use only need to target the template you are using.

Target genstyle.css

The alternative to providing style changes is to target the genstyle.css for them, but if you do be aware that your mod will be impacted with every TNG upgrade since genstyle.css is one of the files that is always changed.

If your mod targets genlib.php or getperson.php, then it may make sense to target your style change against genstyle.css, since both of those modules are normally replaced with each upgrade.

Coding to Standards

The following was extracted from the User2 list, requesting that mods be coded to XHTML coding standards.

Could I make a plea through the lists to persuade mod contributors to make sure that the config files they are offering are of a proper coding standard. I realise that it can be difficult in your own site to understand the vagaries of and differences between the languages of html and php.

The syntax of mod manager adds a third layer to this array. However, the basic structure of TNG8 is set at xhtml1.0 transitional and I believe that if a mod is offered to the end user population, the resulting code should conform to that standard. There is an excellent resume of the syntactic rules for xhtml in the TNG wiki which covers the majority of the requirements: XHTML_Validation_-_Transitional


It is quite possible that your browser will interpret what should be there if you don't conform to these requirements. However you should make sure that your config file is NOT carrying over such errors as:

  • Paired tags not closed (eg: Every opening paragraph tag <p> should

be followed by a closing </p> tag)

  • Self closing tags not closed (eg the image tag should be closed thus: <img ..... />
  • Tags should be nest correctly (eg <b><i> ... </i></b> is correct;

<b><i> ... </b></i> is not)

  • Attribute values must be literals (eg use border="0"; not border=0)
  • Image (and some other) tags require an alt attribute (even if it is declared empty ie alt="")

Perhaps the simplest way to check your coding is to submit a specimen page for validation after you have added it (your home page is the easiest choice) to the w3c validation service. You should aspire to a Green correct validation result:

W3C Validator

I realise there are people who don't consider validation to be particularly important but essentially if you are going to use a language you should use it properly. For people who do, a poorly written mod is not worth the effort. Posted by Alan Craxford on the User2 List on 31 January 2011

Adding Files

There are two separate Mod Manager parameters that can be used to add new files in a TNG mod cfg file:

  • %newfile
  • %copyfile or %copyfile2
TNG version: 14.0

Note : From TNG 14.0, there is no more difference between %copyfile and %copyfile2 and %copyfile can be used instead of %copyfile2.

TNG version: 10.0.2

Note that you cannot create a mod that only adds files to TNG. One workaround this restrictions is to modify or add an entry in the cust_text.php for your mod.


TNG version: 10.0.3

TNG 10.0.3 adds a new %target:files% directive that allows creating (%newfile) or copying files (%copyfile and %copyfile2) to be used without having to specify and existing file as a target.


New File

The %newfile parameter includes the new file source directly in the .cfg file. Note that there is a known side effect that installing or removing a file that contains a long %newfile takes longer to process.

Copy File

There are two flavors of the %copyfile parameter.

%copyfile: copies the file to the TNG root directory: .

%copyfile:icons/new_icon_file.gif%

%copyfile2: copies the file to a specified location

%copyfile2:icons/new_icon_file.gif:img/new_icon_file.gif%

When using the copy file capability, you should create a subdirectory in the mods directory to contain the files used as the source for the copyfile function for your TNG mod.

Note that %copyfile cannot copy the entire content of a folder, you need to specify %copyfile or %copyfile2 for each file within the folder.


TNG version: 10.1.0

It may be that a destination folder for a copied file is missing from the user's system, for example if they've deleted language folders. To prevent an error and allow installation to continue without copying a file, use the '@' sign in front of the source file to tell Mod Manager the copy operation is optional.

%copyfile:@icons/new_icon_file.gif%
%copyfile2:@icons/new_icon_file.gif:img/new_icon_file.gif%


TNG version: 12.0.0

TNG v12 of the Mod Manager added a %mkdir tag. If the copyfile2 directive is to copy a file to the directory (or folder) created by the new mkdir directive, then you must use the new ^ (carat) provisional flag to ensure that the directory exists before the Mod Manager attempts to copy files to that directory.

//Create a subfolder for image files
%mkdir:languages/English/textplus%
//Copy the image files to the new subfolder 
//Note the 'provisional' flag, the caret (^), that prevents the %copyfile2 commands from 
//generating an error when the mod is being analyzed before installation.
%copyfile2:^textplus_charts_v10.1.0.13/English/descend1.png:languages/English/textplus/descend1.png%
%copyfile2:^textplus_charts_v10.1.0.13/English/pedigree1.png:languages/English/textplus/descend1.png%
etc.

Extensions folder

It is recommended that you install new files or copied files to the Mod Manager extensions folder so that your code snippets are not intermixed with the TNG code. There are some cases though where your code might need to be in the TNG root folder in order to work correctly.


TNG version: 11.0.2

TNG v11.0.2 of the Mod Manager supports the TNG rename of the extension folder by parsing the $extspath variable when specifying the target destination folder in the %target, %newfile, or %copyfile parameters. For example,

%newfile:$extspath/bodytext_imageviewer.php%

or

%copyfile2:rip_prevention/rip_warning.html:$extspath/rip_warning.html%
%copyfile2:rip_prevention/rip_ban.html:$extspath/rip_ban.html%
%copyfile2:rip_prevention/showaccess.php:$extspath/showaccess.php%
%copyfile2:rip_prevention/check_access.php:$extspath/check_access.php%


TNG version: 11.0.1

The Mod Manager in TNG versions prior to TNG v11.0.2 do not support the rename of the extension folder, since the folder name is hard-coded as the destination folder in the %target, %newfile, or %copyfile parameters. For example,

%newfile:extensions/bodytext_imageviewer.php%

or

%copyfile2:rip_prevention/rip_warning.html:extensions/rip_warning.html%
%copyfile2:rip_prevention/rip_ban.html:extensions/rip_ban.html%
%copyfile2:rip_prevention/showaccess.php:extensions/showaccess.php%
%copyfile2:rip_prevention/check_access.php:extensions/check_access.php%

Zip Files

Content

Your mod .cfg file should be in the root of the created zip file and not in a mod name folder. Some TNG users extract the zip file directly to the TNG mods folder. The Mod Manager expects the mod .cfg file and any associated sub folders to reside in the TNG mods folder and not in a sub folder. If you use a mod name folder to create your zip file, then the Mod Manager will not find your mod when unzipped directly to the mods which will also result in unnecessary issues being reported on the TNG Community Forum or the user2 email list.

Mod Zip Files created for the Mod Manager .cfg files and associated folders should normally contain:

  • only the .cfg file for the mod itself
  • associated folder if the mod provides scripts that are copied using the %copyfile or %copyfile2 directives

See Dealing With Different Zip Files that were not created using the above guidelines.

Upload to the TNG Wiki

Your mod zip file should be uploaded to the TNG Wiki using the Tools, Upload File link at the bottom of the left nav sidebar.

If you host your mods on your own site and your site disappears, TNG users can no longer download your mods and other developers will not be able to take over supporting your mods.

Thankfully Bart Degryse's mods were all uploaded to the TNG Wiki so that other TNG mod developers can continue to support his wonderful mods.

You should upload new versions of your mod to the TNG Wiki before you update the mod article. Failure to do this results in a TNG User getting the File Upload dialog instead of the mod zip file.

Download Name Display

If you use Bart Degryse's Click Counter II to track the downloads of your mods, you should display the actual zip file name in the download link. If you do not use the actually zip file name you uploaded to the TNG Wiki or you point the Click Counter to your own site and your site goes away, we may not be able to find the zip file for your mod so that the TNG Wiki can be updated to point to the file location on the TNG Wiki

If you do not display the actual zip file name for your mod on the TNG Wiki as the download link, then you are also causing additional work for the TNG Wiki sysops who will try to find your mod so your mod page can be updated to allow other TNG users to download your mod when your site goes away.

You should use the HTML comment characters to indicate the zip file name in your TNG mod article to make it easier in case your site goes away.

If you host your own web server and power off the server because you are away for an extended period of time, then users are not be able to download your mods when you use the Click Counter to track downloads, whether the mod zip file is on the TNG Wiki or not. You should update the TNG Wiki articles for your mods to use the file on the TNGWiki before you power down your server because you will be away for an extended period of time.

Click Counter Email Notify

The Click Counter II Email Notify mod has been updated to allow downloads from sites that require login and when the mod developer's site is in TNG Maintenance Mode

Guideline Summary

The following guidelines should be followed:

  • Your TNG Mod zip files should reside on the TNG Wiki - use the Tools, Upload file in the bottom left nav sidebar to upload your mods to the TNG Wiki
  • Your TNG Mod zip files should be uploaded before you update your mod article on the TNG Wiki.
  • Your TNG mod zip file name display should match the actual file name uploaded to the TNG Wiki, so that the zip file can be found if your site goes away
  • Your mod cfg file should be in the root of the zip file.
See Dealing With Different Zip Files for zip files created on a MacIntosh that contain the mod folder name and MacOS data

Related Links

Mod Manager

Mod Manager Controls

For Mod Developers

Technical

Developer Tools

Example Mods

The Mod Manager Guide pertains to articles related to the TNG Mod Manager.