User:Robinrichm

From TNG_Wiki
Revision as of 19:26, 26 May 2020 by Robinrichm (talk | contribs)

Jump to: navigation, search

Robin Richmond

My Contact Form
Location: Cleveland, Ohio
Occupation: College Information Technology Instructor
Programming:

  • Learned FORTRAN in (OMG) 1970, and did my first Family Tree-related programming in Fortran in about 1976.
  • Wrote my first PC genealogy software with QuickBasic for 8-bit CP/M machines in the early 1980's. (I used essentially that same application, with static charts copied to the web, until I started using TNG in 2013!)
  • Ph.D. Dissertation dealt with MUMPS programming language (now known as M or Cache').
  • Used MS Basic family of languages (esp VB Script/ASP) in the '00's.
  • Learned PHP after I bought TNG in August, 2013.

My Web Sites

  1. My TNG site
  2. My vanity site

My Mods

My Mod Manager Compare mod installs a utility that generates a mod list that is similar to the mods on a site to list the published

  • The 60ish public mods that I've written.
    (Note that some of the mods that are meant to be public don't yet have Wiki articles, and not all of my Wiki articles have the latest version of my mods.) If you would like a mod or mod version that I haven't uploaded yet, let me know, and I'll prioritize it.
  • Other mods that I use.
    I have added the suffix "-RR" to mods that I have tweaked. I occasionally change the functionality a bit, but most of the time, all that I have done to these mods is to
    • Insert %author tags, and
    • Add comments around insertions so that I can easily see which mod inserted each new block of text in each file.

Neither list provides summaries of each mod's purpose. To find out what a mod does, you'll need to follow the link to the mod's Wiki article.

Mods in development

Please let me know if you see something that you would like for me to prioritize.

Name Description Status
Admin Places Copy Copy certain fields from one TNG site (for example, a production site) to another (such as a development site). This is not the same as, backing up the table on one site and then loading the table on another. For instance, it lets you keep non-empty values, or only copy values that are not empty. Working fine for me
Search Trailing Spaces Allows leading and trailing spaces in People firstname and lastname searches seems to work fine
Place Name Format (upgrade) Upgrade to Place Name Format that
  1. Standardizes Placename formats interactively - not just in the Gedcom Converter, and
  2. Handles non-USA places.
Almost working
Name Description Status
Admin Source List Column
  1. Breaks the often-very-long list of objects that link to a source into two columns, and adds hyperlinks to those objects.
  2. Potentially groups those object according to shared medialinks or other shared attributes
Working prototype for #1
File Browser Browses through TNG files & folders, displaying descriptions of them based initially on the appendix.html file that is supplied with TNG releases. Working prototype
Browse Branches Restricted In browsebranches.php, shows only those branches that the user has rights to. Searches for partial match in branch ID and in branch name separately. Also shows full branch membership count, not just count of records the user can see. Still only lists records the user can see. Incomplete
Name Description Status
File Browser Browses through TNG files & folders, displaying descriptions of them based initially on the appendix.html file that is supplied with TNG releases. Early draft
Snapshot Saves snapshots of database counts into two snapshot tables, to provide a historical record of the growth of the database. For now, the Gedcom Import Monitor mod takes a bit of a snapshot when a Gedcom file is imported. Barely started
Generic Citations Store primary built-in events into the same table as custom events to facilitate analysis. It's awkwardly challenging, for example, to write a query that looks at all burial events, especially if citations and notes are involved. I don't know yet whether this will wind up being a brand-new table for analysis only, or whether I can add built-in events to the existing events table and flag them so they are not misinterpreted as custom events. Conceptual
All Events Store built-in events (now in Places and Families) and custom events (now in Events) in one table to facilitate analysis. For example, these queries are difficult with the native event structure since they have to look at several specific fields in Places and Families. Doing so requires several SQL Unions.
  1. Find all events that occur in a given place (i.e. find al; references to a place)
  2. If you have secondary birth events, list all births. (placesearch.php gives up, and has separate lists for primary birth events and secondary events.)

I don't know yet whether this will wind up being a brand-new table for analysis only, or whether I can add built-in events to the existing events table and flag them so they are not misinterpreted as custom events.

Conceptual

Beta Mod Updates

TextPlus Charts

v17 is nearly ready for release, but it has some beta features that need review and feedback.

  • The TextPlus Charts Wiki Article, which is for version 16d
  • The current beta version: Media:textplus_charts_v12.0.0.17beta5a.zip
  • The languages-specific help files and their images take up too much space for them to be included in the main mod distribution file, so they need to be installed as separate mods. The Text+ Charts help files no longer work like classic TNG help files. The help file content is in Include files in the mod subfolder of each of the language mods, a generic Text+ help file program loads the appropriate help file contents.

You can view the beta TextPlus program on my public web site.

Mod Options (unchanged in Beta5) [See Details]

[Hide Details]

Here are the current Text+ Charts mod options, which are in a Mod Settings Blocks at Admin>>Setup>>Chart Settings. (Mod Settings Blocks are not specific to TextPlus Charts; I've applied them to most of my mods.)

In this screenshot of the mod options, I've marked options associated with two sets of new features: "Recent" and "Beta", which are in separate lists below. The "Beta" features haven't been published yet.
Textplus17-modoptionsblock-annotated.jpg

[Hide The Options]

"Beta" Features (Only #2 has changed in the current Beta version; beta5) [See Details]

[Hide Details]

First - I'll note that mod options can hide all three of these features from end-users, so we don't have to worry about them being forced on end-users.

  1. Per a request, I have added the ability for name&age/birth/death/marriage data to be placed on separate lines, in essentially the same way that a couple of mods affect the Person Profile.
    Textplus-separatelines-descendant.jpg
    Two mod options control the availability of this feature.
    1. One mod option, marked as Beta1 above, determines whether the feature is active or not when the program loads.
    2. A second mod option, a checkbox marked as "Beta2" above, determines whether end users get to see and control several date/place settings, including this one.
  2. The section of the options form marked as as a box and labeled "Beta2" in the screenshot above can be duplicated in the TextPlus programs, where end-users can use it to control how dates and places are represented in the Text+ Charts. The checkbox labeled "Beta2" in the options screenshot above controls whether the options are also available to end-users. Here is the Date & Place form, showing the control that pulls down the form.
    Textplus-dateplaceoptions2.jpg
    • The subform's "Save as Defaults" button saves the current options in a permanent cookie. The settings saved in the cookie override (for just the current user) the settings established by the mod options, and, when the user clicks "Redisplay Chart", the settings in the form at that moment override the cookie settings.
    • On the Format for Printing page, the date/place subform does not redisplay the chart; it just changes the settings (and the cookie). The subform on this page has a "Close" button instead of "Redisplay Chart".
  3. At some point when I was looking at an Text+ Ancestor Chart, I decided that I'd like to see a summary of the family names (ancestral lines) that appear in the chart. So I conditionally added this:
    Textplus-ancestrallines1.jpg

    It then expands to

    Textplus-ancestrallines2.jpg
    where the hyperlinks go to the Person Profiles of the most distant ancestor in the chart with that name, and the "omit details" link never appears on a printed page.

    By "conditionally", I mean

    1. The details are not displayed as the page loads, as shown above
    2. The message with the "see details" link does not print, and
    3. A mod option suppresses it altogether

Edits I've made in the last week or two, in the last two beta versions:

  • 23 May - v17beta5
    1. Reworked the layout of and labels for the buttons that save and clear settings (and that submit or apply them in (1) the date/place pop-up forms, and (2) the Format for Printing fieldset.
    2. The new button design does not require any help file changes, except that I need to create new screen shots.
    3. Added about 15 language strings, mostly for the new save settings buttons. (I'll send email to the translators about that)
    4. Reworked the layout of the chart legends, putting the legend in a borded box, and adding the word "Legend" to the left of the legend.
    5. Added/updated Norwegian and French translations
    6. Added Norwegian and French help files.
    7. There are now separate help file mods for German, Norwegian, and French help files because adding language-specific help file images caused the main mod's zip file to exceed the TNG Wiki's file size limits.
    8. Several internal fixes and enhancements.
  • 18 May - v17beta4
    1. Changed the pop-up text for the "=>" hyperlinks to "More Ancestors" and "More Descendants", and added those two strings as language strings.
    2. Added the "More Ancestors" and "More Descendants" icon to both chart legends.
    3. Updated the help files to incorporate the beta features, which I now plan to keep - still with some questions stated below.
    4. Defined untranslated German help files, and German screenshots for the help files. (Both in the German-UTF8 language folder)
[Hide The Text+Charts Beta Documentation]

Other Recently-Implemented Features Most of these are already in the published version[See Details]

[Hide Details]


(Good grief! Even summarized, the changes are daunting. It might be best to check it out on my public web site first, and then read the details here.)

  1. (This is really a beta feature, come to think of it) I copied the "Locate person in chart" feature from the native Descendant Text chart, and have modified it fairly significantly.
    • The icon for this feature is now a spyglass. (There's a story and a question behind that choice of icon. Both are below, under the "Questions" heading)
    • There is a new, much simpler popup. I find this small popup to be much more handy and understandable than the old one.
      Textplus-locatedescendant.jpg
      The "Graphical view of this family line" hyperlink goes to the original chart that, to me, is overkill in most situations.
  2. I added a "locate person in chart" feature to the Ancestor chartTextplus-locateancestor.jpg
  3. Both charts can have "floating footers" that hang at the bottom of the web browser window so that they can always be seen. Both footer can be suppressed through mod options.
  4. Added an option that determines whether the descendant chart floating footer can reopen automatically after it has been closed explicitly. The "automatic" reopening occurs when the user hides or restores a branch of the chart using the plus and minus symbols next to spouse's names.
  5. Changed the "top" button in the floating footer to a smaller version of the TNG "Top of page" arrow that is only available in some templates. Both arrows can now be on the same page comfortably.
    Textplus17-summarydescendant.jpg
  6. Fixed a style rule that was limiting the charts to half of the screen width in Templates 13 and 14 (and perhaps some others)
  7. Added a link to the mod's options from a dummy mod parameter so the options are accessible from Mod Manager, like ordinary mod parameters.
  8. The native Inner Menu now always starts with the label "Chart Types".
    • FWIW, I've written an independent mod named "Chart Types Help" that adds this "Chart Types" label to all ancestor and descendant chart programs. But with the Chart Types Help mod, the "Chart Types" label is accompanied by a little information icon that pops up descriptions of the chart types. The unpublished Chart Types Help mod is described below along with some other brand-new, unpublished mods in its own subsection of this Wiki page.
  9. Notably, I've added some data/place formatting options, which can be seen in the outlined box in the mod options illustrated under the heading Text+ Mod Options just below.
  10. The charts have what I call an "Inner Mod Menu". Many of my mods add Inner Mod Menus to the programs that they modify "significantly" (according to my subjective judgement). Inner Mod Menus pull down from a "Mod Information" label at the right end of TNG's "inner menu" (just below the Tab menu), and contain handy links to information about the mod - particularly to the mod options.
    Textplus-innermodmenu.jpg
    (Importantly, Inner Mod Menus are can be see only by TNG Admins, not any end users.)
    Starting with this version of Text+Chart, Inner Mod Menus are defined by numerous mods, but displayed by the independent, optional mod Inner Mod Menus. Thus, you don't have to display Inner Mod Menus on your site if you don't want to.
[Hide Details]

Questions about Text+ Charts [See Details]

[Hide Details]
  1. I changed the "Locate person in chart" icon because of some other changes that I have abandoned.
    Question 1: Should I restore the icon that is used in the Descendant Text Chart, or leave the spyglass?
  2. I definitely do not like the native phrase "Descendancy chart to this point" that is used in the native Text decendancy chart. But I'm also not crazy about the description I'm using in the legend and in both Text+ charts - "Locate person in chart"
    Question 2 Any suggestions for a phrase to identify this feature? in the chart legend, and in the icon title text?
  3. The "Ancestral lines that end in each generation" feature...
    • First - I have decided to implement a more comprehensive version of this feature in a separate "Count Ancestors" mod that, like "Count Descendants", would not really be a "chart" but would be launched from the Inner Menu, like the chart programs, using the label "Count". The surnames would be listed in a table similar to this one from Count Descendants, where the counts shown in this screen clip would just be check marks or the equivalent.
      Count descendants-namesbygeneration.jpg
      On the other hand, the Ancestor Inner Menu is already awfully long.
    • 'Question 3: Assuming that I won't write the Count Ancestors mod for a while, should I publish v17 of the Ancestor chart with or without this feature? (Remember, admins can turn it off.)
    • Question 4: Assuming that you said "with" to the previous question, should I keep this feature in the Text+ Ancestor chart even after I publish the Count Ancestors mod?
[Hide Details]

Admin Media Search

Media:admin_media_search_v12.0.0.13.zip
I'm on the cusp of releasing version 13, but I'm worried about the mod options. I'll address some below, but I'll focus on mod options first. [See Details].

[Hide Details]

Admin Media Search Options

I knew that the this mod implemented too many search page features, and I got feedback to that effect, but I couldn't see my way clear to remove enough features to make a difference. Instead, I added mod options that suppress some of the search page options. Well, that gave me too many mod options, so I tried to simplify the mod options by adding even more mod options that hide some of the mod options. (Are you still with me?) The mod options now look like this:

Admin media search-modoptionsblock.jpg

The colored boxes are not for Wiki annotation; they are part of the implementation. They help to identify the blocks of options that are controlled by the headings. I think this is necessary since the Mod Settings Block jumps around on the screen when the blocks of options are opened and closed. (That jumping around could be avoided if I could anchor the Mod Settings Block to the top of the window, but I can't figure out a way to do that in the context of the Admin>>Setup programs.)

Here's what you see if you click both the "See Native Behavior" and "See Recommended Behavior" buttons in group 1, which is outlined in blue
Admin media search-optionsgroup1-behavior.jpg

The descriptions give you a glimpse of what the options and Admin Media Search program would look like, without requiring you to look at and make decisions about each option. If you just want to make sure that the program takes on the native or recommended behavior, you still don't have to see all of the options in their form fields. You can just click "Apply" and ignore those details. (Right now, the program doesn't give you feedback when you click "Apply", but I can fix that easily.)

Here are the form fields for group one, after they are opened by by the 'Show Settings' button.
Admin media search-optionsgroup1-settings.jpg
Unfortunately, the options program cannot tell you whether the option values are set to the native settings, the recommended settings, or custom settings. I've looked into doing that, but would take too much time to implement. But still, the point is that you don't have to deal with all of the options. You can just say, in effect 'Don't bother me with the details'. Finally, here's a screen clip of the Admin>>Media>>Search form, with the features controlled by groups 1, 2, 3, and 4 highlighted:
Admin media search-searchfields.jpg
Focusing on group 1, in blue, you can see the five database fields that can be searched, with checkboxes to control whether each is searched, and with two of the checkboxes checked by default.

New Features

In truth, I do need to back off on at least one, and perhaps break another feature off into a separate, though coordination issues would come into play. I'll work on that and come back to this beta description when I'm done, but in the meantime...

Questions

  1. What do you think of the technique of hiding options and allow the user to set Native and Recommented settings without bothering to look at the options fields?
  2. In the mod options screen clip above you can see that I have 3 single-option "Groups", numbers 2, 3, and 5. Even though they aren't really related, I'm thinking about putting them in a single group just to be consistent with notion of "Groups". What do you think?
[Hide The Admin Media Search Beta Documentation]

New Mods

These mods have not been published, and may not be worthy of publishing. I think that the first three (cleaned up as needed) would definitely be valuable as public mods. The fourth and maybe the fifth seem to be reasonable candidates. The sixth would be useful only to mod developers, and may be too idiosyncratic to be useful as a published mod.

1. Admin No Frameset

I previewed this mod on the TNGusers2 list about a year ago, and it may now be ready for release. In fact, Admin No Frameset already has Wiki article.
What does this mod need in order to be released as a production mod?

2. Admin Secondary Processes

The native Import/Export Secondary Processes have always struck me as being klunkier than they should be. This simple mod improves that workflow. [See Details].

Admin secondary processes-2.jpg

  1. It remembers the last tree that was imported, and defaults to that tree for each secondary process,
  2. It displays the Secondary Process menu right below the results of each process, so that you don't have to go back to the Secondary Process menu each time.
  3. It also displays a warning message when you click on the "Relabel Branches" link. The warning notes that the " process really just restores branch labels from the branchlinks table, and does not take in account any changes in the imported Gedcom file that should change some records' branch assignments.
    • Right now, the warning is a Javascript confirm box, but the full message doesn't fit into the confirm box, so I intend to use a TNG LitBox instead.

admin_secondary_processes_v12.3.0.0a

Questions

  1. I plan to productionize this mod soon, so please let me know if you have any suggestions for it.
[Hide The Admin Secondary Processes Documentation]

3. Admin Settings Save All

When modifying options in the various subforms at Admin>>Setup>>General Settings, I find it frustrating to have to scroll all the way down to the bottom of the page to find the only submit button. So this very simple mod adds submit buttons within the subforms. [See Details].

[Hide Details]

Admin settings save all-after.jpg
As you can see, the "Save" button as the bottom of the form now says "Save All", and each subform has its own "Save All" button. (I'm not sure why I didn't do the same to Admin>>Setup>>Chart Settings, but it sure wouldn't be hard to do so.
admin_settings_save_all_v12.0.0.1

Questions

  1. Whaddya think? Should I also patch Admin>>Setup>>Chart Settings? Should this mod be published?
[Hide the Admin Settings Save All Documentation]

4. Search Select Branch

This very simple mod adds a branch selection box to the end-user pull-down people search, but only for users who are logged in. [See Details].

[Hide Details]

If the user is assigned to a tree or branch, then that tree or branch is listed first, then "All". I think that users will want "All" most of the time, so I added an "All" button that lets users select "All" without having to click on the selection box, possibly scroll up to the top and select "All" there.

Here's a screen clip from my one-tree test site.
Search select branch-1tree.jpg

And here's a screen shot from a multi-tree site, where the trees are selectable by themselves, and all branches are identified as {tree}/{branch}
Search select branch-3trees.jpg
Note that "Robin / Hutcheson & Kuykendall" is the choice at the top of the selection list. That is because the user is assigned to that branch. That choice is also the initial default, and default is changed only when users select a different tree or branch. (FWIW, a the VERY top of the screeshot, you can see an enhancement I've made to my template, where it shows the current user's userID and branch.)

search_select_branch_v12.0.0.0a

Enhancements & Questions

  1. It appears that the Branch selection box in the Advanced People Search form only shows branches if the user is assigned to a branch, but it does show all branches. I don't really understand why the native branch search option works the way it does - if a user assigned to branch X can see and select branches Y and Z, I would expect logged in users who aren't assigned to a branch to be able to select branches Y and X (as well as X, of course). But it is what it is. Should this branch selection in the drop-down search work the same way as the selection in the Advanced search form?
  2. We don't often see "option groups" in selection boxes, but the tree/branch hierarchy could quite readily be represented by option groups, thus removing the tree name from the front of every branch name. What do you think?
  3. Anything else?
[Hide the Search Select Branch Documentation]

5. Chart Types Help

This very simple mod affects all of the native chart programs (and some charts installed by mods). It adds the label "Chart Types" in front of the chart types in the TNG "Inner Menu" (just below the tab menu). If you click on the little blue information button next to the Chart Types label, a description of each of the chart types pops up. [See Details].

[Hide Details]
In each chart program, the mod moves the "Generations" selection box to a new Inner Menu line. Here's a screen shot showing the popup for Descendant charts:
Chart type help-descend.jpg
The lists of chart types includes the TextPlus Charts charts, the Ancestor Map, the Count Descendants] "Chart", and the charts produced by the Male and Female Descendant and Parent Ancestor Lines if and only if those mods are installed.
chart_types_help_v12.0.0.0

Questions

  1. Should this mod be published?
  2. Should any other chart types produced by mods be conditionally included in the lists?
[Hide The Chart Types Help Documentation]

6. Mod Manager Check Files

This simple mod installs a utility program, primarily for mod developers, that scans selected mod .cfg files, looks at %copyfile directives, determines whether the mods' files are properly installed, and copies a new file over an older file if the source and destination do not match. . [See Details].

[Hide Details]
The status details for each mod in the Mod Manager list does a pretty good job of reporting which files are installed, but this one makes that information more visible, and significantly, determines whether each installed files matches the source file. Here is some sample output:
Mod manager check files v0a-results.jpg]
  1. 8 files have been selected by the filter in the lower portion of the page.
    • The Check Installed Files program actually starts with just the "Search for" and "Select Mods" fields.
  2. Only one of the 8 mods has any errors.
  3. When the source and destination file do not match, the older one is colored red, and the newer one is colored green.
  4. Mod #3 in the results - Mod Manager Check files v12.0.0.0 - installs 3 files, and two of them do not match.
    • For each of the files installed by the that nod, the source file is on the left, and the destination is on the right.
    • If you look that the two underlined mod/modfile names, you'll see that there are .cfg for Mod Manager Check files v0 and v0a.
    • So we can infer that the older mod is simply not installed.
  5. Still, the new installed files could be copied into the older (v0) subfolder.
  6. Only one file can be copied at a time, and when it is, the program submits to itself, copies the file, displays a copy acknowledgement (or error) message, and updates the results.
  7. The "Re-display" button reruns the program with the same mod selection, without re-copying any files that may have been copied as this instance of the page was loaded.

The Mod Manager Check Files mod does not try to indicate whether a mod has been installed, since Mod Manager already does that quite well. You can infer that if all files for a mod are in place, then it has been installed, and if all files are missing, then it has not been installed, but that's not the point. This mod is intended to focus on

  1. Files that have a different status from other files installed by the mod, and
  2. Files where the source and destination do not match.

Media:mod_manager_check_files_v12.0.0.0a

What this mod needs

  1. The search strings should be a dynamic Javascript filter instead of a search string that requires a form submission to take effect.

Questions

  1. I want to turn the search string into a filter, though my first attempt failed. Is it important to do that?
  2. Anything else? Is it worth pubishing?
[Hide the Mod Manager Check Files Documentation]

Mod Infrastructure

Some nonstandard things I do in most or at least many of my mods.

1. Inner Mod Menus

In each admin program that is significantly changed (whatever that means) by a mod, I add an "Inner Mod Menu" to the program's standard TNG "inner menu" (just below the tab menu. The Inner Mod Menu contains a link to the mod's Wiki article, and, optionally to

  1. The "Mod Options" section of the Wiki article
  2. The mod options editor, where the option are in a "Mod Settings Block"
  3. Pop text describing what the mod has done to the program.

See the Wiki article for the Inner Mod Menus mod.

2. Mod Settings Blocks

In almost all cases, I define mod options in Mod Settings Blocks that are in Admin>>Setup programs. This is not done by a mod; each of the mods that defines a Mod Settings Block contains and can install the necessary Include files. [See Details].

[Hide Details]

Mod Settings Blocks are distinct from other options in the Admin>>Setup programs in that

  1. The options for a mod are wrapped in a bordered block with a heading that states the mod's name and provides a link to the mod's Wiki article,
  2. I can link directly to a Mod Settings Block so that the TNG admin who wants to edit a mod's options doesn't have to open a specific subform within the Admin>>Setup program, nor scroll through other settings and other Mod Settings Block.
    • Links directly to a Mod Settings Block can be found in Inner Mod Menus and in the Mod Managers "Edit Options" page for that mod.

The distinct advantages that Mod Settings Blocks have over options defined by native Mod Manager %parameter% directives are that the options in Mod Settings Blocks

  1. Can be defined through checkboxes, radio buttons, and selection boxes,
  2. Can do validation,
  3. Can use Javascript as necessary to do things like disable an option that is not relevant when another option has a certain value,
  4. Can be composed of values form more than one form field,
  5. Can be combined with related options into tables and lists, and, notably
  6. Can be applied readily to more than one program, and even be used by programs modified by other mods.

See the Wiki article describing Mod Settings Blocks

[Hide Details]

3. Not Using genstyle.css

[See Details].

[Hide Details]

It just strikes me that there are way too many style rules in genstyle.css, and that the ones that are installed by mods generally only apply to one or two program. As a result, genstyle.css is cluttered with rules that are not needed there and that can conflict with each other. So,

  1. In mods that install more than one program, especially if I need a fair number of rules, I may create a separate external style sheets just for that mod.
  2. In several mods, I define an internal style sheet and use a Javascript document.ready script to move that style sheet in the DOM so the it is read before genstyle.css. This allows my style rules to be overridden by rules placed in the bottom of genstyle.css, or, even better, in a template's mytngstyle.css.
[Hide Details]

4. Document.ready functions

Aside from the use of document.ready functions to, say, initialize form field values and the like, I often use document.ready functions to change attributes of or insert HTML tags, and thus avoid having to modify the PHP/HTML text that generates those HTML tags. This can simplify the mod, and avoid conflicts with other mods.

5. Language Strings

As with genstyle.css, I'm not real comfortable adding language strings that will be used by only one or two programs. I've responded with two techniques: [See Details].

[Hide Details]
  1. Sometimes I place a flag variable at the very beginning of the program, before it loads language strings, and then I insert an If statement in the cust_text.php file(s) so that the strings are only loaded when the flag is set. With this technique, the strings are still in the cust_text files, but only the programs that need them load them into $text or $admtext.
  2. More recently, I've started storing language strings in PHP files in the mod subfolder. Those files are never installed. Instead the programs that are modified or installed by my mods explicitly Include those files, thus loading the strings into $text or $admtext.
    • The language files are all in a folder named "languages" within the mod's subfolder, and are named {language}_cust_text.php. I can thus use TNG's $mylanguage variable to find and read the files. That is, given the mod's folder name in $modfolder, I can read $modspath/$modsfolder/$mylanguage_cust_text.php.
    • Since, of course, I don't have strings for every language, the code in every program that uses this technique
      1. Includes the English file,
      2. If the current language is not English, checks for the presence of a file for the current language, and
      3. If the language file is present, reads it.
    • Two advantages of this technique, beyond reducing the clutter in cust_text.php files, are:
      1. I don't have to have define two identical files for English and English-UTF8, nor for other languages that don't depend on accented characters. Instead, when both encodings are identical:
        • For English-UTF8, I just omit the file, because this scheme always reads English file, and if the current language file is missing, that's fine.
        • For other languages, I define strings (usually) using the UTF-8 encoding, and the non-UTF-8 file just contains an Include statement that Includes the UTF8-file.
      2. When I'm developing a mod, I don't have to worry about uninstalling and reinstalling to load language strings. Once I edit the language file in the mod subfolder, modifications are available immediately.
    • For users to add new languages is trivial; they can just add strings to their language cust_text.php as with any other mod.
    • The native TNG cust_text.php files provide a very straightforward way for TNG admins to define overrides to mod-defined strings. Assuming that the relevant mods use the appropriate technique for loading strings into the conventional cust_text.php files (as defined explicitly in the TNGv12 Mod Manager Wiki documention), site admins can simply specify site-specific translation at the bottom of the applicable cust_text.php file. However, my technique for storing language strings always loads its language strings after the cust_text file has been read. To define site-specific overrides, admins must place the new values at the bottom of the mod's language file. Modifications to those files will not interfere with uninstallation of the mod, but they will be lost when the mod is unistalled. Right now, all I can suggest at this point is for site admins to document their overrides, perhaps by placing them in the bottom of the applicable cust_text.php file, where they will never be seen by TNG, but at least they will not be lost.
[Hide Details]

6. Comments

I comment code freely, but, in particular

  1. I place a comment at the very beginning of any file I edit, just to make sure that I actively declare that the mod has affected the file, and add a very short note about what the mod does.
  2. I add comments at the beginning and/or end of every insertions or replacement both to make sure that it is clear that the code I changes is not native code, and to assure that the insertion/replacement is unique.

Technical Notes

Most of the subsections below are derived from an TNG discussion list email message or TNG Community posting. They could become Wiki articles some day.

Wiki Templates

These are templates I use in web pages, whose names or syntax I keep forgetting:

  • construction|notes - Hard to believe that I forget this one, but I keep trying to capitalize the C, and forget the parameter name.
  • TNGver|ver = 12

|notes= - Floats to the right of text that specifically applies to TNGv12. For text that applies specifically You must install Wikipedia Link Mod which you must install first if you use both mods. It also conflicts with the OpenStreetMap mod. If you use the OpenStreetMap mod, you cannot install this Robinrichm mod.}}

  • RobinInstallationBoilerplate - A template that I use to display standard installation instructions in three subsections under a single "Installation" section. If the mod just has a .cfg file without a subfolder or related .cfg files, I say so. Otherwise, I add a message describing the subfolder or other .cfg files. See, for example TextPlus Charts#Installation.


MM Comparison Report Notes

[Show Details]

When a mod article has more than one download link in its right-side panel, the Mod Comparison Report can produce false negatives in its "Site1 vs Wiki" column.

Example 1:
Some mods show multiple downloads links, including variants that are intended for a particular purpose. For instance, a mod might have two download links like this:

best_mod_ever_v12.0.0.1.zip      TNG12 

Version that is compatible with Useless Mod:

best_mod_ever_v12.0.0.1-useless.zip

If you don't have Useless Mod, you don't care about the second link, and you may already have Best Mod Ever v12.0.0.1. But since the second link has what turns out to be a higher version "number" than the first link (counting'-useless'), the Mod Comparison Report will tell you that you don't have the latest version, when, practically speaking, you do.

Example 2:
If you do not have the latest version of TNG, many of the Wiki articles for your mods will have downloads for the newest TNG version, and you will find that many or most of your mods are reported as out of date. So, really, if you don't have the latest version of TNG, the Mod Comparison Report might not be useful to you.

[Hide MM Comparison Report Notes]

Double Toggle Example

(Incomplete)

[Show Details]

The TNG Wiki editor now includes three toggle buttons:

Button-Toggle.png The regular toggle button helps you specify text that will expand or collapse under the control of links with the fixed labels "[expand]" and "[collapse]".
File:Button-Show-Text.png This button starts a double-toggle.
File:Button-Hide-Text.png This button ends a double-toggle.

This example builds on the Wiki page editor's double-toggle but can't really be implemented with editor buttons. The two pieces of content to be toggled are HTML elements (usually <div>; sometimes <span>) that are

  • identified through the element ID mw-customcollapsible-toggleXXi', and
  • referenced by the classname mw-customtoggle-toggleXXi

where

  • XX is a short string that identifies the particular touble-toggle. (You really only need to worry about its value if you have more than one doube-toggle in the same Wiki article.)
  • i is '1' for the first piece of content to be toggled, and '2 for the second piece of content.

In Section 5.1 of this Wiki article; that is, the section you are reading or editing,is identified What you really have to do is:

  1. Edit this section of this article
  2. Copy the wikicode starting with the comment <!-- *** BEGIN DOUBLE TOGGLE --> and ending with the comment <!--END DOUBLE TOGGLE -->
  3. Paste that block of wikicode into your page.

...

[Hide Toggle button example]

The Code Inspector

[Show Details]

The Code Inspector is not a TNG thing; it is a feature of most web browsers, and allows you to inspect the page's HTML code; view the inline styles and style rules that affect specific HTML elements; add, disable, and enable style attributes; edit the "live" HTML (within the browser; not HTML source files); track down JavaScript errors; and much more.

  • The HTML code that the Inspector displays is not necessarily exactly like the source HTML. The inspector really inspects the HTML DOM, which contains tags and elements that are implied by the source HTML. Some implied tags are closing tags for un-closed HTML elements and <tbody> tags that are omitted from the source code.
  • Edits to the HTML code and styles stay in effect only as long as the page is loaded in the browser, and are erased if the page is reloaded.
  • You can inspect the HTML, including Javascript and CSS blocks, both by browsing an indented hierarchical view of the HTML, and by clicking on page elements.
  • When the inspector is active, and you click on any area of the page that that does not trigger a hyperlink or click event, the inspector with both highlight the HTML element immediately surrounding that content, and will highlight the portion of the web page that is subordinate to that element!

Task: Find the style rule (or inline style) that defines the color of certain elements in a web page.
More specifically, We want to find out where the pink background color of some table cells is defined.

Here's a clip of a Mod Manager Comparison Report that reveals one of the pink cells: Dom-modcompare-smallclip.jpg

In the web browser, I right-clicked on the pink area, and selected "Inspect".

The inspector in Chrome showed me this: (Other browsers would produce similar results)
Code inspector-badcfgs.png
In this screen clip:

  1. The parent HTML element of the content that I clicked on is a <td> element. I outlined it in red, and it is highlighted within the inspector by a grey bar (which is blue when you first select it), and by the string "-- #0"
    • Among other possibilities, the cell color could come from
      • Inline styles in the <td> elment, though we can immediately see that there is no style argument in the <td> tag,
      • One of the two style classes ("rrsite1data" and "badcfg") assigned to the element,
      • A style rule that affects all <td> elements, or just that specific <td> element,
      • A style rule that affects all <tr> elements, or just our <td> element's parent <tr> element, or
    • The attributes and content the <td> element are short enough that the full HTML element is displayed.
      • Look above at the <thead> element, and you'll see that its content is represented by an ellipsis. If you were to click on the triangular arrow next to that <thead> element element, the highest-level HTML elements within the <thead> elementlement would be displayed.
    • The <table>, <tbody>, and <tr> elements that contain this <td> element are open so that the <td> element can be displayed.
  2. Below, he styles section contains the rules that affect the highlighted HTML element. There, you can see that
    • The style rule at line 65 in rradmin_modcompare.css, with the selector #results td directly affects the selected <td> elements. That rule defines cell border and padding, but not the background color. within the element with ID='results". That's not the rule we are looking for
    • The style rule at line 297 in modmanager.css, with the selector .badcfg , the .badcfg background color is defined in line 297 of modmanager.css.
    • Other style rules that affect our <td> element could be shown further down in the list of relevant style (note the scroll bar to the right in the Styles area), but, as it turns out, any such rules that might exist would not supercede the rule that defines the background color of the .badcfg class.
    • Also, FWIW, I happen to know that the class "rrsite1data" is not used for styling, but, rather, is used to identify our <td> element's table column.

So, the answer is that our pink color comes from the .badcfg style, whose background color is defined in modmanager.css.
(Unfortunately, the inspector doesn't show the path to that css file. Other panels in the Code Inspector can show you the path to each component of a web page, but in this case, I already know that those CSS files are in the main TNG css folder, so I don't have to look further.)

[Hide Code Inspector Notes]

Colors in TNG Search Programs

[Show Details]

This note focuses on background colors and search results tables.

The TNG Admin and End-User programs that search for database objects and display search results in a "results table" are all quite similar. There are a couple of consistent differences between Admin and End-User search programs, but those difference are easy to reconcile.

The primary difference is the overall page layout.

  • End user program use the template scripts top-menu.php and footer.php to generate the outermost structures of end-user pages. The headings and most navigational elements are consistent in all end-user pages (for a given template), except for the the home page. Those headings and navigational elements are generated by TNG system functions that are called by each program. The HTML <div> element that wraps the content of each page begins in the last of those system functions, and ends in footer.php. Within that <div> element, the contents of end-user search pages match the contents of admin search pages very closely.
  • The outer navigation of admin pages is provided by a single admin frameset that wraps all admin pages. Just like the end-user pages, the admin pages call TNG system functions to generate their page heading and additional navigation menus. But, as in end-user programs, there is a main content <div> element. Within that <div> element, the contents of admin search pages match the contents of end-user search pages very closely.
  • Here are side-by-side examples of an end-user search program and an admin search program
End-user Sources Search Admin Sources Search
Tablecolors-sources-page-enduser.jpg Tablecolors-sources-page-admin.jpg

Note that, when you ignore the navigational menus and the headings, and just focus the search form and results tables (which I outlined in black), you can see that the two programs have nearly identical content. The essential differences are in

  1. Colors, and
  2. Editing options in the Admin version.

Results table colors

The heading background areas on both pages are not specifically styled; they carry the white background assigned to the page <body> tag. The other areas on the page are colored by CSS style classes. In the tables, the same style classes control the cell borders.

Page Element End-user Sources Search Admin Sources Search
Heading Background "white" "white"
Search form background lightback databack
Results Table headings fieldname & fieldnameback fieldname & fieldnameback
Results Table data cells databack lightback

The four classes that are used to provide background colors for these pages have initial definitions in css/genstyle.css. Then, some of their attributes are changed in template stylesheets (templatestyle.css), but different attributes are changed in different templates.

The initial definitions in genstyle.css:
(insert and modify content of earlier email...)

[Hide Notes on Search Result Table Colors]

document.ready function

[Show Details]

A document.ready function is a Javascript function that handles the document "ready" event that is triggered after a page has loaded. It is useful for manipulation the HTML DOM to add and remove style attributes and style classes within HTML elements, and to add and remove HTML elements.

When a web browser finishes reading the HTML file, it triggers the "load" event for the <body> tag. At that point, the external files (images, JavaScript files, and external style sheets) have not necessarily been loaded into the browser, but the HTML code has. Still, the HTML code has not yet been compiled into the DOM.

Once the HTML code is compiled into the DOM, the browser triggers the "ready" event, which is not tied to an HTML element, but just to the document itself. As a result, the ready event handler cannot be defined in an "onready" attribute in an HTML element. Instead, it generally defined with jQuery code within a Javascript block this way:

$(document).ready(function() {
  //The body of the function goes here
});
}); //End of (document).ready function

Note that the so-called "document.ready" function is really defined as "$('document').ready();"

Example 1: A document.ready function that suppresses printing of the Inner menu and Tab menu in TNG pages:

First, here is a style class that I typically define to suppress printing of selected elements on a page.

@media print {
    .rrnoprint {display:none;} /* Styling for other things we don't want to print */
}

This style rule, which takes effect only when a web page is being printed, simply hides elements it is applied to. I typically apply this class to forms and navigation menus, which are displayed in a web browser; but this class prevents them from printing. The effect of this class is very similar to the effect of TNG's "Format for Printing" feature, which sets a querystring parameter (tngprint=1), reloads the page, and depends on PHP to omit such structures from the HTML page altogether. My rrnoprint class takes effect even when the "main" TNG page is printed. It is particularly handy in Admin pages, since they don't implement the TNG Format for Printing feature.

Here is a document.ready function that applies this class to the two navigational menus (The Tab menu and the Inner menu) that are present on most HTML pages.

$(document).ready(function() {
    //(In TNG pages, the Inner menu has id="adm-innermenu", but the tab menu
    //doesn't have an ID.  However, the tab menu is the only sibling of the
    //Inner menu.  That is, the Tab menu and the Innermenu for the entire content
    //of their parent div (which also has no ID).
    //This statement finds the immediate parent of the Inner Menu, and applies
    //the .rrnoprint class to it.
    $('#adm-innermenu').parent().addClass('rrnoprinter');
}); //End of document.ready

One of the very significant things about this document.ready function is that it can apply the .rrnoprint class to the Tab Menu and the Inner menu in any TNG program, without touching the HTML code. A more traditional way to add a class to an HTML element would be through a .cfg file target location. But

  1. Without an ID on the HTML element that contains the menus, it is difficult to find short target location search text that is unique to the desired element, and
  2. If the HTML of the desired element were to be changed, other mods that try to modify the same HTML code would fail.

Fortunately, if two (or more mods) each created a document.ready function that did the exact same thing as this one, nothing bad would happen. The .rrnoprinter class would be applied three times, but once it has been applied to an element, additional applications of the class to the element do nothing.

Example 2 - More document.ready cleanup

$(document).ready(function() {
    //1. Apply the standard TNG results table formatting classes to cells in the results table.
    //Most TNG programs specify class='fieldname fieldnameback' in the th
    //(or, too, often heading rows td) elements of a results table.
    //In the programs that I write and install (as opposed to programs that I mod), I
    // - assign id='results' to the results table, 
    // - always use <th> elements in the table heading rows (if I want them 
    /    highlighted like column headings),
    // - put the heading rows in a <thead> element.
    // So this statement adds the two fieldname classes to each table header cell.
    // I use "child" instead of "descendant" selectors here so that tables 
    // within the result table are not affected by these style rules.
    $('#results>thead>tr>th').addClass('fieldname fieldnameback');
    // Then I do essentially the same thing with the databack (or in some cases
    // lightback) class in the data cells.    
    $('#results>tbody>tr>td').addClass('databack');

     //2. Erase an HTML element that was I was using to show progress as the program was
     //running and the HTML code was being generated.  I'm not really sure why I
     //didn't remove the element altogether. 
     $('#initialcounts').hide();
}); //End of (document).ready function
[Hide First set of Notes on document.ready functions]

Document.ready and striping

[Show Details]

Here is another document.ready function that I use in my Mod Comparison Report to define the same "striping" as in the Mod Manager List. It uses two Mod Manager options:

  • $options['use_striping'] is a flag that tells us whether to stripe the rows.
  • $options['stripe_after'] tells us how many consecutive rows use the same color.
    (For simplification in the explanation below, I'll assume that this option value is 3.)

The colors are defined by the two TNG class "databack" and "databackalt".

&lt;script>
$(document).ready(function() {
<?php
#Apply striping to the results table rows if the striping flag is set
if ($options['use_striping']) {
    $n = 2*$options['stripe_after'];
    #The for statement loops the 3 times, since (we assume) $options['stripe_after']=3
    #Each time through the loop, two JQuery statement are created. One JQuery statement
    #applies .databack to every sixth row in the body of the results table,
    #starting with row 1.  The second JQuery statement applies .databackalt to every
    #sixth row, starting with row 4.
    for ($i=1; $i<=$options['stripe_after']; $i++) {
        echo "$('#results tbody tr:nth-child({$n}n+{$i})').addClass('databack');\n";
        $ii=$i+$options['stripe_after'];
	echo "$('#results tbody tr:nth-child({$n}n+{$ii})').addClass('databackalt');\n";
    }
}
?>
}); //End of (document).ready function
&lt;/script>

If striping is turned on, and the striping count is 3, then this PHP code generates the following document.ready function:

<script>
$(document).ready(function() {
$('#results tbody tr:nth-child(6n+1)').addClass('databack');\n";
$('#results tbody tr:nth-child(6n+4)').addClass('databackalt');\n";
$('#results tbody tr:nth-child(6n+2)').addClass('databack');\n";
$('#results tbody tr:nth-child(6n+5)').addClass('databackalt');\n";
$('#results tbody tr:nth-child(6n+3)').addClass('databack');\n";
$('#results tbody tr:nth-child(6n+6)').addClass('databackalt');\n";
}); //End of (document).ready function
</script>

(In the CSS nth-child selector, 'n' automaticaly counts from 0 to the end of the table, and the table row number calculated using 'n' needs to start with row 1, not row 0. Also 'n' is a syntactic element of the )

Application of .databack in the code above

When I assembled the example above, I was struck by the realizations that

  1. I was applying .databack to rows, rather than to cells, where it is normally applied. The .databack class has border attributes that are used to apply borders to each data cell in the results table. Applying .databack to the row does apply .databack's colors to each cell in the row, but does not apply .databack's border attributes to each cell. So where to the table cells' border attribute come from?
  2. The PHP code above doesn't apply the .databack (or .databackalt) to the results table cells except when striping. So when there is no striping, how do the results table get their colors?

The answers to both questions is supplied by the code inspector. First, I'll show three inspections of unmodded TNG Admin program, admin_sources.php:

 and add a couple of TNG page screen clips to help illustrate what is going on.

First, a screen clip from an arbitrary TNG Admin page, with a results table. I'll pick Sources... Then the mod comparison report and the style inspector...

Now the styles again Applying them to rows works only because

  • The rule I mentioned above, at line 65 of rradmin_modcompare.css, applies the border attributes that .databack would normally apply to cells, and
  • When I apply .databack to a table row:
    • The .databack border attribute only apply to the row, not each cell, but, best I can tell, they don't really do anything, and
    • The .databack background color attribute does apply to every cell in the row.
[Hide additional document.ready notes]

Customizing index.php

[Show Details]

As you must already know, if you are not using a template, then yes, the TNG home page is very sketchy, but it isn't hard to modify index.php to your liking, or just to change

if( && $templateswitching && $templatenum) {
	include($cms['tngpath'] . "templates/$templatepfx$templatenum/index.php");
	exit;
}
to

include( "mycustomhomepage.php")
which allows you to create a completely custom home page with very little modification to index.php.

In the home page, only two internal TNG components are critical:

  1. The statement include("tng_begin.php"); at the beginning of the file.
    • tng_begin.php loads TNG system variables and $text variables, opens the database, and so on.
  2. The call to tng_header() shortly below that.
    • tng_header() defines the page's <head> element and <body> tag, and in doing so, generates a number of essential <script> tags for Javascript code and <link> tags for CSS files.

If you do want to override style attributes defined in the CSS files in the css folder (or in a template's css folder) you really shouldn't modify the existing CSS rules in-place. Instead:

  • If you use a template, then add rules to the template's mytngstyle.css,
  • If not, add rules to the main TNG mytngstyle.css.

(BTW, it is not intuitive - at least to me - that the main mytngstyle.css is ignored by the TNG setup code if you do use a template. That's why mods, which generally have to work for all templates, have to place most CSS modifications at the bottom of css/genstyle.css.)

If you are using a template, the TNG home page (index.php) includes (using the PHP meaning of the term) your template's index.php file.

You can completely replace the main index.php if you want (whether you use a template or not), or completely replace your template's index.php. I use Template 5, and I wrote a private mod to modify it, but wound up just editing it by hand. To protect the pristine code, and my modification, I backed up index.php as index-pristine.php, and backed up up my custom index.php as index-custom.php.

It would be handy if template index.php files were interchangeable, but that is not practical. Different templates depend on different classnames and style rules from their css files, and, of course, the same classes are used by index.php and topmenu.php, so you can't go half-way to another template. That doesn't mean that you can't adapt one template's index.php for use with another template, but you are likely to need to modify classnames within the index.php (and possibly create rules in the template's mytngstyle.css) to accomplish that.

Modifying a template's index.php file is not that hard; standard TNG pieces and parts generally do not apply to the index.php files. You can modify the template strings and image files through the form at Admin>>Template Settings, or you can replace the references to those strings and images inside the index.php file with hardcoded strings. Certainly, my notes above about the critical TNG components in the main index.php file apply here, too (well, except that the template's index.php file does not have to include tng_begin.php, because the main index.php file does so before it includes the template's index.php).

[Hide Notes on index.php]

genstyle.css Issues

Internal Style Sheets

[Show Details]

My mods generally do not add style rules to genstyle.css because

  1. genstyle.css has SO MANY rules already,
  2. The rules added by most mods affect only one or two programs, and just take up space in genstyle.css for other programs, and
  3. Keeping them separate helps to avoid classname conflicts between mods.

Some of my mods define stand-alone .css files, but most of my mods define an inline style sheet.

Sometimes, TNG site administrator wants to override style rules that are in defined genstyle.css (whether those styles are native or were added by a mod). There are two straightforward places to define supplemental rules of this sort:

  1. A template's mytngstyle.css, or
  2. the main genstyle.css file.

The first choice is generally the best, since genstyle.css is typically updated in TNG releases, and copying the new genstyle.css to your site would erase all of your hand-coded rules. But if a site uses multiple templates, using mytngstyle.css to supplement genstyle.css rules requires those rules to be defined in each template's mytngstyle.css.

More to the point, neither of these file work straightforwardly as a place for rules that override my inline stylesheets, because the Included template code that loads genstyle.css into the page (almost) necessarily occurs before an inline style sheet can be defined.

I use some jQuery code in a document.ready function to address this problem. That is

  1. I add an HTML element ID to the <style> tag with which I start my internal stylesheets, like this:
    <style id='rramsstyle'>, where rramsstyle is contrived to be unique to a mod.
  2. In a document.ready function (which is triggered once the page's DOM has been build), I add jQuery code that moves the stylesheet within the DOM (that is, within the web page in the web browser) so that my stylesheet precedes the <link> tags that load genstyle.css and the template's mytngstyle.css. Here is that code:
$(function() {
    //Move the embedded style sheet so that it is before css/genstyle.css in the DOM.
    //This allows updates to be made in genstyle.css or the user's template's mygenstyle.css
    var stylesheet = $('#rramsstyle').html();
    $("#rrams_style").remove();
    $("link[href^='css/genstyle.css']").before("<style>"+stylesheet+"</style>");
}
[Hide stylesheet notes]

What is GEDCOM?

GEDCOM is a formal technical standard whose stated purpose is

"to provide a flexible, uniform format for exchanging computerized genealogical data".

The name "GEDCOM" is an acronym for GEnealogical Data COMmunications. GEDCIN is

  • a data and file format,
  • a description of genealogical data elements and structures, and
  • a specification that maps those genealogical elements and structures to the file format.

As a consequence, GEDCOM also provides (or serves as a) Genealogy Data Model

The GEDCOM standard was first formalized in 1985, and when GEDCOM version 5.5 was released in 1996, it did such a good job of incorporating the data elements of current genealogy software that some widely-used genealogical software packages used GEDCOM files as their core data/database files.

Amazingly, although the features of (and data elements within) genealogical software packages have changed considerably since 1996, GEDCOM 5.5.1 (dated 2 Oct 1999) is the "current" version of GEDCOM'. (There is a draft GEDCOM 5.6 standard, from 2000, but it ventured into XML as a file format, and never gained anyt traction.). Though the current GEDCOM standard is almost 20 years old and is far from perfect, it is very widely used, and it is essentially "all we have."

GEDCOM File Format

The GEDCOM data/file format is strictly text-based:

  • One GEDCOM file contains all of the data records that represent what we generally think of as a "family tree".
  • Records are organized hierarchically. For instance, a "Person" record contains multiple "Event" records (Birth, Death, etc.), which contain "Date", "Place", and "Source" records, and so on.
  • GEDCOM records consist of
    • A line of text that consists of three space-separated elements:
      1. An integer "level number" that identifies the record's place in the record hierarchy.
      2. A short "Tag" (essentially a record type), and
      3. A possible tag value whose nature depends on the tag)
    • and all subordinate records, defined on subsequent lines with larger "level numbers"
  • GEDCOM tags are generally no more than 4 characters long
    • Some tag values essentially serve as attribute names (CITY, CTRY, PHON, AGE, NAME, SEX)
    • Some tag value are analogous to relational record types (INDI-individual person, FAM-family, OBJ-media object, etc.)
  • Long data values and textual data values that may contain end-of-line characters are broken into records that extend the value that was started in their parent record or in the previous record.
  • The top level of the hierarchy is level zero.

Overall, a GEDCOM file consists of

  1. A zero-level HEAD record that describes the file itself; filename, date, copyright, gedcom version, language, etc.
  2. A zero-level SUBM (submission) record that indicates who or what created the file, and that can describe the number of records or generations in the file.
  3. The data itself - in a series of zero-level data records (each of which contains the appropriate subordinate records)
  4. A zero-level TRLR record that simply marks the end of the file.

GEDCOM Person Record

Each person (which GEDCOM calls an "Individual") is defined in a zero-level GEDCOM record, with, of course, all necessary subordinate records. n a GEDCOM file is Here's a hypothetical GEDCOM excerpt of a single zdescribing part of my grandmother's genealogy record. I've indented the text lines lines to illustrate the hierarchical structure, and added colored, italicized text as documentation.

0 @I4526@ INDI Level 0 INDIvidual record - person #I4526
  1 NAME Ida Marie /HAZLET/ NAME fact. Last names are typically marked with slashes
    2 SOUR @S41@ Source #S41 supports the Name fact
  1 BIRT Birth event
    2 SOUR @S77@ Source #S77 supports the Birth event
      3 Page 112 Info about her birth is on page 112 of the source
      3 DATA Relevant quote from the source
        4 TEXT Birth date: abt 1899 The beginning of the text
          5 CONT Birth place: Iowa The quotation continues
          5 CONT Residence date: 1915 The quotation continues
          5 CONT Residence place: Eden The last line of the quotation
       3 OBJE @M3349@ A media object associated with the Source (and the birth, and the person)
  1 SEX F Sex fact
  1 EDUC Harper College EDUC event
    2 DATE FROM 1920 TO 1923 The duration of the education event
    2 PLAC Harper, Harper, KS The place of the education event
  1 OBJE @M502@ Media object #M502 (probably a photo) is tied to this INDI record
  1 FAMS @F1513@ She is one of the spouses in Family #F1513
  1 FAMC @F2324@ She is a child of Family #F2324
0 @I43@ INDI The INDI record ends when the next Level 0 record starts

The actual complete GEDCOM record for my grandmother in my last extract was 266 lines long, and included birth, death, and residence events, plus additional source and media object references. But really, that additional length doesn't add to the complexity of the GEDCOM file; just to its volume.

See also

You can also review any GEDCOM file (you'll find plenty on the Internet) by opening it with a text editor or word processor. GEDCOM files are certainly not primarily written for human eyes, but they are structured text files, and it's pretty easy to understand them in small pieces.

GEDCOM Media Record

A media item in the GEDCOM file is represented by a set of lines that might look similar to the examples just below. Here is a hypothetical media record from an Apple MacIntosh environment. The record starts at level 0 with a OBJE (for media object) line, and contains 7 additional subordinate lines (all at level 1).

0 @M232@ OBJE 
1 FORM jpg
1 FILE ~/Documents/Documents/Genealogy/Roger/ReunionPictures/photos/people/RogerOval.JPG
1 TITL Roger Moffat
1 NOTE Taken at the time of Kurt and Ann Christensen's wedding - 2 March 1996.
1 _TYPE PHOTO
1 _PRIM Y
1 _SIZE 147.000000 193.000000

Note, in particular, the FILE line, which contains a fully specified filename, with its complete path on the Macintosh PC.

Here's the beginning of a comparable media record from a GEDCOM generated on a Windows PC. The only significant difference is that the PC GEDCOM (not surprisingly) uses Windows syntax to specify the filepath and filename.
0 @M232@ OBJE 
1 FORM jpg
1 FILE C:\Users\me\documents\gene\photos\people\RogerOval.JPG
...

GEDCOM data model (part 1)

(BTW - GEDCOM isn't supposed to be a data model, and many people will tell you that it isn't one. But the GEDCOM standard defines data structures for essentially genealogical concepts such as "events", "source citations", "people", "families", "sources", "repositories" (and more). For all practical purposes, those definitions ARE a data model.)

GEDCOM has six fundamental genealogical object types, which are identified by their record tags, and by a letter that prefixes their record ID:

  • People, that is, "Individuals": INDI (I)
  • Families: FAM (F)
  • Data sources: SOUR (S)
  • Repositories: REPO (R); places where data sources are held, such as libraries.
  • Notes: NOTE (N)
  • Media objects: OBJE (M). Generally, OBJE records simply describe media files.

Records of these six types are called "level zero" records, because they all start at level zero in the record hierarchy. In level-zero records,

  • The tag comes after the tag value, not before, and
  • The tag value is a record id, which is numeric except for an initial letter that identifies the object type.
    (Actually, in GEDCOM files, record ID's are always wrapped with @-signs.)


INDI and FAM records are quite similar. They consist primarily of

  • Level 1 "Event" records, in which the tag (NAME, BIRT, DEAT, OCCU...) represents a particular "event" or "attribute" (Name, birth, death, occupation...).

Event records typically contain subordinate level 2 records that specify

    • A date,
    • A place,
    • Source citations that can occupy several levels,

Event records and their subordinate records can also contain NOTE and OBJE records, which are typically just references to zero-level NOTE and OBJE records. For instance, if hich can be multiple levels, themselves)

  • SOUR, REPO, AND OBJE records are, for the most part, not really hierarchical. That is, they consist mostly of level 1 records that provide specific attributes such as source name, source title, source author, repository name, filename, file type, etc.
  • NOTE records just contain a value that is continued on subordinate level 1 CONC and CONT records.

are simply broken into chunks with CONT and CONT records. always and only consist of CONC and CONT r

      • A level 2 DATE record such as "2 DATE 15 Jan 1832",
      • A level 2 PLAC record such as "2 PLAC Chicago, Cook, Illinois, USA"
      • And often one or more level 2 Source Citation records that occupy multiplesource citation

The GEDCOM standard was developed and is owned by FamilySearch.org, a service of the Church of Jesus Christ of Latter-Day Saints (the Mormons). Its latest version dates to the 1990's, and is far from perfect, but it is very widely used, and it essentially "all we have."

Each line in a GEDCOM file starts with an integer number (typically less than 10) that represents that line's level in the hierarchy. Each line also has a record type keyword (INDI for Individual, EVEN for Event, DATE for date, etc.) known as a "Tag". A GEDCOM "record" consists of a line plus any subordinate lines - i.e. subsequent, contiguous lines that start with larger level numbers.