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.

Revision History

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.

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.

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.

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.

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.

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:

Embed a link in text displayed on the home page;

Add a link to a home page menu.

Add a link to a top or side menu.

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.

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.

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

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

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.

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: