Difference between revisions of "Mod Guidelines - Prior to TNG 10.0.3"

From TNG_Wiki
Jump to navigation Jump to search
(→‎TNG V9: tweaked the wording)
(moved to MM 9 Before TNG 10.1 category)
(22 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{Languages}}
 
{{Languages}}
  
{|align=right
+
{| style="margin-right:0.5 em;" align="right"
|__TOC__
+
| __TOC__
 
|}
 
|}
With the Mod Manager now being part of TNG V8, the following Mod Manager Guidelines are proposed for TNG V8 and above:
+
 
 +
The following Mod Manager Guidelines should be followed by the Mod Developer when creating mods that will be posted for others to install:
  
 
* file name
 
* file name
Line 13: Line 14:
 
* coding standard
 
* coding standard
 
* adding files
 
* adding files
 +
 +
Mod manager directive keywords are in the format %keyword:value% where there is no white space between the percent sign keyword colon and value.  Directives should also start in the first column.
  
 
== Mod File Names ==
 
== Mod File Names ==
 +
=== Version ===
  
Starting with TNG V8, it is proposed that file names use '''v8.y.z''' for the file version number, where
+
{{TNG 9.0|and after}}
* v8 is the TNG version
+
Starting with TNG V9 the file names use mod_name_'''v.x.y.z''' for the .cfg file names and %version: numbers to identify the minimum version of TNG that a mod can be installed on, where the first 3 positions identify and the 4th position identifies the mod revision number
* y indicates the mod version for this version of TNG, starting with 1.
+
* v is the TNG version
* z indicates the mod revision number used when having to make changes to the mod between versions, starting with 0.
+
* 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 starting with 0.
 +
For example, the first version of the mod in TNG V9 is numbered and named as 9.0.0.0, the z  value for the TNG Mod number is '''0'''  so that the mod number matches  the TNG V9.0.0 and the last .0 indicates the  original release of the  mod.  
  
For example, '''living_flag_backup_v8.1.0.cfg''' since it's the first version of the [[Backup / Restore Living Flag]] mod that is compatible with TNG 8. When minor changes are made it would become '''living_flag_backup_v8.1.1.cfg''' and for TNG 9 would become '''living_flag_backup_v9.1.0.cfg'''.  
+
See the [[Mod_Guidelines#TNG_V9|TNG V9 version number]] below for additional examples where the mod number might not change with a new TNG release.
  
File names should also 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 _v8.1.1.cfg would sort before _v8.1.cfg, it was decided to use _v8.1.0.cfg.
+
=== Related Mods ===
  
=== Related Mods ===
+
Configuration files for related mods should also be named so they sort together, for example:
Configuration files for related mods can also be named so they sort together rather than by the TNG Wiki article name, for example:
 
 
{| border="1" cellspacing="5" cellpadding="2" width="100%" class="wikitable"
 
{| border="1" cellspacing="5" cellpadding="2" width="100%" class="wikitable"
 
|-
 
|-
Line 34: Line 40:
 
|-
 
|-
 
| Living Flag Backup / Restore
 
| Living Flag Backup / Restore
| living_flag_backup_v8.1.0.cfg
+
| living_flag_backup_v9.0.0.0.cfg
 
| [[Backup / Restore Living Flag]]
 
| [[Backup / Restore Living Flag]]
 
|-
 
|-
 
| Living Flag Display
 
| Living Flag Display
| living_flag_display_v8.1.0.cfg
+
| living_flag_display_v9.0.0.0.cfg
 
| [[Living Flag Mod]]
 
| [[Living Flag Mod]]
 
|}
 
|}
  
 +
If the mod was originally named differently then a wiki redirect should be created.
  
=== Related Mods with Install Sequence ===
+
=== Related 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
+
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.
Rumsey's Image Viewer is now part of TNG.
 
 
{| border="1" cellspacing="5" cellpadding="2" width="100%" class="wikitable"
 
{| border="1" cellspacing="5" cellpadding="2" width="100%" class="wikitable"
 
|-
 
|-
Line 52: Line 58:
 
! TNG Wiki Article
 
! TNG Wiki Article
 
|-
 
|-
| Media - Show Table
+
| Media 2 - Show Table
| media-2_show_table_v8.1.0.cfg
+
| media-2_show_table_v9.1.0.2.cfg
 
| [[ShowTable Mod]]
 
| [[ShowTable Mod]]
 
|-
 
|-
| Media - Body Text for Translation
+
| Media 3 - Body Text for Translation
| media-3_body_text_V8.1.0.cfg
+
| media-3_body_text_V9.1.0.0.cfg
 
| [[Body Text for Translation]]
 
| [[Body Text for Translation]]
 
|-
 
|-
| Media - Tooltip
+
| Media 4 - Tooltip
| media-4_tooltip_v8.1.0.cfg
+
| media-4_tooltip_v9.1.0.1.cfg
 
| [[Tooltip Mod]]
 
| [[Tooltip Mod]]
 
|-
 
|-
| Media - Image Map Message
+
| Media 5 - Image Map Message
| media-5_image_map_msg_v8.1.0.cfg
+
| media-5_image_map_msg_v9.1.0.1.cfg
 
| [[Image Map Message Mod]]
 
| [[Image Map Message Mod]]
 
|}
 
|}
Line 73: Line 79:
 
=== Subfolder for additional files ===
 
=== Subfolder for additional files ===
  
If a mod contains more than one file that needs to be copied from the mods folder during the Mod Manager install, it is recommended that a subfolder with the same name as used on the .cfg file '''but excluding
+
If a mod contains more than one file that needs to be copied from the mods folder during the install, it is recommended that a subfolder with the same name as used on the .cfg file or that can be easily related to the mod '''but excluding the version number''' should be used to contain the files that are copied so they will group together in the mods folder. So for example
the version number''' be used to contain the files that are copied so they will group together in the mods folder. So for example
 
  
 
*gmaps_add_4_placelevels
 
*gmaps_add_4_placelevels
*gmaps_add_4_placelevels_V8.1.0.cfg
+
*gmaps_add_4
 +
 
 +
would be related to the gmaps_add_4_placelevels_v9.0.0.1.cfg mod.  Not using the version number in the sub-folder name will make it easier to keep the mod updated and
 +
prevent cluttering with folders all similarly named when only 1 is needed. However, if your mod provides a lot of copied files that change with different versions of the mod, then you should use a version number in the subfolder, like censusplus_v10001
  
Not having the version number in the sub-folder name will make it easier to keep the mod updated and
 
prevent cluttering with folders all similarly named when only 1 is needed.
 
 
== Name ==
 
== Name ==
  
The '''<nowiki>%name: </nowiki>''' parameter used for the TNG mod config file should be the same name as used for the TNG Wiki article on the mod.  It should also be closely related to the mod file name to avoid confusion when referring to a mod in the TNG Forum when the user requests help.
+
The '''<nowiki>%name:Mod Name </nowiki>''' parameter used for the TNG mod config file should be the same name as used for the TNG Wiki article on the mod.  It should also be closely related to the mod file name to avoid confusion when referring to a mod in the TNG Forum when the user requests help.  Note that no whitespace should exist between the colon and the Mod Name.
  
 
== Version number ==
 
== Version number ==
=== TNG V9 ===
+
 
{{TNG 9.0|and after}}
+
'''<nowiki>%version:Vv.x.y.z%</nowiki>''' should be used for new config files to   identify that the mod applies to TNG Vv where v is the TNG version, x is the TNG release, and y is the TNG release modification number. The z is the TNG mod revision number. For the first version of the mod in TNG V9, numbered and named as  Mod_V9.0.0.0, the z value for the TNG Mod number is '''0'''  so that the mod number matches the TNG V9.0.0 and the last .0 indicates the original release of the mod. Note that no whitespace should exist between the colon and the version number.
'''<nowiki>%version: V9.x.y.z%</nowiki>''' should be used for new config files to identify that the mod applies to TNG V9 where x is the TNG release, y is the TNG release modification number, and z is the TNG mod number. For the first version of the mod in TNG V9, the z value for the TNG Mod number is '''0'''  so that the mod number matches the TNG V9.0.0.0 and the last .0 indicates the original release of the mod.  
+
 
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 155: Line 161:
 
|}
 
|}
  
Note that the TNG Mod V9.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 the first three values identify the minimum TNG version.release.mod on which the TNG mod can be installedFor example 9.1.0 indicates that TNG v9.1.0 is the minimum version this mod will install on. If the mod installs as is on the next major version of TNG it is not necessary to create a new version of the mod, so v9.0.2.4 could also apply to TNG v10
 
 
Note that if you include %newfile you should also update the version numbers in those new files being added.
 
=== TNG V8 ===
 
{{TNG 8.0}}
 
'''<nowiki>%version: V8.y.z%</nowiki>''' should be used for new config files to identify that the mod applies to TNG V8 where y is the mod version and z is the mod revision. The first version of a mod should be identified by <nowiki>%version: V8.1.0%</nowiki>
 
  
Note that if you include %newfile you should also update the version numbers in those new files being added.
+
Note that if you include %newfile you should also update the version numbers in those new files being added to match the mod %version number.
  
 
== Description ==
 
== Description ==
  
The %Description: statement should be kept as brief as possible. However, it should provide information on the TNG modules being modified, who the mod developer is, and a link to the TNG Wiki article pertaining to
+
The %Description:statement should be kept as brief as possible. However, it should provide information on the TNG modules being modified, who the mod developer is, and a link to the TNG Wiki article pertaining to the mod. Optionally, some mods might require other installation actions. Note that no whitespace should exist between the colon and the Mod Name.
the mod. Optionally, some mods might require other installation actions.
 
 
 
=== Modules modified ===
 
  
You should consider identifying the TNG Modules modified by your mod to make it easier for the user to know if they should Remove your mod prior to an upgrade. If the TNG upgrade does not include a change to
 
the modules that your mod targets, there is no need to uninstall your mod prior to an upgrade.
 
  
 
=== Mod Developer ===
 
=== Mod Developer ===
Line 180: Line 176:
 
=== TNG Wiki Article Link ===
 
=== 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.
+
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.
  
 
=== Installation Actions ===
 
=== 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 [[Template_Settings_-_Multi-language_Mod#After_Installation_Actions | After Installation Actions]] for the [[Template Settings -
+
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 [[Template_Settings_-_Multi-language_Mod#After_Installation_Actions | After Installation Actions]] for the [[Template Settings -
 
Multi-language Mod]] rather than creating readme files for the mod.
 
Multi-language Mod]] rather than creating readme files for the mod.
  
Line 195: Line 191:
 
* languages/English-UTF8/cust_text.php
 
* languages/English-UTF8/cust_text.php
  
Note that the cust_text.php is no longer in the English directory, but is now in the  
+
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).
* languages/English
+
 
* languages/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.
  
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).
+
If you support additional languages, TNG v10 now provides the equivalent of the [[Custom Text Mod]] that allows display of  new text variables in English until you have can create the appropriate  translations.
  
If you support additional languages, you should consider installing the [[Custom Text Files Mod]] to allow display of new text variables in English until you have can create the appropriate translations.
 
  
 
=== Coding recommendations ===
 
=== 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.
+
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.
  
To avoid conflicts with the [[Custom Text Files Mod]] is it recommended that text variables be inserted before the end of cust_text.php as shown in the code fragment below, where your code will replace lines
+
To avoid conflicts with the [[Custom Text Files Mod]] is it recommended that text variables be inserted before the end of cust_text.php as shown in the code fragment below, where your code will replace lines 15-18 and 26-29.
15-18 and 26-29.
 
  
<syntaxhighlight lang="php" line start="10" highlight="6,7,8,9,17,18,19,20" enclose="div">%target:languages/English/cust_text.php%
+
<syntaxhighlight lang="php" line start="10" highlight="6,7,8,9,17,18,19,20" enclose="div">%target:languages/English/cust_text.php%
 
%location:%
 
%location:%
 
?>
 
?>
Line 230: Line 224:
 
// End of (Mod name)
 
// End of (Mod name)
 
%end:%</syntaxhighlight>
 
%end:%</syntaxhighlight>
 +
 +
=== 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 ===
 
=== Containing Foreign Accents ===
  
While this is not a TNG V8 change, but was discovered during testing, if you create custom text that includes foreign accented characters, you should use the [http://www.ascii.cl/htmlcodes.htm HTML special
+
If you create custom text that includes foreign accented characters, you should use the [http://www.ascii.cl/htmlcodes.htm 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.  
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.  
 
  
The issue is that if you create the mod as ANSI encoded, the accented characters will be mangled when installing on a UTF-8 TNG site and vice versa if you encode the mod as UTF-8 without BOM it will get mangled on an ISO-8859-1 TNG site. Using the HTML special characters avoids the mangling if an ANSI encoded file is installed on a UTF-8 environment.
+
The issue is that if you create the mod as ANSI encoded, the accented characters will be mangled when installing on a UTF-8 TNG site and vice versa if you encode the mod as UTF-8 without BOM it will get mangled on an ISO-8859-1 TNG site. Using the HTML special characters avoids the mangling if an ANSI encoded file is installed on a UTF-8 environment.
  
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.
+
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 ==
 
== Style additions ==
Line 248: Line 247:
  
 
mods that contain style changes or additions can provide the change in one of two ways:
 
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 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 the change to the TNG genstyle.css since you don't know what template the mod installer will be using.  
  
Line 255: Line 254:
 
If you want to keep your style additions or changes to the documented override mytngstyle.css, you '''should''' use as target
 
If you want to keep your style additions or changes to the documented override mytngstyle.css, you '''should''' use as target
 
* css/mytngstyle.css
 
* css/mytngstyle.css
* templates/template1/css/mytngstyle.css for all TNG distributed templates from 1 through 8
+
* templates/template1/css/mytngstyle.css for all TNG distributed templates from 1 through 14
  
 
Mods created for your own site that are not published for others to use only need to target the template you are using.
 
Mods created for your own site that are not published for others to use only need to target the template you are using.
Line 261: Line 260:
 
=== Target genstyle.css ===
 
=== 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
+
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.  
changed.  
 
  
 
If your mod targets genlib.php or getperson.php, then it may make sense to target your style change
 
If your mod targets genlib.php or getperson.php, then it may make sense to target your style change
Line 271: Line 269:
 
The following was extracted from the User2 list, requesting that mods be coded to XHTML coding 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
+
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.
 
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:
+
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]]
 
[[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:
+
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 <code><nowiki><p></nowiki></code> should
 
* Paired tags not closed (eg: Every opening paragraph tag <code><nowiki><p></nowiki></code> should
 
be followed by a closing <code><nowiki></p></nowiki></code> tag)
 
be followed by a closing <code><nowiki></p></nowiki></code> tag)
 
* Self closing tags not closed (eg the image tag should be closed thus:  <img ..... />
 
* Self closing tags not closed (eg the image tag should be closed thus:  <img ..... />
* Tags should be nest correctly (eg <code><nowiki><b><i> ... </i></b></nowiki></code> is correct;
+
* Tags should be nest correctly (eg <code><nowiki><b><i> ... </i></b></nowiki></code> is correct;
 
<code><nowiki><b><i> ... </b></i></nowiki></code> is not)
 
<code><nowiki><b><i> ... </b></i></nowiki></code> is not)
 
* Attribute values must be literals (eg use border="0"; not border=0)
 
* 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="")
 
* 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
+
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:
 
correct validation result:
 
   
 
   
 
[http://validator.w3.org/ W3C Validator]
 
[http://validator.w3.org/ 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. <sub>Posted by Alan Craxford on the User2 List on 31 January 2011</sub>
+
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. <sub>Posted by Alan Craxford on the User2 List on 31 January 2011</sub>
  
 
== Adding Files ==
 
== Adding Files ==
Line 301: Line 299:
 
* %copyfile or $copyfile2
 
* %copyfile or $copyfile2
  
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 10.0.2|and before}}{{TNG 7.1|and after}}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 10.0.3|and after}}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 ===
 
=== 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.
+
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 ===
 
=== Copy File ===
  
There are two flavors of the %copyfile parameter. One that copies the file to the TNG root directory, the other, %copyfile2 which copies the file to the specified location.  
+
There are two flavors of the %copyfile parameter.  
 +
 
 +
%copyfile: copies the file to the '''TNG root''' directory: .
 +
 
 +
<syntaxhighlight lang="php" enclose="div">%copyfile:icons/new_icon_file.gif%</syntaxhighlight>
 +
 
 +
%copyfile2: copies the file '''to a specified location'''
 +
 
 +
<syntaxhighlight  lang="php"  enclose="div">%copyfile2:icons/new_icon_file.gif:img/new_icon_file.gif%</syntaxhighlight>
 +
 
 +
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.
  
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.
  
 
=== Extensions folder ===
 
=== 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
+
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.
 
need to be in the TNG root folder in order to work correctly.
  
Also, currently you cannot rename the extension folder, since the folder name is hard-coded as the destination folder in the $newfile or %copyfile parameters. For example,  
+
Also, currently you '''cannot rename''' the extension folder, since the folder name is hard-coded as the destination folder in the $newfile or %copyfile parameters. For example,  
  
 
<syntaxhighlight lang="php" enclose="div">%newfile:extensions/bodytext_imageviewer.php%</syntaxhighlight>
 
<syntaxhighlight lang="php" enclose="div">%newfile:extensions/bodytext_imageviewer.php%</syntaxhighlight>
Line 328: Line 339:
 
%copyfile2:rip_prevention/check_access.php:extensions/check_access.php%
 
%copyfile2:rip_prevention/check_access.php:extensions/check_access.php%
 
</syntaxhighlight>
 
</syntaxhighlight>
[[Category:TNG Mod Manager|!]]
+
 
 +
== Related Links ==
 +
 
 +
[[Mod Guidelines]]
 +
 
 +
[[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]]
 +
 
 +
[[Category:MM 9 Before TNG 10.1‎]]

Revision as of 09:00, 11 April 2018

The following Mod Manager Guidelines should be followed by the Mod Developer when creating mods that will be posted for others to install:

  • file name
  • version
  • description
  • custom text
  • style additions
  • coding standard
  • adding files

Mod manager directive keywords are in the format %keyword:value% where there is no white space between the percent sign keyword colon and value. Directives should also start in the first column.

Mod File Names

Version

TNG version: 9.0

Starting with TNG V9 the file names use mod_name_v.x.y.z for the .cfg file names and %version: numbers to identify the minimum version of TNG that a mod can be installed on, where the first 3 positions identify and the 4th position identifies the mod revision number

  • v 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 starting with 0.

For example, the first version of the mod in TNG V9 is numbered and named as 9.0.0.0, the z value for the TNG Mod number is 0 so that the mod number matches the TNG V9.0.0 and the last .0 indicates the original release of the mod.

See the TNG V9 version number below for additional examples where the mod number might not change with a new TNG release.

Related Mods

Configuration files for related mods should also be named so they sort together, for example:

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

If the mod was originally named differently then a wiki redirect should be created.

Related with Install Sequence

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.

Description File Name TNG Wiki Article
Media 2 - Show Table media-2_show_table_v9.1.0.2.cfg ShowTable Mod
Media 3 - Body Text for Translation media-3_body_text_V9.1.0.0.cfg Body Text for Translation
Media 4 - Tooltip media-4_tooltip_v9.1.0.1.cfg Tooltip Mod
Media 5 - Image Map Message media-5_image_map_msg_v9.1.0.1.cfg Image Map Message Mod

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

Subfolder for additional files

If a mod contains more than one file that needs to be copied from the mods folder during the install, it is recommended that a subfolder with the same name as used on the .cfg file or that can be easily related to the mod but excluding the version number should be used to contain the files that are copied so they will group together in the mods folder. So for example

  • gmaps_add_4_placelevels
  • gmaps_add_4

would be related to the gmaps_add_4_placelevels_v9.0.0.1.cfg mod. Not using the version number in the sub-folder name will make it easier to keep the mod updated and prevent cluttering with folders all similarly named when only 1 is needed. However, if your mod provides a lot of copied files that change with different versions of the mod, then you should use a version number in the subfolder, like censusplus_v10001

Name

The %name:Mod Name parameter used for the TNG mod config file should be the same name as used for the TNG Wiki article on the mod. It should also be closely related to the mod file name to avoid confusion when referring to a mod in the TNG Forum when the user requests help. Note that no whitespace should exist between the colon and the Mod Name.

Version number

%version:Vv.x.y.z% should be used for new config files to identify that the mod applies to TNG Vv where v is the TNG version, x is the TNG release, and y is the TNG release modification number. The z is the TNG mod revision number. For the first version of the mod in TNG V9, numbered and named as Mod_V9.0.0.0, the z value for the TNG Mod number is 0 so that the mod number matches the TNG V9.0.0 and the last .0 indicates the original release of the mod. Note that no whitespace should exist between the colon and the version number.


TNG Mod Version Mod File name z value Meaning of the TNG Mod number
9.0.0 %version: V9.0.0.0% filename_v9.0.0.0.cfg 0 first mod for a new TNG version
9.0.0 %version: V9.0.0.1% filename_v9.0.0.1.cfg 1 fixed a bug in the Mod
9.0.0 %version: V9.0.0.2% filename_v9.0.0.2.cfg 2 fixed another bug in the Mod
9.0.1 %version: V9.0.0.2% filename_v9.0.0.2.cfg 2 no change required to the mod for new TNG release
9.0.2 %version: V9.0.2.3% filename_v9.0.2.3.cfg 3 mod needed a change
9.0.2 %version: V9.0.2.4% filename_v9.0.2.4.cfg 4 added new feature to mod
9.0.3 %version: V9.0.2.4% filename_v9.0.2.4.cfg 4 no change required
9.1.0 %version: V9.0.2.4% filename_v9.0.2.4.cfg 4 no change required
9.1.1 %version: V9.1.1.5% filename_v9.1.1.5.cfg 5 change required for new TNG release

Note that the first three values identify the minimum TNG version.release.mod on which the TNG mod can be installed. For example 9.1.0 indicates that TNG v9.1.0 is the minimum version this mod will install on. If the mod installs as is on the next major version of TNG it is not necessary to create a new version of the mod, so v9.0.2.4 could also apply to TNG v10

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

Description

The %Description:statement should be kept as brief as possible. However, it should provide information on the TNG modules being modified, who the mod developer is, and a link to the TNG Wiki article pertaining to the mod. Optionally, some mods might require other installation actions. Note that no whitespace should exist between the colon and the Mod Name.


Mod Developer

The mod developer should be identified in the description.

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.

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.

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 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.

To avoid conflicts with the Custom Text Files Mod is it recommended that text variables be inserted before the end of cust_text.php as shown in the code fragment below, where your code will replace lines 15-18 and 26-29.

%target:languages/English/cust_text.php%
%location:%
?>
%end:%
%insert:before%
// (Mod name), (mod version)
$text['something'] = "these words";
$text['something more'] = "etc.";
// End of (Mod name)
%end:%

%target:languages/English-UTF8/cust_text.php%
%location:%
?>
%end:%
%insert:before%
// (Mod name), (mod version)
$text['something'] = "these words";
$text['something more'] = "etc.";
// End of (Mod name)
%end:%

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.

The issue is that if you create the mod as ANSI encoded, the accented characters will be mangled when installing on a UTF-8 TNG site and vice versa if you encode the mod as UTF-8 without BOM it will get mangled on an ISO-8859-1 TNG site. Using the HTML special characters avoids the mangling if an ANSI encoded file is installed on a UTF-8 environment.

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 14

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: 10.0.2
TNG version: 7.1

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.

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.

Also, currently you cannot rename the extension folder, since the folder name is hard-coded as the destination folder in the $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%

Related Links

Mod Guidelines

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