Custom Text Files Mod

From TNG_Wiki
Jump to: navigation, search
Ambox notice.png This mod only applies to TNG V8 and V9 only

The Custom Text Files Mod mod is obsolete with TNG V10 since the functionality has been included in TNG
TNG V10 action required

  • if you upgraded over existing environment -- Remove and then Delete the mod it is no longer needed with TNG V10
  • if you did a full install -- Do NOT install this mod but rather Delete it.
TNG 9.0
TNG 8.0


Custom Text Files Mod
Summary "Includes" the English or English-UTF8 cust_text.php prior to the selected language so that new variables added by other mods always have text available
Validation
Mod Updated {{{mod_last_update}}}
Download link cust_text_v9.0.0.0.zip for
TNG 9.0

Cust_text_v8.1.0.zip for
TNG 8.0
Download stats
Author(s) Roger Clist
Homepage The Clist Connections
Mod Support TNG Forum (Addons)
Contact Developer Mod User Support Form
Latest Mod 9.0.0 for TNG V9
8.1.0 for TNG V8
Min TNG V 8.0.0
Max TNG V 9.2.2
Files modified
Modifies all cust_text.php files
Related Mods
None
Notes
Each user is required to edit their .cfg file to suit their configuration of languages


Introduction

Purpose of the mod

This mod cascades cust_text.php files so that custom text variables always have text definitions, even if they are only defined in English/cust_text.php (or English-UTF8/cust_text.php if your site uses UTF-8 character sets). The mod is designed to work with any language on sites with any default language.

Is this mod useful to you?

  • Do you have language(s) on your site in addition to English?
  • Do you like installing mods to customize your site?
  • Do these mods contain custom text definitions in English only?
  • Do you find it tiresome copying (let alone translating) custom text definitions into the cust_text.php files for every language offered? (Because if you don't do this copying for every language offered, visitors using international languages will not see the custom text that your pages are intended to display!)

If so, this mod could help make your life easier!

For instance, you could install a mod which adds text variables to the English cust_text.php files and immediately all visitors will be able to see this text (albeit in English) without the need for you to immediately copy the definitions to all your other cust_text.php files in the other languages. Of course, you can add the definitions to the other languages later, suitably translated.

To see the mod in action, open the Mod User Support Form for this page, for which most of the field descriptions are defined only in English/cust_text.php. If you change language using the control in the upper right of the form, you will see the navigation text change, but the form's custom text strings remain in English. Without this Custom Text Files Mod being installed, these field descriptions would be blank in non-English languages until such time as their translations were added to the respective language's cust_text.php file. Such translations are unlikely to proceed now that the Custom Text Files Mod is in place on this site.

This mod applies to ISO-8859-1 character sets as well as UTF-8, and if you do the automated install, it will change both versions (i.e. languages/xxxxx/cust_text.php and languages/xxxxx-UTF8/cust_text.php).

Caveats

  • Sites which have a non-English default language and which offer English as a language should have English definitions of their default language custom text.
  • If you change the languages offered, you will need to remove this mod, edit its config file appropriately, then reinstall the mod.

Order of precedence

Using this mod, definitions of custom text are set in this order:

  • first from English/cust_text.php (many mods will only write text definitions to this file)
  • then overwritten by the site's default language (if non-English)
  • then overwritten by the visitor's selected language (if not English, and not the default language).

Relevance

This mod is relevant to: This mod is not relevant to:
  • sites which offer dynamic language changing, or
  • sites which have a non-English default language, with or without the facility for dynamic language switching.
  • sites running TNG versions prior to v8
  • sites which have English as the default language and which do not permit site visitors to dynamically change to another language.

Scenario examples

Site Default language Other languages Visitor's language How the mod operates
1 English No English This mod is not useful for English-only sites, as all custom text is defined in English/cust_text.php anyway. But keep this mod in mind for the time when you add international languages to your site.
2 English Yes English The mod sets custom text definitions from English/cust_text.php. See next example for what happens when the visitor changes language.
3 English Yes French, for example Custom text definitions are first set from English/cust_text.php then overwritten by French/cust_text.php. If you install mods which write to English/cust_text.php then the visitor will see these definitions in English until you get around to adding their translations to French/cust_text.php, if ever.
4 German No German You can install mods which add to English/cust_text.php and site visitors will read these definitions in English until you translate and/or add them to German/cust_text.php, if ever.
5 German Yes German You can install mods which add to English/cust_text.php and site visitors will read these definitions in English until you translate and/or add them to German/cust_text.php, if ever.
6 German Yes English You can install mods which add to English/cust_text.php and site visitors will read these definitions. But if you've added custom text of your own to German/cust_text.php you must copy/translate these to English/cust_text.php as your pages will not open German/cust_text.php for these visitors.
7 German Yes French, for example You can install mods which add to English/cust_text.php and site visitors will read these definitions in English unless (a) you translate and/or add them to German/cust_text.php (in which case they will see them in German) or (b) you translate and/or add them to French/cust_text.php.

Please note that the examples of French and German in the above scenarios are representative of any of the languages offered in the TNG package.

Perhaps it seems complicated, but once you install the Custom Text Files mod and see how it works on your site, you will find it makes it easier to install and try out other mods without the burden of immediately adding/translating their custom text definitions to all your installed languages.

Modifications to Distributed Files

This mod, when custom-configured for your site, will insert a few lines of code at the beginning of each cust_text.php file in your languages folders.

If your site is set for a non-English language as default, you must still have the English folders and files present in your languages folder, even if you do not offer English as a language choice.

As this mod affects cust_text.php files only, it will not be disturbed by TNG upgrades as long as the languages folder structure remains.

Revision History

Version Date Contents
v9.0.0.0 2 February 2012 Updated release number for TNG V9, no logic changes were made
v8.1.0 1 August 2011 Initial release of Custom Text Files Mod

How it works

The mod is conceptually very simple, as it cascades the cust_text.php files in a defined order. It inserts a small block of code at the start of each cust_text.php file in your language folders. Note that this code must always be executed prior to the setting of any definitions. As mods which write to cust_text.php are normally programmed to insert their code before the end of the file, breaking of this rule is unlikely to arise.

In the automated install, for languages other than English, the inserted code checks to see if its language is the site's default language.

  • If so, it includes English/cust_text.php before it overwrites definitions with the default language.
  • If not, it includes the default language's cust_text.php before overwriting yet further with default language definitions.

This gives the desired order: English definitions set first, default language second, and visitor's selected language third.

In the manual installation option, you can minimize the code to a single include line being inserted in each cust_text.php file other than the English versions.

Automated Install

  1. Download the mod to your local computer, and unzip the config file and save it in your mods folder.
  2. Open it in the text editor you use when working with TNG files. You will see that it has sections of code written to install in French, German, Italian, and Spanish languages. As your site will undoubtably offer different language options, it needs editing to suit your site's structure. You will need one section per language other than English. You may edit or delete any of the four sample language sections, or add extra sections as necessary. Each section starts and finishes with a comment line as per lines 35 and 59 in the example below.
  3. Check what languages are operative on your site. To do this, open Setup -> Configuration -> General Settings in your Admin panel and expand the Language section - your site's default language will be shown in the Language folder field. Click on the field's pull-down control, and write down all the languages offered on your site.
  4. Now edit the config file to suit your site. For each language you offer (other than English) the config file must contain a section of code like the sample below. Do not change any references to English or English-UTF8. In this example, change all instances of "French" to the name of the language you are targeting (lines 35, 36, 42, 48, 54).
    35 // French
    36 %target:languages/French/cust_text.php%
    37 %location:%
    38 <?php
    39 %end:%
    40 %insert:after%
    41 // Added Custom Text Files Mod v8.1.0
    42 if ($language == 'French') {
    43 include($rootpath . 'languages/English/cust_text.php'); } else {
    44 include($rootpath . $languages_path . $language . '/cust_text.php'); }
    45 // End of Custom Text Files Mod
    46 %end:%
    47 
    48 %target:languages/French-UTF8/cust_text.php%
    49 %location:%
    50 <?php
    51 %end:%
    52 %insert:after%
    53 // Added Custom Text Files Mod v8.1.0
    54 if ($language == 'French-UTF8') {
    55 include($rootpath . 'languages/English-UTF8/cust_text.php'); } else {
    56 include($rootpath . $languages_path . $language . '/cust_text.php'); }
    57 // End of Custom Text Files Mod
    58 %end:%
    59 // *******************************************************************
    
  5. Save the edited config file and FTP to the mods folder on your site.
  6. Click on Mod Manager in the Admin panel and install it. Check for errors.
  7. If your site's default language is not English, but you offer English as a choice for visitors, check that your English cust_text.php files contain definitions for all your own custom text definitions in your default language cust_text.php file (otherwise English language visitors will not see them). Edit if necessary.
  8. Test mod operation. Check for problems.

Manual Installation

Manual installation is relatively easy to implement and results in tighter code, but of course it cannot be readily removed or re-installed as with the automated install, unless you create your own mod config file to undertake the task. The strategy of cascading custom text files can be achieved with a single include line in each cust_text.php file instead of a conditional code block, and you need only edit your UTF-8 versions or the standard versions as appropriate for your site. If you are unsure which set of language files to edit, go to your Admin panel and look at Setup -> Configuration -> Language. If the Character Set field shows ISO-8859-1 then edit the non-UTF8 cust_text.php files. If it shows UTF-8 then you clearly need to edit the UTF-8 cust_text.php files.

Follow these steps:

  1. Do not edit English/cust_text.php or English-UTF8/cust_text.php with this mod.
  2. If your default language is English, insert the following include line as Line 2 in every other cust_text.php file installed in your site, substituting "English-UTF8" for "English" if you are editing UTF-8 versions.
    1 <?php
    2 include($rootpath . 'languages/English/cust_text.php');
    
  3. If your default language is a language other than English
    1. Insert the include line above as Line 2 in the default language's cust_text.php file, substituting "English-UTF8" for "English" if you are editing the UTF-8 versions
    2. Insert the include line below as Line 2 in all other non-English cust_text.php files
      1 <?php
      2 include($rootpath . $languages_path . $language . '/cust_text.php');
      
    3. If your site offers English, check that your English cust_text.php files contain definitions for all your own custom text definitions in your default language cust_text.php file (otherwise English language visitors will not see them). Edit if necessary.
  4. Test mod operation. Check for problems.

Test mod operation

  1. For convenience, the automated install inserts a test variable in your English cust_text.php files as given below. If you are doing a manual installation, add this line (or something similar) to your English/cust_text.php file (or English-UTF8/cust_text.php as the case may be).
    $text['cust_text_files_mod_test'] = "Custom Text Files  Mod Test (English)";
    
  2. Now reference this variable within the body code of any php file, such as a histories page. Find a section in your test page where the file is in html mode and add this line:
    <p><?php echo  $text['cust_text_files_mod_test'];  ?></p>
    
  3. Check that the test message appears in your page whatever language is selected.
  4. Remove the test from your histories page if desired.

Conficts

This mod must insert its code at Line 2 of cust_text.php and will cause a conflict with any other mod attempting to place code at that position. Such mods will need revision to add their code before the end of cust_text.php. Refer to Mod Guidelines for coding recommendations.

Fortunately the vast majority of mods which write to cust_text.php insert their code before the end of the file. This code gets shifted away from the end of the file as more mods get installed, but the "before the end of the file" rule remains satisfied and the Mod Manager reports no errors.

If you encounter installation errors, remove the mod and check your editing of its config file before attempting reinstallation or seeking help.

Sites using this mod

If you download and install this mod, please add your TNG site to the table below:

Site Owner Default Language Other Languages Installation
The Clist Connections Roger Clist English French, German, Italian, Spanish Automated
Our Acadian, French Canadian, and Maine Ancestors Ken Roy English French Automated
Chamberlain & Eidenbenz Genealogy Graham Chamberlain English German, Dutch, French Spanish Automated
--- --- --- --- ---