Difference between revisions of "Admin Branches Queue"

From TNG_Wiki
Jump to navigation Jump to search
(31 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{construction
 
|notes=This mod is in a beta testing state. I've been using it for a while, but it needs to be tested on other TNG sites,
 
 
In truth, I have close to 40 new and updated mods in beta status, and I'd appreciate whatever help that anyone can offer.
 
So it would be great if you could download the mod, test it, and let me know how it works for you.
 
 
Thanks in advance.
 
<br/>Robin Richmond 31 May 2017
 
}}
 
 
{{TNGmod
 
{{TNGmod
| mod_name        =  Branch Timestamps
+
| mod_name        =  Admin Branches Queue
|  mod_summary    = This mod installs database fields and AJAX programs that mark branch operations with timestamps in the TNG Branches table, and that enable batch operations on multiple branches.
+
|  mod_summary    = Implements a queuing mechanism that can perform batch execution of multiple branch label operations.
 
| mod_validation  =  
 
| mod_validation  =  
| download_link  =  For {{Tv1010}} [[Media:branch_timestamps_v11.0.0.0a.zip|branch_timestamps_v11.0.0.0a.zip]]  
+
| mod_last_update = 17 Nov 2020
 +
| download_link  =  [[Media:admin_branches_queue_v13.0.0.6.zip|v13.0.0.6.zip]]{{Tv130}}
 +
<div style="clear:both;">[[Media:admin_branches_queue_v12.0.0.2a.zip|v12.0.0.2a.zip]]{{Tv120}}</div>
 +
<div>See older versions in the [[#Revision_History|Revision History]]</div>
 
| download_stats  =
 
| download_stats  =
 
| mod_author      = [[User:Robinrichm|Robin Richmond]]
 
| mod_author      = [[User:Robinrichm|Robin Richmond]]
| mod_url        = [http://www.robinrichmond.com/family/ Robin Richmond's Genealogy Database]
+
| mod_url        = ''this page''
 
| mod_contact    = [http://www.robinrichmond.com/family/mod_support.php My Mod Support form]
 
| mod_contact    = [http://www.robinrichmond.com/family/mod_support.php My Mod Support form]
 
| mod_support    = [http://www.robinrichmond.com/family/mod_support.php My Mod Support form] or [http://tng.community/ TNG Community Forums]
 
| mod_support    = [http://www.robinrichmond.com/family/mod_support.php My Mod Support form] or [http://tng.community/ TNG Community Forums]
| mod_version    = v11.0.0.0a
+
| mod_version    = 13.0.0.6
 
| min_TNG_ver    = 11.0
 
| min_TNG_ver    = 11.0
| max_TNG_ver    = at least 11.1.1
+
| max_TNG_ver    = 13.0.1
|   TNG_file_list  = ajx_labels.php, admin_branches.php, admin_editbranch.php, admin_updatebranch.php, English cust_text.php. <b>Installs</b>: branch_timestamps_dbsetup.php, ajx_branch_status.php, ajx_branches.php, admin_updatebranchtimestamps.php, branch_timestamps_tester.php
+
| TNG_file_list  = ajx_labels.php, admin_branches.php, admin_editbranch.php, admin_updatebranch.php, English cust_text.php. <b>Installs</b>: rrbranchesqueue_dbsetup.php, rrbranchesqueue_status.php, rrbranchesqueue_ajx.php, rrbranchesqueue_dequeue.php, rrbranchesqueue.php, rrbranchesqueue_restore_ajx.php
| related_mods  = [[Admin Branches]] (required), [[Show Mod Names]] (optional)
+
| related_mods  = [[Admin Branches]] (required), [[Add Name to PersonID]], [[Admin Secondary Processes]], [[Inner Mod Menus]]
 
| notes    =   
 
| notes    =   
}}
+
}}== Purpose of the Mod ==
 
+
To make it easier to rebuild (relabel) multiple branches from their branch rules, and to know whether branches have been or need to be rebuilt. This mod
 
{| style="margin-right:0.5 em;" align="right"  
 
{| style="margin-right:0.5 em;" align="right"  
 
| __TOC__
 
| __TOC__
 
|}
 
|}
 
== Purpose of the Mod ==
 
This mod
 
 
* Installs database fields and AJAX programs that mark Branch operations with timestamps in the TNG Branches table, so that administrators can know when or whether a Branch has been updated or cleared.
 
* Installs database fields and AJAX programs that mark Branch operations with timestamps in the TNG Branches table, so that administrators can know when or whether a Branch has been updated or cleared.
# Implements a simple queueing method that allows site administrators to queue Branch operations (Add Labels, Clear Labels, and Delete Records that are marked with a Label). This queueing mechanism is of particular importance on large sites, where Branch operations take a long time.
+
# Implements a simple queuing mechanism that allows site administrators to queue tasks that Add (aka Rebuild) or Clear branch labels. This queuing mechanism is of particular importance on large sites, where Branch operations take a long time.
 
# Modifies the Admin>>Branches>>Search results screen to show the status of each branch.
 
# Modifies the Admin>>Branches>>Search results screen to show the status of each branch.
# Adds queueing options to the Admin>>Branches editor.
+
# Adds queuing options to the Admin>>Branches editor.
# Installs a Branch Queueing and Test Mod from when an administrator can directly run some Branch operations, and can queue Branch operations to run in the background.
+
# Installs a Branch Queuing application from which an administrator can directly run some Branch operations, and can queue Branch operations to run in the background.
 
+
#* This program is similar to the Admin>>Branches>>Search program, and is launched from a tab labeled "Queue Actions"
== Parameters ==
+
# Provides a way for branches to be rebuilt ''accurately'' after a Gedcom Import.
# $updateActionWhenRuleChanges
+
#* The issue here is that the native Gedcom Import Secondary Process to "Relabel Branches" uses the old branch index (the branchlinks table), but the Gedcom Import can change who belongs in a branch, and thus make the branch index obsolete.
This option allows you to mark the Branch as "needing to be updated" if you change the Branch rule.
+
#* Thus, this mod simplifies and optimizes the process of running complete branch label rebuilds, using the branch rules (e.g. ancestor generations, descendant generations, etc.)
  
== Files Installed ==  
+
== Mod Options ==
# branch_timestamps_dbsetup.php - Creates or deletes Branch table fields for the Branch Timestamps mod.
+
none
# ajx_branch_status.php - Checks the status of processes that have been queued to rebuild or clear branch labels.
 
# ajx_branches.php - Loops through a set of branches to call ajx_labels.php to add or clear branch labels. Significantly, it does not invoke ajx_lables.php through AJAX, but rather through the PHP function file_get_contents. As a result,
 
#* the branches are done in sequence, not in parallel, and
 
#* one run-time process will not accumulate the execution time require to process all branches in the set.
 
# admin_updatebranchtimestamps.php - Modifies branch queueing by changing values in the new queing fields in the Branches table.
 
# branch_timestamps_tester.php - Application that is accessible through the Branches inner menu
 
#* Tests the new queueing features,
 
#* Adds or Clears branches immediately. 
 
#* Has search features that I hope to implement in Admin_Branches at some point, such as the ability to focus on group of branches with a shared "dummy branch" (whose BranchID is a substring within other BranchIDs). 
 
  
== Compatibility with Other Mods ==
+
== Compatibility ==
 
This mod is compatible with [[Add Name to PersonID]], [[Tree ID Mod]], and [[TreeID-One Column]],
 
This mod is compatible with [[Add Name to PersonID]], [[Tree ID Mod]], and [[TreeID-One Column]],
and depends on [[Admin Branches]].  Is is '''not compatible with''' [[Branches Sort mod]] because [[Admin Branches]] has a direct conflict. But the goal of [[Branches Sort mod]], to sort related branches together in the Admin Branches Search results table, is only achieved if the related branches use the common BranchID at the very beginning of their BranchIDs. A Branch Testing Application that can focus on all groups of related branches in installed by [[Branch Timestamps]]
+
and depends on [[Admin Branches]].  Is is '''not compatible with''' [[Branches Sort mod]] because [[Admin Branches]] has a direct conflict. But the goal of [[Branches Sort mod]], to sort related branches together in the Admin Branches Search results table, is only achieved if the related branches use the common BranchID at the very beginning of their BranchIDs. The Queue Actions program supplied by this mod can focus on ''all'' of related branches.
  
 
== Related Mods ==
 
== Related Mods ==
# This mod '''is dependent on''' [[Admin Branches]], which also adds columns to the Admin>>Branches results table, and adds options to the Branch Editor. The two mods can be installed independently, but [[Admin Branches]] installs code that implements the $summaryonly query string parameter in ajx_labels.php, and Branch Timestamps depends on that code.
+
<ol>
# The optional [[Show Mod Names]] mod will use data saved by Branch Timestamps to to display information about the mods that affect admin_branches.php and admin_branchedit.php '''''if''''' [[Show Mod Names]] is installed.
+
<li>{{RobinBoilerplate | text=imm}}</li>
 
+
<li>{{RobinBoilerplate | text=smn}}</li>
==Requirements==
+
<li>This mod '''is dependent on''' [[Admin Branches]], which also adds columns to the Admin>>Branches results table, and adds options to the Branch Editor.</li>
* A working TNG installation.
+
<li>This mod coordinates with [[Add Name to PersonID]] and [[Admin Branches]] because they all want to make changes to the main SQL query. The three mods share a flag that allows just one of the mods to make all of the SQL changes that all three mods need.</li>
* An installed current version of the [[Mod Manager]].
+
<li>This mod coordinates with [[Admin Secondary Process]] in that it adds a tab that returns to the Secondary Processes menu if it was invoked from a Secondary Process.
* You should backup files listed in the panel on the right.
+
</ol>
 
 
==Installation==
 
# Remove and delete previous version of this mod.
 
# Backup the files updated by this mod.  They are listed in the panel at the upper right.
 
# Download the .zip file, and extract its .cfg file to the mods folder.
 
# Follow the normal automated installation for Mod Manager, as shown in the example [[Mod Manager - Installing Config Files]].
 
  
== In the event of a problem ==
+
== Installation ==
# Try using the [[Mod_Manager_-_Installing_Config_Files#Remove_Mod_Steps|Mod Manager Remove]] capability
+
{{RobinBoilerplate | text=languageandfiles}}
# Contact me through [http://www.robinrichmond.com/family/mod_support.php My Mod Support form].
+
=== Files Installed ===  
 +
# '''rrbranchesqueue_dbsetup.php''' - A script that sets up the new database fields that track queuing. It is launched from the mod description block within the Mod Manager List.
 +
# '''rrbranchesqueue.php''' - The queuing app launched from the new "Queue Actions" tab.  It lists selected branches and allows the user to enqueue jobs that rebuild (i.e. label) or clear the labels from multiple branches.
 +
# '''rrbranchesqueue_ajx.php''' - An AJAX program to queue a list of branches for processing. Invoked by rrbranchesqueue.php.
 +
# '''rrbranchesqueue_dequeue.php''' - An action script called by admin_editbranch.php to remove a job from an action queue. Invoked from admin_branchedit.php.
 +
# '''rrbranchesqueue_status.php''' - An AJAX program that checks the status of the queued branch tasks. Invoked from admin_branches.php and rrbranchesenqueue.php
 +
# '''rrbranchesqueue_restore_ajx.php''' - An AJAX program to relabel one branch by copying the branch index; similar to the secondary process that relabels all branches.
 +
{{RobinBoilerplate | text=install}}
  
 
== Visualizations ==
 
== Visualizations ==
 
+
{| border="3" cellspacing="1" cellpadding="2" class="wikitable"
{| border="1" cellspacing="1" cellpadding="2" class="wikitable"
 
 
|-
 
|-
| style="border:thin solid black;vertical-align:top;" | '''Admin>>Branches>>Search <span style="color: red">BEFORE:</span>'''<br/>
+
| '''Admin>>Branches>>Search '''<span style="color: red">Before installation of either [[Admin Branches]] or Admin Branches Queue</span><br/>
[[Image:Branches Before1.png]]<!-- ######## Bob - same screenshot as Admin Branches -->
+
The buttons at the bottom of this form generate cascading pop-up forms that I find confusing.  The [[Admin Branches]] mod changes that workflow so that more actions can be taken without popups.
 +
<div>[[Image:branch_timestamps-before.png]]</div>
 
|-  
 
|-  
| style="border:thin solid black;vertical-align:top;" | '''Admin>>Branches>>Search <span style="color: red">AFTER:</span> With [[Admin Branches]] also installed'''<br/>
+
| '''Admin>>Branches>>Search''' <span style="color: red">After Installation of [[Admin Branches]]</span>'''<br>
[[Image:after1.png]]
+
See the [[Admin Branches#Visualizations|visualizations]] in the [[Admin Branches]] wiki article for annotation.
 +
<div>[[Image:admin_branches-after1.jpg]]</div>
 +
|-
 +
| '''Admin>>Branches>>Search''' <span id='admin_branches' style="color: red"> After installation of both [[Admin Branches]] and Admin Branches Queue</span>
 +
<div>[[Image:branch_timestamps-after1bt.jpg]]</div>
 +
|-
 +
| '''Admin>>Branches>>Search''' <span style="color: red">The Inner Mod Menu</span><br>
 +
Both [[Admin Branches]] and Admin Branches Queue generate Inner Mod Menus in the Admin>>Branches search form, and in Admin>>Branches>>Edit. The two menus are consolidated in one menu as shown here.
 +
* For Admin Branches, which has mod options, the links are
 +
*# To the Wiki article (via the Wiki logo)
 +
*# To the section of the Wiki article describing the mod options, and
 +
*# Directly to the mod options themselves.
 +
* For Admin Branches Queue, which does not have branches, the links are
 +
*# To the Wiki article,
 +
*# To a section of the Wiki article that says what has changed in Admin>>Branches
 +
In Admin>>Branches>>Edit, the only difference is that the last link for Admin Branches Queue goes to a section of the Wiki article that describes the changes made to ''that'' program.
 +
<div>[[Image:admin_branches_queue-after-innermodmenu.jpg]]</div>
 +
|}
 +
<!-- ****************** Branch Edit Visualizations **************** -->
 +
{| border="3" cellspacing="1" cellpadding="2" class="wikitable"
 +
|-
 +
| '''Admin>>Branches>>Edit''' <span style="color:red"> After Installation of [[Admin Branches]]</span><br/>
 +
See the [[Admin Branches]] Wiki article for more annotation of the two forms on this page:
 +
# The upper form edits the Branch record, and
 +
# The lower form (enclosed by a fieldset with the legend "Branch Action Form") executes various actions on this branch.
 
|-
 
|-
| style="border:thin solid black;vertical-align:top;" | '''Admin>>Branches>>Edit <span style="color: red">BEFORE:</span>'''<br/>
+
| [[Image:admin_branches_queue-edit-after-admin_branches.jpg]]
[[Image:Branches Edit Existing Branch - Before.png|750px]]<!-- ########## Bob - same screenshot as Admin Branches -->
 
 
|-  
 
|-  
| style="border:thin solid black;vertical-align:top;" | '''Admin>>Branches>>Edit <span style="color: red">AFTER:</span>'With [[Admin Branches]] also installed''<br/>
+
| '''Admin>>Branches>>Edit''' <span id='admin_editbranch' style="color: brown"> After both mods have been installed.</span><br/>
[[Image:after2.png]]
+
The Branch Edit page has three HTML forms, each of which is surrounded by a fieldset.
 +
* The first form is largely intact from the native program.
 +
* The third form is from the [[Admin Branches]] mod.
 +
* Admin Branches Queue creates the "Form for Action Results and Queue Manipulation", which is outlined in orange in the screenshot. This form
 +
*# Show the results of the the most recent branch action - whether it was queued or was executed by clicking on the buttons in the "Branch Action Form" below. The middle form:
 +
*# Indicates whether an action on this branch is currently in the processing queue.
 +
*# Has a button that removes the current action from the queue.
 +
*#* This button is visible '''only''' if there is a job in the queue.
 +
|-
 +
| [[Image:admin_branches_queue-after-both.png]]
 +
|}
 +
<!-- ****************** Queue Actions Page Visualizations **************** -->
 +
{| border="3" cellspacing="1" cellpadding="2" class="wikitable"
 +
| '''Admin>>Branches>>Queue Actions Page''' <span style="color:red"> After installation of both mods</span><br/>
 +
This page is similar to the Branch Search page in that it lists all of the branches that match a search, and lets you select or clear checkboxes for each branch. But unlike the Branch Search Page
 +
* '''The Search form'''
 +
*# The tree selection box shows the last Gedcom Import date for each tree.  That date is important to both the program and the user in deciding whether a branch ''needs'' to be rebuilt.
 +
*# The search can focus on the branch name ''or'' description, not both.
 +
*# Three checkboxes affect what is in the result table.
 +
*## '''Count labels in each branch''' - As with the branch record counts that [[Admin Branches]] added to the Admin>>Branches>>Search results, by default, the records are not counted, because counting can take too long on a very large database.  Instead, a simply Y or N is displayed by default.
 +
*## '''Show branch-restricted users''' - This is represented by the very last column of the results.
 +
*##* This screen shot was generate from a test database, so most of the branches have no users. In another environment, displaying this column might make sense only if the search string focused on one or two branches.
 +
*##* Still, it is important to realize that not all branches will necessarily have users. Some branches, such as "Contacts", "Ancestors", and perhaps "Hazlet" (which contains ancestors only) are defined simply to identify sets of people in the tree, and are not intended for users.
 +
*## Focus on dummy branches - A subsequent visualization will illustrate the effect of this checkbox
 +
* '''The results table'''
 +
*# In the checkbox column, the "Contacts" and "hk" columns do not have checkboxes because they do not have branch rules (i.e. ancestor or descendant generations values)
 +
*# The branch 'hk' is a true 'dummy branch', as it is a substring of 'hk-hutch' and 'hk-kuyk' (two closely related families that intermarried). As with most dummy branches
 +
*#* The Actual record count is the union of it constituent branches, which overlap, hence the record counts are not the sum of the constituent branch record counts.
 +
*#* There are no records in the index, thus the counts are highlighted in red. But, in this case, the difference between the records counts and the index counts are normal, so the highlighting is essentially extraneous.
 +
*#* The branch has never had an action performed on it, since its whole purpose is to reflect the actions of its constituent branches.
 +
*# In the branch "Durbahn", the last action was "clear", hence the record and index counts are zero. The counts in the People/Families column are non-zero; they reflect the number of records that were cleared.
 +
*# All actions other than "add" are highlighted in brown text.
 +
*# The "Clear" action could have been launched from the Branch Edit page, or from this page. There is no way to know.
 +
*#* The same is true for all "add" actions.
 +
*# The Queued Actions columns is blank because there are no actions in the queue at the moment. See a visualization below.
 +
* '''Actions and Results of Actions'''
 +
*# The "Immediate Action" buttons use Ajax to enqueue add or clear actions for checked buttons.
 +
*#* The results of queued actions are shown in the black box near the bottom of the screen, but are not reflected in the results table until the page is reloaded. See a visualization below.
 +
*# The Submit buttons were mostly used to test the queuing mechanism, but if an action goes awry, it may be appropriate to use them.
 +
*# This page does not have a way to remove a queued action, though it should. To remove an action from the queue, you must go to the Branch Edit page for the branch whose action you want to remove from the queue.
 +
*# A visualization below shows how the text in the black box is replaced with the results of queued actions.
 +
*# Reflecting the use of this page as a testing ground for the queuing mechanism, there are several notes at the bottom of the page.  These notes ''could'' and may be in this Wiki article, as well.
 +
|-
 +
| [[Image:admin_branches_queue-qactions1.jpg]]
 
|-  
 
|-  
| style="border:thin solid black;vertical-align:top;" | '''Admin>>Branches>>Timestamp Test App <span style="color: red">AFTER:</span>''' The Branch Testing Application <br/>
+
| '''Admin>>Branches>>Queue Actions Page''' <span style="color:red"> Reflecting some queued actions</span><br/>
[[Image:after3.png]]
+
This screen clip was generated by refreshing the page quickly after actions were queued by the "Queue to add labels" button. Note that the "hk-hutch" branch is being processed, and the "hk-huyk" and "Marwil" branches are queued up to be processed next.
 +
|-
 +
| [[Image:admin_branches_queue-qactions2.jpg]]
 
|-  
 
|-  
| style="border:thin solid black;vertical-align:top;" | '''Admin>>Branches>>Timestamp Test App <span style="color: red">AFTER:</span>''' The Branch Testing Application, focusing on groups of related mods<br/>
+
| '''Admin>>Branches>>Queue Actions Page''' <span style="color:red"> After queued actions have completed.</span>
[[Image:after4.png]]
+
* The results of a set of queued actions appears in the black box below the results table.
 +
* It is important to realize that if you were to refresh the page to reveal the queued actions, as reflected by the screen clip just above, this result message will not appear. To see the results of queued actions in the black box, you must wait until all of the queued tasks have been completed. But you are certainly not required to wait.  You can move on to other tasks.
 +
* Also importantly, since the Immediate Action buttons show results in the black box, but do not refresh the page, the the results table still reflects the search results from ''before'' the actions were queued, and shows the checked boxes for the branches that were queued.
 +
|-
 +
| [[Image:admin_branches_queue-qactions3.jpg]]
 +
|-
 +
| '''Admin>>Branches>>Queue Actions Page''' <span style="color:red"> Showing a 'dummy branches' search</span>
 +
* (This screen clip comes from a different database than the previous ones.)
 +
* The results show each (in this case, two) dummy branch and their constituent branches]
 +
|-
 +
| [[Image:admin_branches_queue-qactions4.jpg]]
 
|}
 
|}
  
== Mod Change History ==
+
== Language Strings ==
 +
{{RobinBoilerplate | text=language0}}
 +
 
 +
== Revision History ==
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
|-
+
! Mod Version !! TNG Version !! Date !! Note
! Mod Version
+
|- valign="top"
! TNG Versions
+
| [[Media:admin_branches_queue_v13.0.0.6.zip|13.0.0.6]]
! Date
+
| 13.0-13.0.1
! Note
+
| 20 Nov 2020
|-  
+
|
| 11.0.0.0a
+
# Coordinates with the new Admin Secondary Processes Mod by adding a "Return to Secondary Processes" tab if it was invoked by a Secondary Process button.
| 11.1.1
+
# The Reset button was working like a normal Reset button, not like other TNG Reset buttons.
 +
# Tree column wasn't always appearing when it should
 +
# Improved handling of queries when there are no branches in the database and when the specified tree has no branches
 +
# See the .cfg file's Revision History for other changes
 +
 
 +
|- valign="top"
 +
| [[Media:admin_branches_queue_v13.0.0.5.zip|13.0.0.5]]
 +
| 13.0
 +
| 2 Aug 2020
 +
|
 +
* Upgraded to TNGv13, with just a few straightforward code changes
 +
* Set the version number to 5 to coordinate with Admin Branches, on which this mod depends.
 +
* To coordinate among Add Name to PersonID, Admin Branches and Admin Branches Queue over the main SQL query in admin_branches.php, all three mods use a shared flag to determine which one will output the entire query with all tables and fields that they all need.
 +
 
 +
|- valign="top"
 +
| [[Media:admin_branches_queue_v12.0.0.2a.zip|12.0.0.2a]]
 +
| 12.0+
 +
| 21 Mar 2020
 +
|
 +
# In the Queue Actions program:
 +
## Moved the buttons that check select all or clear all checkboxes to the column heading.
 +
## Added a checkbox that tells the "Queue to Clear Labels" action to clear "all" of the branch's labels by scanning the entire People and Families tables. When the box is not checked, the Clear operation uses the branch rule.
 +
## The earch results now use the "Count Branch Labels" mod option (defined by the Admin Branches mod) to determine whether to (initially) display label counts vs the flag that indicates simply that "there are labels"
 +
# Fixed a bug in admin_updatebranch.php; Would crash when a branch rule property was changed
 +
# The variable $tableformat was used without being defined and was used without the dollar sign
 +
# Put a nowrap span around 'T-[days}" in date fields and omitted time of day if the date is more than 7 days ago.
 +
 
 +
|- valign="top"
 +
| [[Media:admin_branches_queue_v12.0.0.2.zip|12.0.0.2]]
 +
| 12.0+
 +
| 3 Jan 2020
 +
|
 +
* Renamed to Admin Branches Queue
 +
* Renamed the mod & files installed by this mod to have the common prefix rrbranchesqueue
 +
* Removed most of the testing activity from the "Timestamps Test App", and changed its name.
 +
* In what is now the "Queue Actions" page:
 +
** Changed several of the notes and labels. (Many of them are not translated)
 +
** Added the ability to select or unselect all branches
 +
** "All branches" excludes branches without a labeling rule (i.e. no ancestor or descendant count)
 +
** Branches without a labeling rule and 'with' records in the branch index (the branchlinks table) have a "Restore Branch" button that copies the index to People and Families records, like the Relabel Branches secondary process.
 +
* Added an Ajax program to restore one branch from its index.
 +
 
 +
|- valign="top"
 +
| [[Media:branch_timestamps_v12.0.0.1.zip|Branch Timestamps v12.0.0.1]]
 +
| 12.0+
 +
| 15 May 2018
 +
| No functional changes; made compatible with TNGv12.
 +
|- <span style='vertical-align:top;'><!-- ------------------------------------------------ -->
 +
| [[Media:branch_timestamps_v11.0.0.1.zip|Branch Timestamps v11.0.0.1]]
 +
| 11.0-11.1.2
 +
| 5 Mar 2018
 +
| No functional changes - Removed the second line from the cust_text.php target location search string, and replaced a message with a translation string.
 +
|- <span style='vertical-align:top;'><!-- ------------------------------------------------ -->
 +
| [[Media:branch_timestamps_v11.0.0.0a.zip|Branch Timestamps v11.0.0.0a]]
 +
| 11.0-11.1.2
 
| 31 May 2017
 
| 31 May 2017
 
| New mod. Beta status
 
| New mod. Beta status
Line 119: Line 237:
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
 
|-
 
|-
! URL
+
! URL !! User !! Note !! Mod Version !! TNG Version !! User language
! User
 
! Note
 
! Mod Version
 
! TNG Version
 
! User language
 
 
|-
 
|-
 
| [http://www.robinrichmond.com/family/ Robin Richmond's Genealogy Database]
 
| [http://www.robinrichmond.com/family/ Robin Richmond's Genealogy Database]
 
| [[User:Robinrichm|Robin Richmond]]
 
| [[User:Robinrichm|Robin Richmond]]
 
| Mod developer
 
| Mod developer
| 11.0.0.0a
+
| 13.0.0.6
| 11.1.1
+
| 13.0.1
 
| English
 
| English
 
|-
 
|-
| [http://racine-ad.fr/TNG/index.php]
+
| [http://racine-ad.fr/TNG/index.php racine d'Alsace]
| [J-L Valory]
+
| J-Louis Valory
| ...
+
| Pubic/Privat - Template 1
 
| 11.0.0.0a
 
| 11.0.0.0a
 
| 11.1.1
 
| 11.1.1
 
| French  
 
| French  
 
|}
 
|}
 
+
[[Category:Mods for TNG v13]]
 +
[[Category:Mods for TNG v12]]
 
[[Category:Mods for TNG v11]]
 
[[Category:Mods for TNG v11]]
 
[[Category:ajx_labels.php mods]]
 
[[Category:ajx_labels.php mods]]

Revision as of 00:44, 21 December 2020

Admin Branches Queue
Summary Implements a queuing mechanism that can perform batch execution of multiple branch label operations.
Validation
Mod Updated 17 Nov 2020
Download link v13.0.0.6.zip
TNG 13.0
v12.0.0.2a.zip
TNG 12.0
See older versions in the Revision History
Download stats
Author(s) Robin Richmond
Homepage this page
Mod Support My Mod Support form or TNG Community Forums
Contact Developer My Mod Support form
Latest Mod 13.0.0.6
Min TNG V 11.0
Max TNG V 13.0.1
Files modified
ajx_labels.php, admin_branches.php, admin_editbranch.php, admin_updatebranch.php, English cust_text.php. Installs: rrbranchesqueue_dbsetup.php, rrbranchesqueue_status.php, rrbranchesqueue_ajx.php, rrbranchesqueue_dequeue.php, rrbranchesqueue.php, rrbranchesqueue_restore_ajx.php
Related Mods
Notes

Purpose of the Mod

To make it easier to rebuild (relabel) multiple branches from their branch rules, and to know whether branches have been or need to be rebuilt. This mod

  • Installs database fields and AJAX programs that mark Branch operations with timestamps in the TNG Branches table, so that administrators can know when or whether a Branch has been updated or cleared.
  1. Implements a simple queuing mechanism that allows site administrators to queue tasks that Add (aka Rebuild) or Clear branch labels. This queuing mechanism is of particular importance on large sites, where Branch operations take a long time.
  2. Modifies the Admin>>Branches>>Search results screen to show the status of each branch.
  3. Adds queuing options to the Admin>>Branches editor.
  4. Installs a Branch Queuing application from which an administrator can directly run some Branch operations, and can queue Branch operations to run in the background.
    • This program is similar to the Admin>>Branches>>Search program, and is launched from a tab labeled "Queue Actions"
  5. Provides a way for branches to be rebuilt accurately after a Gedcom Import.
    • The issue here is that the native Gedcom Import Secondary Process to "Relabel Branches" uses the old branch index (the branchlinks table), but the Gedcom Import can change who belongs in a branch, and thus make the branch index obsolete.
    • Thus, this mod simplifies and optimizes the process of running complete branch label rebuilds, using the branch rules (e.g. ancestor generations, descendant generations, etc.)

Mod Options

none

Compatibility

This mod is compatible with Add Name to PersonID, Tree ID Mod, and TreeID-One Column, and depends on Admin Branches. Is is not compatible with Branches Sort mod because Admin Branches has a direct conflict. But the goal of Branches Sort mod, to sort related branches together in the Admin Branches Search results table, is only achieved if the related branches use the common BranchID at the very beginning of their BranchIDs. The Queue Actions program supplied by this mod can focus on all of related branches.

Related Mods

  1. Inner Mod Menus used to be implemented by a standalone mod named Inner Mod Menus, but they are now a feature of the Mod Settings Blocks mod. "Inner Mod Menus" are drop-down menus in the standard TNG "InnerMenu" and are visible only to TNG site administrators. They provide information about mods that affect a given program and links to the mod's settings (in Mod Settings Blocks).
  2. The old Show Mod Names mod has been retired. Its functionality (now called "Mods Used" is now implemented by the Mod Settings Blocks mod.
  3. This mod is dependent on Admin Branches, which also adds columns to the Admin>>Branches results table, and adds options to the Branch Editor.
  4. This mod coordinates with Add Name to PersonID and Admin Branches because they all want to make changes to the main SQL query. The three mods share a flag that allows just one of the mods to make all of the SQL changes that all three mods need.
  5. This mod coordinates with Admin Secondary Process in that it adds a tab that returns to the Secondary Processes menu if it was invoked from a Secondary Process.

Installation

This mod does not use standard cust_text.php files for language strings. Instead, it stores languages strings in the mod's subfolder, and pages modified by this mod load language strings directly from files in the mod's languages/ subfolder. Read more about this technique and its procedure for handling site-specific language string overrides.

Files Installed

  1. rrbranchesqueue_dbsetup.php - A script that sets up the new database fields that track queuing. It is launched from the mod description block within the Mod Manager List.
  2. rrbranchesqueue.php - The queuing app launched from the new "Queue Actions" tab. It lists selected branches and allows the user to enqueue jobs that rebuild (i.e. label) or clear the labels from multiple branches.
  3. rrbranchesqueue_ajx.php - An AJAX program to queue a list of branches for processing. Invoked by rrbranchesqueue.php.
  4. rrbranchesqueue_dequeue.php - An action script called by admin_editbranch.php to remove a job from an action queue. Invoked from admin_branchedit.php.
  5. rrbranchesqueue_status.php - An AJAX program that checks the status of the queued branch tasks. Invoked from admin_branches.php and rrbranchesenqueue.php
  6. rrbranchesqueue_restore_ajx.php - An AJAX program to relabel one branch by copying the branch index; similar to the secondary process that relabels all branches.

[Show Standard Installation Process]

Requirements

  • A working TNG installation.
  • An installed current version of the Mod Manager.
  • You should backup files listed in the panel on the right.

Procedure

  1. Remove and delete previous version of this mod.
  2. Backup the files updated by this mod. They are listed in the panel at the upper right.
  3. Download the .zip file, Extract its .cfg file to the mods folder.
  4. Follow the normal automated installation for Mod Manager, as shown in the example Mod Manager - Installing Config Files.

Problems?

  1. Try using the Mod Manager Remove capability
  2. Contact me through My Mod Support form.
[Hide Details]

Visualizations

Admin>>Branches>>Search Before installation of either Admin Branches or Admin Branches Queue

The buttons at the bottom of this form generate cascading pop-up forms that I find confusing. The Admin Branches mod changes that workflow so that more actions can be taken without popups.

Branch timestamps-before.png
Admin>>Branches>>Search After Installation of Admin Branches

See the visualizations in the Admin Branches wiki article for annotation.

Admin branches-after1.jpg
Admin>>Branches>>Search After installation of both Admin Branches and Admin Branches Queue
Branch timestamps-after1bt.jpg
Admin>>Branches>>Search The Inner Mod Menu

Both Admin Branches and Admin Branches Queue generate Inner Mod Menus in the Admin>>Branches search form, and in Admin>>Branches>>Edit. The two menus are consolidated in one menu as shown here.

  • For Admin Branches, which has mod options, the links are
    1. To the Wiki article (via the Wiki logo)
    2. To the section of the Wiki article describing the mod options, and
    3. Directly to the mod options themselves.
  • For Admin Branches Queue, which does not have branches, the links are
    1. To the Wiki article,
    2. To a section of the Wiki article that says what has changed in Admin>>Branches

In Admin>>Branches>>Edit, the only difference is that the last link for Admin Branches Queue goes to a section of the Wiki article that describes the changes made to that program.

Admin branches queue-after-innermodmenu.jpg
Admin>>Branches>>Edit After Installation of Admin Branches

See the Admin Branches Wiki article for more annotation of the two forms on this page:

  1. The upper form edits the Branch record, and
  2. The lower form (enclosed by a fieldset with the legend "Branch Action Form") executes various actions on this branch.
Admin branches queue-edit-after-admin branches.jpg
Admin>>Branches>>Edit After both mods have been installed.

The Branch Edit page has three HTML forms, each of which is surrounded by a fieldset.

  • The first form is largely intact from the native program.
  • The third form is from the Admin Branches mod.
  • Admin Branches Queue creates the "Form for Action Results and Queue Manipulation", which is outlined in orange in the screenshot. This form
    1. Show the results of the the most recent branch action - whether it was queued or was executed by clicking on the buttons in the "Branch Action Form" below. The middle form:
    2. Indicates whether an action on this branch is currently in the processing queue.
    3. Has a button that removes the current action from the queue.
      • This button is visible only if there is a job in the queue.
Admin branches queue-after-both.png
Admin>>Branches>>Queue Actions Page After installation of both mods

This page is similar to the Branch Search page in that it lists all of the branches that match a search, and lets you select or clear checkboxes for each branch. But unlike the Branch Search Page

  • The Search form
    1. The tree selection box shows the last Gedcom Import date for each tree. That date is important to both the program and the user in deciding whether a branch needs to be rebuilt.
    2. The search can focus on the branch name or description, not both.
    3. Three checkboxes affect what is in the result table.
      1. Count labels in each branch - As with the branch record counts that Admin Branches added to the Admin>>Branches>>Search results, by default, the records are not counted, because counting can take too long on a very large database. Instead, a simply Y or N is displayed by default.
      2. Show branch-restricted users - This is represented by the very last column of the results.
        • This screen shot was generate from a test database, so most of the branches have no users. In another environment, displaying this column might make sense only if the search string focused on one or two branches.
        • Still, it is important to realize that not all branches will necessarily have users. Some branches, such as "Contacts", "Ancestors", and perhaps "Hazlet" (which contains ancestors only) are defined simply to identify sets of people in the tree, and are not intended for users.
      3. Focus on dummy branches - A subsequent visualization will illustrate the effect of this checkbox
  • The results table
    1. In the checkbox column, the "Contacts" and "hk" columns do not have checkboxes because they do not have branch rules (i.e. ancestor or descendant generations values)
    2. The branch 'hk' is a true 'dummy branch', as it is a substring of 'hk-hutch' and 'hk-kuyk' (two closely related families that intermarried). As with most dummy branches
      • The Actual record count is the union of it constituent branches, which overlap, hence the record counts are not the sum of the constituent branch record counts.
      • There are no records in the index, thus the counts are highlighted in red. But, in this case, the difference between the records counts and the index counts are normal, so the highlighting is essentially extraneous.
      • The branch has never had an action performed on it, since its whole purpose is to reflect the actions of its constituent branches.
    3. In the branch "Durbahn", the last action was "clear", hence the record and index counts are zero. The counts in the People/Families column are non-zero; they reflect the number of records that were cleared.
    4. All actions other than "add" are highlighted in brown text.
    5. The "Clear" action could have been launched from the Branch Edit page, or from this page. There is no way to know.
      • The same is true for all "add" actions.
    6. The Queued Actions columns is blank because there are no actions in the queue at the moment. See a visualization below.
  • Actions and Results of Actions
    1. The "Immediate Action" buttons use Ajax to enqueue add or clear actions for checked buttons.
      • The results of queued actions are shown in the black box near the bottom of the screen, but are not reflected in the results table until the page is reloaded. See a visualization below.
    2. The Submit buttons were mostly used to test the queuing mechanism, but if an action goes awry, it may be appropriate to use them.
    3. This page does not have a way to remove a queued action, though it should. To remove an action from the queue, you must go to the Branch Edit page for the branch whose action you want to remove from the queue.
    4. A visualization below shows how the text in the black box is replaced with the results of queued actions.
    5. Reflecting the use of this page as a testing ground for the queuing mechanism, there are several notes at the bottom of the page. These notes could and may be in this Wiki article, as well.
Admin branches queue-qactions1.jpg
Admin>>Branches>>Queue Actions Page Reflecting some queued actions

This screen clip was generated by refreshing the page quickly after actions were queued by the "Queue to add labels" button. Note that the "hk-hutch" branch is being processed, and the "hk-huyk" and "Marwil" branches are queued up to be processed next.

Admin branches queue-qactions2.jpg
Admin>>Branches>>Queue Actions Page After queued actions have completed.
  • The results of a set of queued actions appears in the black box below the results table.
  • It is important to realize that if you were to refresh the page to reveal the queued actions, as reflected by the screen clip just above, this result message will not appear. To see the results of queued actions in the black box, you must wait until all of the queued tasks have been completed. But you are certainly not required to wait. You can move on to other tasks.
  • Also importantly, since the Immediate Action buttons show results in the black box, but do not refresh the page, the the results table still reflects the search results from before the actions were queued, and shows the checked boxes for the branches that were queued.
Admin branches queue-qactions3.jpg
Admin>>Branches>>Queue Actions Page Showing a 'dummy branches' search
  • (This screen clip comes from a different database than the previous ones.)
  • The results show each (in this case, two) dummy branch and their constituent branches]
Admin branches queue-qactions4.jpg

Language Strings

This mod includes a typical mod subfolder, with the same base name as the mod's .cfg file. The subfolder is atypical in that no files in it are installed to working TNG folders. However, it does contain critical files that contain the mod's language strings, which the mod does not add to standard cust_text.php files. Instead, the PHP code modified by this mod loads the language strings from files in the mod's languages/ subfolder. Read more about this technique.

Revision History

Mod Version TNG Version Date Note
13.0.0.6 13.0-13.0.1 20 Nov 2020
  1. Coordinates with the new Admin Secondary Processes Mod by adding a "Return to Secondary Processes" tab if it was invoked by a Secondary Process button.
  2. The Reset button was working like a normal Reset button, not like other TNG Reset buttons.
  3. Tree column wasn't always appearing when it should
  4. Improved handling of queries when there are no branches in the database and when the specified tree has no branches
  5. See the .cfg file's Revision History for other changes
13.0.0.5 13.0 2 Aug 2020
  • Upgraded to TNGv13, with just a few straightforward code changes
  • Set the version number to 5 to coordinate with Admin Branches, on which this mod depends.
  • To coordinate among Add Name to PersonID, Admin Branches and Admin Branches Queue over the main SQL query in admin_branches.php, all three mods use a shared flag to determine which one will output the entire query with all tables and fields that they all need.
12.0.0.2a 12.0+ 21 Mar 2020
  1. In the Queue Actions program:
    1. Moved the buttons that check select all or clear all checkboxes to the column heading.
    2. Added a checkbox that tells the "Queue to Clear Labels" action to clear "all" of the branch's labels by scanning the entire People and Families tables. When the box is not checked, the Clear operation uses the branch rule.
    3. The earch results now use the "Count Branch Labels" mod option (defined by the Admin Branches mod) to determine whether to (initially) display label counts vs the flag that indicates simply that "there are labels"
  2. Fixed a bug in admin_updatebranch.php; Would crash when a branch rule property was changed
  3. The variable $tableformat was used without being defined and was used without the dollar sign
  4. Put a nowrap span around 'T-[days}" in date fields and omitted time of day if the date is more than 7 days ago.
12.0.0.2 12.0+ 3 Jan 2020
  • Renamed to Admin Branches Queue
  • Renamed the mod & files installed by this mod to have the common prefix rrbranchesqueue
  • Removed most of the testing activity from the "Timestamps Test App", and changed its name.
  • In what is now the "Queue Actions" page:
    • Changed several of the notes and labels. (Many of them are not translated)
    • Added the ability to select or unselect all branches
    • "All branches" excludes branches without a labeling rule (i.e. no ancestor or descendant count)
    • Branches without a labeling rule and 'with' records in the branch index (the branchlinks table) have a "Restore Branch" button that copies the index to People and Families records, like the Relabel Branches secondary process.
  • Added an Ajax program to restore one branch from its index.
Branch Timestamps v12.0.0.1 12.0+ 15 May 2018 No functional changes; made compatible with TNGv12.
Branch Timestamps v11.0.0.1 11.0-11.1.2 5 Mar 2018 No functional changes - Removed the second line from the cust_text.php target location search string, and replaced a message with a translation string.
Branch Timestamps v11.0.0.0a 11.0-11.1.2 31 May 2017 New mod. Beta status

Sites using this mod

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

URL User Note Mod Version TNG Version User language
Robin Richmond's Genealogy Database Robin Richmond Mod developer 13.0.0.6 13.0.1 English
racine d'Alsace J-Louis Valory Pubic/Privat - Template 1 11.0.0.0a 11.1.1 French