Family Group Worksheet

From TNG_Wiki
Revision as of 23:20, 7 February 2012 by Pastormacomber (talk | contribs) (Sites Using)

Jump to: navigation, search
Ambox notice.png The Family Group Worksheet is designed to work with TNGv813 and later. If you are using an earlier version of TNG8 and cannot upgrade, we will suggest a workaround.
TNG 8.1.3


Family Group Worksheet
Summary Form for registered users to upload their related family groups.
Validation This mod is XHTML compliant.Valid-xhtml10.png
Mod Updated {{{mod_last_update}}}
Download link For
TNG 9.0
Family_Group_Worksheet_v9.0.0.0.zip
for
TNG 8.1.3

sheets_v132.zip


Language Files:
Dutch
French
German

Spanish
Download stats {{{download_stats}}}
Author(s) Rick Bisbee and members of tngusers2
Homepage Bisbee Family Connection
Mod Support TNG Forums
Contact Developer Support for Family Group Worksheet
Latest Mod v1.32
Min TNG V 8.1.3
Max TNG V 8.1.3
Files modified
genlib.php
Related Mods
None
Notes


Introduction

The Family Group Worksheet provides a form for registered users to enter and upload information to the website for inclusion in the family tree. It sends a formatted email containing the family group to the site administrator, with a copy back to the informant if desired. The Family Group Worksheet is downloaded as a TNG mod, but can be manually installed and linked by knowledgeable administrators.

When installed as a mod, the worksheet script file is placed in the TNG root folder. Language and help files are added to language folders, and cust_text.php files are modified to use them.

The mod will create a link to the worksheet in the 'Find' drop down menu that will only be visible to registered users. Because of the variety of TNG and customized templates, links in the top or side menus, or elsewhere on the home page will need to be created manually. We will explain how to do that for those not familiar with modifying HTML and PHP.

The Family Group Worksheet comes with generic styling, but is easily customized.

Visualization

The following shows how the form will appear with no language or styling customizations. It is perfectly usable out of the box.

Fgw001.gif

Revision History

Version Date Contents
v1.25 09 Oct 2011 Initial release of Family Group Worksheet.
v1.26 12 Oct 2011 Adds UTF8 language files; minor fixes and options.
v1.27 12 Oct 2011 Updates sheets.php, fixes minor errors and makes it W3C compliant. Language files are not affected. If upgrading from v1.26, replace sheets.php only. There is no need to uninstall and reinstall the mod.
v1.28 27 Oct 2011 This version adds support for LDS ordinances. This is conditional, and only appears on sites with LDS data enabled for users with LDS permissions. For any other site/user, the form appears identical to v1.27. This mod updates sheets.php as well as ws.english.php and ws.english-UTF8.php. Non-English translations for LDS fields are not yet available.
v1.29 2 Nov 2011 This is a minor update. This update places the 'sheets.php' file in the TNG root directory rather than the extensions directory. It is otherwise identical to v.1.28.
v1.30 8 Dec 2011 This is a minor update. This update fixes syntax in the mod configuration file to resolve errors which users have had. It also uses the 'fileoptional' parameter so that the mod still works if not all language files are present. The English language folders are still required. It is otherwise identical to v.1.29.
v1.31 17 Dec 2011 This update fixes a few more bugs that were occurring with missing language folders. If language folders are missing (English is still required), this version will install and function properly, however you may see a mod manager error showing those missing languages as uninstalled. In this case, do not run the cleanup operation. The error message can be ignored.
v1.32 19 Dec 2011 This update strips non-English language files out of the mod. Supported languages must now be installed separately using one of the linked language packs.
v9.0.0.0 25 Jan 2012 Update for TNG V9. This version uses the new syntax for naming for mods.

Download Package

The download package will contain several files:

  • sheets.cfg: configuration file for TNG Mod Manager installation
  • fgws/sheets.php: main script displays and processes the Family Group Worksheet
  • fgws/ws.english.help.php: help file in English
  • fgws/ws.english.php: English language file
  • fgws_dutch/ws.dutch.php: Dutch language file - In Dutch language download.
  • fgws_french/ws.french.php: French language file - In French language download.
  • fgws_german/ws.german.php: German language file - In German language download.
  • fgws_spanish/ws.spanish.php: Spanish language file - In Spanish language download.
  • fgws/others languages as they become available
  • fgws/readme.txt for manually installing/upgrading to new version

Upgrading from Previous Version

Before upgrading to a new version of the Family Group Worksheet it is important that you completely remove your current version. If you installed it with Mod Manager, use Mod Manager to Remove and Delete it. Check your mods directory and remove the fgws folder. Any links you installed manually should not need to be modified.

If you installed the Family Group Worksheet manually, see the readme.txt file in the download package. Depending on what is affected in the upgrade, you may have to remove/replace the language files, delete/replace the Worksheet code in the cust_text.php files, delete/replace sheets.php from the root directory or extensions folder (or wherever you put it.) Your links should not need to be modified unless the location of sheets.php changes.

Installation

The TNG Mod Manager will install the Family Group Worksheet (sheets.php) in the TNG root folder. It will install the language files, modify cust_text.php files, and create a link in the TNG drop down menu labeled "Find". Even so, the link will not completely satisfy, mainly because the drop down menus don't always appear on the home page. Because of the variety of TNG and custom templates, TNG Mod Manager is unable to install additional links. Administrators will need to manually create them. There are techniques for hiding links from unregistered users, but we will only deal with visible links here. If an unregistered user clicks on them, they will be taken to the site's log in page. See our tutorial: Linking to the Worksheet.

TNG Mod Manager Installation

To install the Family Group Worksheet using the Mod Manager:

  • Download sheets.zip and unpack it in your mods folder (not to a sub-folder).
  • Open your Admin panel and click on Mod Manager. You should see the Family Group Worksheet ready to be installed.
  • Click to install it.
  • Check that the link appears in the "Find" drop down menu.

Fgw003.jpg

Manual Installation

To manually install the Family Group Worksheet:

  • Download sheets.zip and extract the files to a temporary work area.
  • Place the worksheet (sheets.php) somewhere on your website perhaps in the TNG root directory.
  • Open the fgws folder and copy all the language files to the appropriate language folders. For example, copy ws.english.php to the languages/English folder.
  • Copy the help file to the appropriate folders and rename them ws.help.php. For example, copy ws.english.help.php to languages/English/ws.help.php.
  • Use a code editor to add the following to cust_text.php in each folder, using the appropriate link name for the language and making sure to 'include' the correct language file.
$text['ws_linkname'] = "Submit Family";
if( $textpart == "worksheet" ) 
    @include( "ws.english.php");

The variable $text['ws_linkname'] determines the name of the link that will appear in the menus.

  • Repeat the above steps for each language you choose to support. Be sure to set $text['ws_linkname'] as appropriate in each language.
  • Create menu or page links to access the worksheet (see next section).
  • Discard the worksheet.cfg file.

Linking to the Worksheet

The Family Group Worksheet, like any other web page, would not be useful if the visitor could not access it via some kind of link, either in a menu, with a button or in some kind of text links.

The administrator must decide where best to link to the Family Group Worksheet:

  1. Embed a link in text displayed on the home page;
  2. Add a link to a home page menu.
  3. Add a link to a top or side menu.
  4. Add a link to the TNG drop down menus. This one is done by the Family Group Worksheet mod if you choose to use it.


We will take a look at the first three, one at a time and use a concept called coding by example, where you don't need to understand each element of the code, you just need to duplicate it, changing content to suit your needs, but keeping all the surrounding code and symbols intact.

Links in HTML and PHP are very similar.

Display a Link in Text

The first example assumes your sheets.php file is in your TNG root folder and you want the underlined link text to be 'click here'.

<a href="sheets.php">click here</a>

The next example assumes your sheets.php file is in a folder named 'uploads' and that you want the underlined link text to be 'Family Group Worksheet.'

<a href="uploads/sheets.php">Family Group Worksheet</a>

Here are a couple of sentences containing HTML links to the worksheet.

Please <a href="sheets.php">click here</a> to fill out 
a family group worksheet to add your family to our website.

Result: Please click here to fill out a family group worksheet to add your family to our website.

Use our <a href="uploads/sheets.php">Family Group Worksheet</a> to upload 
your family for inclusion in our website.

Result: Use our Family Group Worksheet to upload your family for inclusion in our website.

Add Link to Home Page Menu

There are a variety of possible menus on a TNG Website. Some home pages only contain one menu that is coded in the index.php file. To add a link to an existing menu, open the file containing the menu with a code editor, and find the PHP or HTML code that creates the menu items. You will see a number of entries similar to the HTML links shown above. The way to add a link is to determine where in the menu you want to place it, open up an empty line for typing, copy and past one of the existing lines, and change the path and link text, being careful to not to change any of the other surrounding code.

Fgw005.jpg

Lets start with a menu that is unique to the home page -- that is, only found in the index.php (home page) file. Such is the case in template 5, where there are three lines of links near the top of the home page. If we open index.php we find a section marked "third Line of Links." It starts with a link to Notes and ends with a link to the Contact form. Let's insert a link just before 'Contact Us'.

Fgw004.jpg

As we mentioned earlier, this is coding by example. We have inserted an empty line between Bookmarks and Contact US. We copied the line above it, inserted it where we want the new link, and changed only the path and link name. A predefined variable -- $text['ws_linkname'] -- was placed by the Family Group Worksheet mod in our cust_text.php to name the link in whatever language is chosen.

Note of caution: make sure you have a fresh copy of any file you modify just in case things go awry.

Keep in mind, if you modify a TNG file in this way, a TNG upgrade may well replace the file and your link will be lost. As you get comfortable making this kind of change, spend some time learning how to use the Mod Manager. It was specifically designed to "remember" modifications and uninstall them, or reinstall them after an upgrade. Look at sheets.cfg as an example.

Add Link to Top or Side Menu

template 4 vertical menu
template 4

Each TNG template has a file named topmenu.php. In some templates this produces a horizontal menu across the top of the page. In others, it creates a vertical menu down the left side of the page. Either menu is a good place to put a link to the Family Group Worksheet.

Template 4 uses a vertical menu on the left, so let's insert a link after Most Wanted. Open topmenu.php, find the menu items and locate the link for Most Wanted, open an empty line after it, copy an existing line into it, and modify the path and link label. Be careful to leave all the other code unchanged. Fgw007.jpg

Styling the Worksheet

Near the top of sheets.php is a code section titled, "SET WORKSHEET STYLES HERE". You can set colors for the worksheet background, text, labels, borders and messages. Be careful of modifying the CSS portion of the script as it controls the size and shape of the worksheet.

Languages

Because of the amount of translated text used in the Family Group Worksheet, and for ease of maintenance, we are providing a separate file for each language rather than including it in the cust_text.php files.

The Family Group Worksheet mod language packs will copy the appropriate language files into their corresponding folders. Those who install manually, must drop a language file into the folder for each language they support. They must also modify the cust_text.php files to add the text for the link label and to conditionally include the language file for the worksheet. Obviously, if they only use English there is no need to install the other files.

At the moment the only help file we have is in English. If help is not found in other languages, Family Group Worksheet defaults to English.

Where they are available, the Family Group Worksheet uses existing TNG translations from the standard language files -- you can see a list of them near the top of sheets.php where they are being assigned. If you want to modify one of them for the worksheet, without modifying it for the rest of TNG, you can add a definition to your cust_text.php file for the language in question. For instance, the worksheet assigns $text['ws_personid'] to TNG's $text['personid'], but you can override this by assigning it in the cust_text.php file -- $text['ws_personid'] = "PID"; notice only the worsheet variable beginning with 'ws_' is modified, not the TNG definitions. Be sure to add it before the worksheet's language file 'include' statement.

Issues and Workarounds

Email

TNG version: 8.1.2

Family Group Worksheet uses the latest TNG code to send email messages. This code is only available starting with TNGv813. If you have an earlier version of TNG8, and you cannot upgrade, you can still use the worksheet with the following workaround.

Download tngupgrade812-813.zip, take out three files --

  • tngmaillib.php,
  • class.phpmailer.php
  • class.smtpmailer.php

and drop them into your current TNG8 installation. They will only be used by this form. The rest of your installation won't even know they are there. If you have an SMTP account, you will have to fill in your account information at the top of tngmaillib.php.

Sometimes administrators may not want to have their 'system' address used for these emails. In that case, they can define the following two variables in their customconfig.php file:

 $adminaddr = "me@mymail.com";
$adminname = "mypreferredname";

Of course, $adminaddr must be assigned a valid email address.

Username

The Worksheet will fail if any users, including the Administrator, select a two-word Username contrary to TNG instructions which require that a Username be a single word.

Credits

Family Group Worksheet was written by William Bisbee, Oct 2011 with invaluable contributions from:

Roger Mitchell, http://mfo.me.uk (Mitchell Family Online);

Douglas Couch, http://www.adkinshorton.net (Adkins - Horton Genealogy)

Graham Chamberlain, Chamberlain and Eidenbenz Genealogy -- provisional French, German and Spanish translations

Joop Giesendanner, http://www.oudheidkamer.info/genealogie/ (Oudheidkamer Oostzaan) -- Dutch translations

Bryan S. Larson, Our Family Histories -- addition of LDS fields

and the members of tngusers2


Disclaimer

There is no warranty. Use the script at your own risk. It has been tested in all the TNG template styles without any particular problems.

Sites Using

The following sites are using the the Family Group Worksheet (please add your website if it applies):

  • Our Family Histories to view LDS and non-LDS versions of the form, use the following usernames/passwords: ldsguest/ldsguest or guest/guest