Difference between revisions of "User:Robinrichm"

From TNG_Wiki
Jump to navigation Jump to search
Line 89: Line 89:
 
v17 is nearly ready for release, but it has some of beta features that need review and feedback.
 
v17 is nearly ready for release, but it has some of beta features that need review and feedback.
 
<!-- *** BEGIN DOUBLE TOGGLE --><span class="mw-collapsible mw-customtoggle-textplus1 mw-customtoggle-textplus2" id='mw-customcollapsible-textplus1' style="text-decoration:underline;color:#0645ad;">&#91;See Details&#93;</span>
 
<!-- *** BEGIN DOUBLE TOGGLE --><span class="mw-collapsible mw-customtoggle-textplus1 mw-customtoggle-textplus2" id='mw-customcollapsible-textplus1' style="text-decoration:underline;color:#0645ad;">&#91;See Details&#93;</span>
<br>[[Media:textplus_charts_v12.0.0.17beta2.zip]]
+
<br>[[Media:textplus_charts_v12.0.0.17beta3.zip]]
 
<div class="mw-customtoggle-textplus1 mw-customtoggle-textplus2" class='mw-collapsible mw-collapsible-content mw-collapsed' id='mw-customcollapsible-textplus2' style="border:thin solid grey;"><!-- BEGIN TOGGLED CONTENT -->
 
<div class="mw-customtoggle-textplus1 mw-customtoggle-textplus2" class='mw-collapsible mw-collapsible-content mw-collapsed' id='mw-customcollapsible-textplus2' style="border:thin solid grey;"><!-- BEGIN TOGGLED CONTENT -->
 
<div class="mw-customtoggle-textplus1 mw-customtoggle-textplus2" style="text-decoration:underline;color:#0645ad;float:right;">&#91;Hide Details&#93;</div>
 
<div class="mw-customtoggle-textplus1 mw-customtoggle-textplus2" style="text-decoration:underline;color:#0645ad;float:right;">&#91;Hide Details&#93;</div>
Line 113: Line 113:
 
<li>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.</li>
 
<li>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.</li>
 
<li>The charts have what I call an "Inner Mod Menu". Many of my mods add Inner Mod Menus to the programs that they modify.  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.<br>[[Image:textplus-innermodmenu.jpg]]<br>
 
<li>The charts have what I call an "Inner Mod Menu". Many of my mods add Inner Mod Menus to the programs that they modify.  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.<br>[[Image:textplus-innermodmenu.jpg]]<br>
Starting with this version of Text+Chart, and other mods I am updating this month, Inner Mod Menus are ''defined'' by numerous mods, but ''displayed'' by the independent, optional mod '''[[Show Inner Mod Menus]]'''.  Thus, you don't have to display Inner Mod Menus on your site if you don't want to. (Importantly, Inner Mod Menus are can be see only by TNG Admins, not any end users.)</li>
+
Starting with this version of Text+Chart, and other mods I am updating this month, 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. (Importantly, Inner Mod Menus are can be see only by TNG Admins, not any end users.)</li>
 
</ol>
 
</ol>
  
Line 122: Line 122:
  
 
==== Text+ Beta Features ====
 
==== Text+ Beta Features ====
First - I'll note that mod options can hide all three of these features from end-users, so I don't really have to worry about them being forced on end-users. But I do have to wonder about whether it is appropriate to force TNG admins to deal with the mod options.
+
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.
 
<ol>
 
<ol>
 
<li>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.
 
<li>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.
Line 147: Line 147:
 
# I definitely do not like the native phrase "Descendancy chart to this point" that describes the text descendancy chart feature that I've implemented in the Text+ charts as "Locate person in chart", and I'm not crazy about my description either.<br>'''Question 2''' Any suggestions for a phrase to identify this feature in the chart legend, and in the icon title text?
 
# I definitely do not like the native phrase "Descendancy chart to this point" that describes the text descendancy chart feature that I've implemented in the Text+ charts as "Locate person in chart", and I'm not crazy about my description either.<br>'''Question 2''' Any suggestions for a phrase to identify this feature in the chart legend, and in the icon title text?
 
# The separations of name/birth/death/marriage onto separate lines...
 
# The separations of name/birth/death/marriage onto separate lines...
#* '''Question 3''': Other than the question of whether the end-user should control of this feature (which I address below) do you have any qualms or suggestions about this feature?
+
#* '''Question 3''': Other than the question of whether the end-user should control of this feature (which I address below) do you have any qualms or suggestions about this it?
 
# The date/place options...
 
# The date/place options...
#* '''Question 4''': Should the "Dates & Places" pull-down label be placed where it is in the screen clips above, or next to the Format for Printing button, where the form lines up to the pull-down label better?</li>
+
#* '''Question 4''': Should the "Dates & Places" pull-down label be placed where it is in the screen clips above, or next to the Format for Printing button, where the form lines up to the pull-down label better?
## The "Ancestral lines that end in each generation" feature...
+
#* '''Question 5''': If a site admin turns off the end-user "Dates & Places" form, TNG admins still have the ability to edit those options. And, if a site admin has installed [[Inner Mod Menus]], then the options are just a swipe-and-click away. Still, should the "Dates & Places" slide-down form be available ''only to Admins'' if it has been turned off for end-users?
 +
# The "Ancestral lines that end in each generation" feature...
 
#* First - I think that I've decided to implement 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. The family names could be reported in a table similar to this one from Count Descendants:<div>[[Image:count_descendants-namesbygeneration.jpg]]</div>On the other hand, the Ancestor Inner Menu is already awfully long.
 
#* First - I think that I've decided to implement 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. The family names could be reported in a table similar to this one from Count Descendants:<div>[[Image:count_descendants-namesbygeneration.jpg]]</div>On the other hand, the Ancestor Inner Menu is already awfully long.
#* '''Question 5''': Should I create that separate "Count Ancestors" mod and a "Count" link in the Ancestor Inner Menu?
+
#* '''Question 6''': Should I create that separate "Count Ancestors" mod and a "Count" link in the Ancestor Inner Menu, with a table like the one above that shows the generations in which each ancestral surname appears?
#* '''Question 6''': Let's assume that I do create the separate "Count Ancestors" mod. Should I then omit this summary of the ancestral lines from the Text+ Ancestor Chart summary?
+
#* '''Question 7''': Let's assume that I ''do'' create the separate "Count Ancestors" mod. Should I then omit this summary of the ancestral lines from the Text+ Ancestor Chart summary?
#* '''Question 7''': If I ''don't'' create the "Count Ancestors" mod, should I omit the ancestral lines data from the Text+ summary? (That would, of course, mean that it is not available at all, unless someone comes up with another place to put it.)
+
#* '''Question 8''': Even if I ''don't'' create the "Count Ancestors" mod, should I omit the ancestral lines data from the Text+ Ancestor Chart summary? (That would, of course, mean that it is not available at all, unless someone comes up with another place to put it.)
 
<!-- BUTTON AT THE BOTTOM OF TOGGLED CONTENT --><div class="mw-customtoggle-textplus1 mw-customtoggle-textplus2" style="text-decoration:underline;color:#0645ad;text-align:right;">&#91;Hide The Text+Charts Beta Documentation&#93;</div>
 
<!-- BUTTON AT THE BOTTOM OF TOGGLED CONTENT --><div class="mw-customtoggle-textplus1 mw-customtoggle-textplus2" style="text-decoration:underline;color:#0645ad;text-align:right;">&#91;Hide The Text+Charts Beta Documentation&#93;</div>
 
</div><!-- END TOGGLED CONTENT and END DOUBLE TOGGLE -->
 
</div><!-- END TOGGLED CONTENT and END DOUBLE TOGGLE -->
Line 279: Line 280:
 
# The mod options editor, where the option are in a "Mod Settings Block"
 
# The mod options editor, where the option are in a "Mod Settings Block"
 
# Pop text describing what the mod has done to the program.
 
# Pop text describing what the mod has done to the program.
See the Wiki article for the '''[[Show Inner Mod Menus]]''' mod.
+
See the Wiki article for the '''[[Inner Mod Menus]]''' mod.
  
 
=== 2. Mod Settings Blocks ===
 
=== 2. Mod Settings Blocks ===

Revision as of 11:48, 5 May 2020

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 of beta features that need review and feedback. [See Details]
Media:textplus_charts_v12.0.0.17beta3.zip

[Hide Details]

You can view the beta TextPlus program on my public web site. You will not see the Inner Mod Menu there, since you will not be an Administrator. Note that the behavior of that page will change as I update the beta (or turn it into a production mod), but I certainly plan to update this text as I update the mod.

The .cfg has extensive revision notes. Here's a summary of recent changes:
(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. In an earlier version, I copied the "Locate person in chart" feature from the native Descendant Text chart, but now I've modified it fairly significantly.
    • The icon for this feature is now a spyglass.
    • There is a new, much simpler popup that links to the old one. 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. Also added a "locate person in chart" feature to the Ancestor chartTextplus-locateancestor.jpg
  3. Added options to handle the presence of the floating footers in both charts. (See a screen clip of the options below.)
  4. Added an option that determines whether the descendant chart floating footer can reopen automatically after it has been closed explicitly.
  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 breaking Template 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 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. 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
    Starting with this version of Text+Chart, and other mods I am updating this month, 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. (Importantly, Inner Mod Menus are can be see only by TNG Admins, not any end users.)

Text+ Mod Options

The Text+ Charts mod options, which are in a Mod Settings Blocks at Admin>>Setup>>Chart Settings. One of the great features of Mod Settings Block is that you can hyperlink directly to the Mod Settings Block, without having to select and Admin>>Settings program, open an Admin>>Settings>>General Settings submenu, or even scroll through other options. (The 'Change Mod Options' links in Inner Mod Menus, such as the one illustrated above, do this.

In this screen clip, I've marked new and beta-feature-related options with the item numbers from the list of recent changes above and the Beta features lists below.
Textplus17-modoptionsblock-annotated.jpg

Text+ Beta Features

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
    As I noted above, this feature can be suppressed by a mod option.
  2. As I noted in "new feature" item 10 above, Text+ Charts now has a set of mod options that allow an admin to control how and whether to display dates and places in the Text+Charts. The new option marked as 'Beta2' in the mod options form above determines whether end users get to see and control the date/place formats for themselves through a pop-down form within the Text+ Chart programs:
    Textplus-dateplaceoptions2.jpg

    The form's "Save" button saves the current options in a 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.

    There is a complication in the positioning of the Date/Place form. You can see that the form is not positioned immediately below the 'Dates & Places" label. That's because the label can wind up wrapped to another line when the browser window is narrower or when certain languages are used:
    Textplus-dateplacelabel-ancestor.jpg
    I'll ask a question about this in the "Questions" section below.
  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

Questions

I'm sorry for all of the questions. I'm just burned out. :-)

  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 describes the text descendancy chart feature that I've implemented in the Text+ charts as "Locate person in chart", and I'm not crazy about my description either.
    Question 2 Any suggestions for a phrase to identify this feature in the chart legend, and in the icon title text?
  3. The separations of name/birth/death/marriage onto separate lines...
    • Question 3: Other than the question of whether the end-user should control of this feature (which I address below) do you have any qualms or suggestions about this it?
  4. The date/place options...
    • Question 4: Should the "Dates & Places" pull-down label be placed where it is in the screen clips above, or next to the Format for Printing button, where the form lines up to the pull-down label better?
    • Question 5: If a site admin turns off the end-user "Dates & Places" form, TNG admins still have the ability to edit those options. And, if a site admin has installed Inner Mod Menus, then the options are just a swipe-and-click away. Still, should the "Dates & Places" slide-down form be available only to Admins if it has been turned off for end-users?
  5. The "Ancestral lines that end in each generation" feature...
    • First - I think that I've decided to implement 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. The family names could be reported in a table similar to this one from Count Descendants:
      Count descendants-namesbygeneration.jpg
      On the other hand, the Ancestor Inner Menu is already awfully long.
    • Question 6: Should I create that separate "Count Ancestors" mod and a "Count" link in the Ancestor Inner Menu, with a table like the one above that shows the generations in which each ancestral surname appears?
    • Question 7: Let's assume that I do create the separate "Count Ancestors" mod. Should I then omit this summary of the ancestral lines from the Text+ Ancestor Chart summary?
    • Question 8: Even if I don't create the "Count Ancestors" mod, should I omit the ancestral lines data from the Text+ Ancestor Chart summary? (That would, of course, mean that it is not available at all, unless someone comes up with another place to put it.)
[Hide The Text+Charts Beta Documentation]

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 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. (I'll touch on a couple of possible removals below). 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 help to idenify the blocks of options as they open and close, since the page can jump around when its components open and close.

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

If you just want to make sure that the program takes on the native or recommended behavior, you don't have to see all of the options in their form fields. Instead, you can just get it glimpse (if you want to look at those descriptions) at what those settings, click "Apply", and be done with it. (Right now, the program doesn't give you good feedback when you click "Apply", but I can fix that easily.)

Here are the options form fields, displayed 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. 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 highlighting the search form feature controlled by groups 1, 2, 3, and 4:
Admin media search-searchfields.jpg
Focsing on group 1, you can see the five database fields that can be searched, with checkboxes to control whether each is searched, and two fields 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

Unfortunately, there's no good way to demonstrate the other sections of the mod options for without opening up an administrative login, which would expose too many mod options, so all I can do for the moment is refer to the options examples above, and ask this question:

  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?
[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 may now be ready for release. See the Admin No Frameset wiki article

Questions

  1. What does this mod need in order to be released as a production mod?

2. Admin Secondary Processes

The 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 relabeling branches 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 memssage doesn't fit into the confirm box, so I intend to use a TNG LitBox instead.

Media:admin_secondary_processes_v12.3.0.0a.zip

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.
Media:admin_settings_save_all_v12.0.0.1.zip

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 branch selection box to the end-user pull-down people search, but only for users who are logged in. [See Details].

[Hide Details]
Here's a screen clip from my one-tree test site.
Search select branch-1tree.jpg
When the user has an assigned branch, that branch is listed first.
Media:search_select_branch_v12.0.0.0.zip

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 it would not let all users select a branch to search. Should this mod work the same way that the Advanced People Search does?
  2. What 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.
Media:chart_types_help_v12.0.0.0.zip

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 very simple mod installs a utility program, primarily for mod developers, that scans selected mod .cfg files, looks at %copyfile directives, and determines whether the mods' files are properly installed. [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-results.jpg]
You can see that
  1. admin_no_frameset_v12.0.0.h.cfg installs 9 files, including the two shared Mod Settings Blocks file
  2. One of the Admin No Frameset files does not match. It presumably has been edited on one side or the other, and needs to be copied to the other side.
  3. mod_manager_check_files_v12.0.0.0.cfg installs three files, two of which do not match.
  4. mod_support_form_v12.0.0.6rr.cfg installs just one file, and that file has not been installed.

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. Its focus is on files that do not match.
Media:mod_manager_check_files_v12.0.0.0.zip

What this mod needs

  1. The ability to focus on errors. You can see from the screen clip that, despite the color-coding, errors can be lost among the files are are installed and match.
  2. A search string to help select mods. As things stand, the mods must be selected from a selection box. But at least the selection box shows only those mods that do install files.
  3. When files do not match, it would be very helpful, and it should be very easy, to list the last modification date of each file.
  4. The mod name as well as the mod filename should be displayed in the results.

Questions

  1. Whaddya think? Any suggestions?
  2. Should this mod be published once I clean up the issues listed just above and respond to suggestion?
[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 in Admin>>Setup programs. [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 scheme
      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 scheme, 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,
        • 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 state 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, I can just edit the language file in the mod subfolder, and new/modified strings 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.
    • To override an English string is a problem. All that I can really suggest is to use English-UTF8 and copy my English_cust_text.php file contents into the English-UTF8 cust_text.php file.
[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.