Difference between revisions of "Field Buttons"

From TNG_Wiki
Jump to navigation Jump to search
(New mod)
 
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{TNGmod
 
{{TNGmod
 
| mod_name        = Field Buttons
 
| mod_name        = Field Buttons
|  mod_summary    = This strictly optional utility mod installs a Javascript library that supports Field Buttons, which must be defined by other Mods. It also defines a new TNG system parameter. By itself, it has no affect on TNG programs other than those that implement the Admin >> Setup >> General Settings form.
+
|  mod_summary    = This strictly optional utility mod installs a Javascript library that supports  
 +
"Field Buttons" that are placed in HTML forms by other mods.
 
| mod_validation  =  
 
| mod_validation  =  
| download_link  =  [[Media:admin_media_predefined_search_v10.1.0.1.zip|10.1.0.1]]{{Tv110}}{{Tv1010}}
+
| mod_last_update = 2 Oct 2019
 +
| download_link  =  <div>[[Media:field_buttons_v12.0.0.3.zip|v12.0.0.3]]{{Tv120}}</div>
 
| download_stats  =
 
| download_stats  =
 
| mod_author      = [[User:Robinrichm|Robin Richmond]]
 
| mod_author      = [[User:Robinrichm|Robin Richmond]]
Line 9: Line 11:
 
| 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://robinr.org/family/mod_support.php My Mod Support form] or [http://tng.community/ TNG Community Forums]
 
| mod_support    = [http://robinr.org/family/mod_support.php My Mod Support form] or [http://tng.community/ TNG Community Forums]
| mod_version    = 10.1.0.2
+
| mod_version    = v12.0.0.3
 
| min_TNG_ver    = 10.1
 
| min_TNG_ver    = 10.1
| max_TNG_ver    = at least 11.1.2
+
| max_TNG_ver    = 12.2
|  TNG_file_list  = Modifies admin_genconfig.php, admin_updateconfig.php, English cust_text.php;<br/>Installs js/fieldbuttons.js  
+
|  TNG_file_list  = Modifies admin_genconfig.php, admin_updateconfig.php, genstyle.css, English cust_text.php;<br/>Installs js/fieldbuttonsmod.js; Installs shared files: rrsetup_modoptions1_cssjs.php, img/rrmodadmin_wikilogo.png
| related_mods  = [[Admin_Branches]], [[Admin Cemeteries]], [[Admin Places Search]], [[Admin Reports Search]] [[Cemetery Edit]], [[Mod Manager Compare]], and possibly others.
+
 +
| related_mods  = [[Admin_Branches]], [[Admin Cemeteries Search]], [[Admin Places Search]], [[Admin Reports Search]] [[Cemetery Edit]], [[Mod Manager Compare]], and possibly others.
 
| notes    =  This is a utility mod that ''supports'' other mods, but is not ''required'' by them.  
 
| notes    =  This is a utility mod that ''supports'' other mods, but is not ''required'' by them.  
 
}}
 
}}
 
== Purpose of the Mod ==
 
== Purpose of the Mod ==
To support the use of Field Buttons by other mods, by installing  
+
To support the use of "Field Buttons" by other mods.  Field buttons are one-character buttons that are attached to HTML form fields ''by other mods'' and that do simple editing tasks like clearing a field or restoring its initial value.  The Field Buttons mod does not define field buttons in forms; it just enables field  buttons by installing
 
* A Javascript library that is used by various TNG programs ''only if this mod has been installed'', and
 
* A Javascript library that is used by various TNG programs ''only if this mod has been installed'', and
* Administrative setup form fields that implement a new TNG system variable, '''$tngconfig['rrfieldbuttonflags']]''', which allows Field Buttons types to be disabled.
+
* A mod option that control whether each type of field button is active.
 
{| style="margin-right:0.5 em;" align="right"  
 
{| style="margin-right:0.5 em;" align="right"  
 
| __TOC__
 
| __TOC__
 
|}
 
|}
  
This mod is needed only if a TNG site administrator,
+
This mod is needed only if a TNG site administrator
* Installs at least one mod that defines Field Buttons in a form that is changed by that mod, and
+
* Installs at least one mod that places field buttons in an HTML form, and
* Wants to see Field Buttons in forms.
+
* Wants to see field buttons.
That is, if this mod has not been installed, Field Buttons that have been defined by various other mods will simply not appear. Thus, mods that install Field Buttons are not strictly dependent on the Field Buttons mod.
+
That is, if this mod has not been installed, no errors will occur; Field Buttons that have been defined by various other mods will simply not appear.
 +
 
 +
The buttons are configurable in that
 +
* The one-character labels for the field buttons are defined in cust_text.php, and can be changed for different languages.
 +
* Any of the four types of field buttons can be disabled through the mod's option at '''Admin >> Setup >> General&nbsp;Settings''', in the new subform titled '''[[User:Robinrichm#The_Inner_Mod_Menu|Robin's&nbsp;Mods]]'''.
  
 
==Field Buttons==
 
==Field Buttons==
Field Buttons are hyperlinks formatted as buttons, that, with a single click, assign a particular value to an "attached" form field. There are four types of field buttons:  
+
Field Buttons are hyperlinks formatted as buttons, that act as shortcuts to common editing tasks. With a single click on a field button, a particular value to will be assigned to the "attached" form field. There are four types of field buttons:  
 
*  X - Clear the field
 
*  X - Clear the field
 
*  R - Reset/Reload the initial value; the value that was in place when the form was loaded.
 
*  R - Reset/Reload the initial value; the value that was in place when the form was loaded.
*  D - Default - Set the value to a default that was defined elsewhere, such as by a TNG system parameter or Mod Manager option.
+
*  D - Default; Set the value to a default that was defined elsewhere, such as by a TNG system parameter or Mod Manager option.
*  A - Set an 'All items' value. (At this writing, A buttons have been used only with "Results Per Page" fields.)
+
*  A - Set an 'All items' value. (At this writing, A buttons have been used only with "Results Per Page" fields on search forms)
 
Note that it would be very rare for all four buttons to be attached to one form field. Only the applicable buttons should be attached to any given form field.
 
Note that it would be very rare for all four buttons to be attached to one form field. Only the applicable buttons should be attached to any given form field.
  
Line 40: Line 47:
  
 
Buttons are "attached" to a form field in that
 
Buttons are "attached" to a form field in that
* They follow it without intervening spaces, and the form field and its Field Buttons are wrapped by a <span> tag that doesn't allow line breaks, and
+
* They follow it without intervening spaces, and the form field and its field buttons are wrapped by a <span> tag that doesn't allow line breaks, and
 
* The buttons' field names are based on the fieldname of the field that they are attached to. The buttons' field names are essentially what causes them to modify their form field.
 
* The buttons' field names are based on the fieldname of the field that they are attached to. The buttons' field names are essentially what causes them to modify their form field.
  
== Visualizations (1) ==
+
== Visualizations ==
This screen clip illustrates 5 field buttons on 2 fields in the Admin>>Reports program that has been modified by the [[Admin_Reports_List]] mod.
+
This screen clip illustrates 5 field buttons on 2 fields in the Admin>>Reports program that has been modified by the [[Admin_Reports_Search]] mod.
# The search field has X and R buttons. There is no meaning in the search field to a default value (remember, the ''initial value'' is covered by the R button) or an "all items" value (which would just be an empty search field, and the X button serves the purpose of clearing the field.)is perhaps an empty field).
+
# The search field has X and R buttons. There is no meaning in the search field to a default value (remember, the ''initial value'' is covered by the R button) or an "all items" value (which would just be an empty search field).
# The 'Results per page" has R, D, and A buttons.
+
# The 'Results per page" field has R, D, and A buttons.
 +
#* You never want an empty 'Result per page' field, so there is no X Button.
 
#* The R button restores the initial value - the value that was present when the form was loaded.
 
#* The R button restores the initial value - the value that was present when the form was loaded.
 
#* The D button sets a default value, which, in this case, is the TNG system variable $maxsearchresults.
 
#* The D button sets a default value, which, in this case, is the TNG system variable $maxsearchresults.
#* And the A button sets a value that represents 'All Items'. That value is the word 'all' (or its translation).<br>
+
#* The A button sets a value that represents 'All Items'. That value is the word 'all' (or its translation).<br>
 
[[Image:fieldbuttons-fig1.jpg]]
 
[[Image:fieldbuttons-fig1.jpg]]
  
Line 59: Line 67:
 
When a button is not needed, it is shaded out, but still physically present on the screen.  
 
When a button is not needed, it is shaded out, but still physically present on the screen.  
  
We can tell just by looking a the screen clip above that is does not represent the initial state of a form, because we can see the R buttons.  R buttons are always shaded out when the form is first loaded, because, by definition, the form field values when the form is loaded ''are'' the initial values. Here's what the same form might look like when first loaded, if the search value is empty, and the Results per page value is the site default value (in this case, 30).<br>
+
The R buttons in the screen clip above tell us that it does not represent the initial state of a form, because we can see the R buttons.  R buttons are always shaded out when the form is first loaded, because, by definition, the form field values when the form is loaded ''are'' the initial values. Here's what the same form might look like when first loaded, if the search value is empty, and the Results per page value is the site default value (in this case, 30).<div>[[Image:fieldbuttons-fig2.jpg]]</div>
[[Image:fieldbuttons-fig2.jpg]]
 
 
The search field's R and X buttons are both shaded out, but still present (and barely visible).
 
The search field's R and X buttons are both shaded out, but still present (and barely visible).
 
The 'Results per page' field's R and D buttons are also shaded out, and only its A button is visible.
 
The 'Results per page' field's R and D buttons are also shaded out, and only its A button is visible.
  
If the user enters the search string "children", ''and'' click on the A button, we'll see this:<br>
+
If the user enters the search string "children", ''and'' clicks on the A button, we'll see this:
[[Image:fieldbuttons-fig3.jpg]]
+
<div>[[Image:fieldbuttons-fig3.jpg]]</div>
 
where the search field's X button is visible because the search field has a non-empty value, both R buttons are visible because both fields have changed, and the 'Results per page' field's D button is visible because the field's value is not the default of 30. Now, only the A button is shaded out.
 
where the search field's X button is visible because the search field has a non-empty value, both R buttons are visible because both fields have changed, and the 'Results per page' field's D button is visible because the field's value is not the default of 30. Now, only the A button is shaded out.
  
If the X button is clicked, it will disappear, as will the value in the attached field:<br>
+
If the X button is clicked, it will disappear, as will the value in the attached field:
[[Image:fieldbuttons-fig4.jpg]]
+
<div>[[Image:fieldbuttons-fig4.jpg]]</div>
  
If we then do a search, the next page will look like this:<br>
+
If we then do a search, the next page will look like this:
[[Image:fieldbuttons-fig5.jpg]]
+
<div>[[Image:fieldbuttons-fig5.jpg]]</div>
 
which is very similar to figure 3.
 
which is very similar to figure 3.
 
    
 
    
== Adding Field Buttons to Forms ==
 
The program must have a <script> tag that invokes the Field Buttons Javascript library.
 
Fundamentally, the Form fields to which field buttons are to be attached must have
 
#* An ID, and
 
#* A specific style class for each field button that will be attached to the form field (see examples below).
 
 
In addition, the program must:
 
# Call two Field Buttons library functions to supply the Field Buttons Javascript library with the button labels (which are defined in a language text string), and button status flags (which are defined in a TNG system variable), and
 
#* Define (through Javascript assignment statements) the Default and All Items values that will be assigned to each form field that has a D or A button.
 
These calls and assignment statements must be defined within an "unnamed function" that is passed to the Field Buttons Javascript library through a shared array variable. (See examples below that can be copied into TNG mods and programs.)
 
 
The program can define the form field ID and/or classes either
 
* By modifying the HTML code directly, or
 
* Through Javascript code that is defined within an unnamed function similar to the required function that defines D and A default values.
 
 
See details and examples in the Implementation
 
 
==Compatibility With Other Mods==
 
This mod is fully compatible with [[Unused Media]], [[Admin Media Search]], and [[Private Media Mod]], the only other mods that affect admin_media.php.
 
 
==Dependencies on other Mods==
 
This mod generates that can be used by the [[Show Mod Names]] mod, which is completely optional.
 
 
==Related Mods==
 
* [[Gedcom Import Mediatype]] is specifically designed to help make process of reassigning Media Collections easier.  It allows you to specific a rarely used mediatype (say, Videos) as the default for new media items in a Gedcom Import.  With new media items assigned to, say Videos, instead of Photos, it will be much easier to identify the new items that need to be reassigned.  You still need this mod (or a more manual process), but [[Gedcom Import Mediatype]] helps to distinguish new media items from old ones.
 
* [[Admin Media Search]] also affects the Admin Media Search, and is more widely applicable than this mod.
 
 
==Requirements==
 
* A working TNG installation.
 
* An installed current version of the [[Mod Manager]].
 
* You should backup files listed in the panel on the right.
 
 
==Automated 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, 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 ==
 
# Try using the [[Mod_Manager_-_Installing_Config_Files#Remove_Mod_Steps|Mod Manager Remove]] capability
 
# Contact me through [http://www.robinrichmond.com/family/mod_support.php My Mod Support form].
 
 
== Visualization of this Mod ==
 
 
 
{| border="1" cellspacing="1" cellpadding="2" class="wikitable"
 
{| border="1" cellspacing="1" cellpadding="2" class="wikitable"
|-
+
| Another Field Buttons example: The Mod Comparison Report kickoff form, just after being loaded, showing three fields that have X, R, and D buttons. (All three have default values that are defined by the Mod Manager Options.)
| <span style="color: red">'''AFTER:'''</span>
+
* In the 'Author to search for field', the default value is being displayed, and it is not empty, so X is visible, and R and D are hidden.
|-
+
* In the 'Include mods whose names contain' field, the default value is empty and is being displayed, so all three buttons are hidden.
| [[Image:admin_media_predefined_search-after.png]]
+
* In the 'Exclude mods whose names contain' field, the value being displayed is not the default, and is not empty, so X and D are displayed, but, as is always the case when a form has just been displayed, D is hidden.
Note the highlighted drop-down list. Only one entry is shown when the page is loaded; it has been expanded to list all of the predefined search choices.  When "Headstones" was selected, the related search string was stored in the Search field in the form.
+
[[Image:fieldbuttons-after.jpg]]
 
+
|}
Note also that the collect "Photos" has been selected, since (without [[Gedcom Import Mediatype]]) most new Media Items are assigned to "Photos" (in the single-collection-folder environment that this mod was designed for).
+
{| border="1" cellspacing="1" cellpadding="2" class="wikitable"
 
+
| The setup form at '''Admin>>Setup>>General&nbsp;Settings>>Robin's&nbsp;Mods''' after the Field Buttons mod has been installed. The four fields define the active status of each of the four types of field button. The four values are saved in the configuration variable $rrconfig['FieldButtonFlags'] in a comma-delimited string, typically as '1,1,1,1'.
When the user clicks on Search, the search results will list Photos that have the words "stone", OR "tomb", OR "grave", OR "burial" (etc) in the Media table description, path, notes, or bodytext fields. These results are (we hope) likely to yield Headstone photos, which belong in the Headstones collectionUpon seeing the results, the user can select the Photos that should be moved, and move several at once.
+
<div>[[Image:fieldbuttons-after-options.jpg]]</div>
 +
(In truth, I'm not sure that it will ever make sense for just one or two buttons types to be deactivatedDeactivating all four button types has the same effect as uninstalling the mod, but it could be useful to deactivate the field buttons temporarily without having to uninstall and later reinstall the mod.)
 
|}
 
|}
  
== The search strings ==
+
==Related Mods==
The Admin Media Search form search the description, path, notes, and bodytext fields of a media item for one search string.
+
Mods that implement Field Buttons include
 
+
* [[Admin_Branches]], [[Admin Cemeteries Search]], [[Admin Places Search]], and [[Admin Reports Search]], all of which attach field buttons to the Search field and a new 'Results per page' field.
The following lines in the English and English-UTF8 versions of cust_test.php define '''a single string''' named 'presearchvalue' that contains multiple multi-valued, case-insensitive search strings.
+
* [[Reports-Floating Results]]. The new form that this mod implements in showreport.php has three 'Results per page' fields with field buttons.  
<syntaxhighlight lang="php" enclose="div">
+
* [[Cemetery Edit]] attaches X and R field buttons to 5 text fields, including the textarea field for Notes.
$admtext['presearchvalue'] = "Census:census,ennumeration";
+
* [[Mod Manager Compare]], where the kickoff form for the new Mod Comparison report attaches D, R, and A buttons to 4 fields (3 of which are illustrated in a Visualization below)
$admtext['presearchvalue'] .= "\nHeadstones:stone,tomb,grave,memorial,burial,cemetery,marker,crypt,resting place";
 
$admtext['presearchvalue'] .= "\nDocuments1:index,births,deaths,marriages,U.S.,records,registration cards";
 
$admtext['presearchvalue'] .= "\nDocuments2:death collection,marriage collection,certificate,license";
 
$admtext['presearchvalue'] .= "\nDocuments3:register,tax list,border crossings";
 
$admtext['presearchvalue'] .= "\nHistories1:bio,history,histories,memoir,notes,story,obit";
 
$admtext['presearchvalue'] .= "\nHistories2:article,letter,will ,will$,wills,probate";
 
</syntaxhighlight>
 
 
 
Each line in the 'presearchvalue' string will be presented to the user as an option in the new the new drop-down box called "Preloaded Searched" on the Admininstration >> Media Search form.  If you select "Headstones" from the drop-down box, the program will search for "stone" OR "tomb" OR "grave" (etc.). 
 
 
 
To accomplish this, the modified code places the keyword "OR:" at the front of the multi-valued search string.  The keyword "OR:" is not a search term, but it tells the program to treat the rest of the string as a series of comma-delimited search terms, each of which will satisfy the match.  '''Thus, with this mod installed, not only can you select one of the predefined search terms, but you can also simply simply type OR: at the beginning of a comma-delimited search string of your own, and force the program to search for ANY of the search terms, rather than the search string as a whole.'''
 
  
Note that
+
==Compatibility & Dependencies With Other Mods==
* A normal search looks in five fields in the Media table - mediaID, description, path, notes, and bodytext fields.  Preloaded searches, however, do not search the mediaID field.
+
No mods are ''strictly'' dependent on this mod, but there is a functional dependency in that, when other mods define Field Buttons in their HTML forms, this mod must be installed for those field buttons to be visible. No errors will occur if the Field Buttons mod is not installed in conjunction with mods that define Field Buttons. The forms will simple act as if the Field Buttons were not defined in the first place.  
* You might want to remove the term the term "stone" from the "Headstones" search string if you have a "Stone" family in your database. The same goes for the term "story" in the "Histories" search string.
 
  
* The term "will " in the "Histories2" search string contains a space so that names like "William" don't cause false matches.
+
== Installation ==
* The dollar sign in the term "will$" in the "Histories2" search string represents the end of the target string, just like it does in regular expressionsGiven that "will " has a space at the end, "will$" allows the search to match "John Brown's will", while not matching "William".
+
This mod uses the standard installation procedure, though it should be noted that this mod contains a mod subfolder that is shared with other mods that implement the "Inner Mod Menu" and that put their options in '''Admin >> Setup >> General&nbsp;Settings >> Robin's&nbsp;Mods'''As a result, as you unzip or copy the mod, you might get a warning noting that a folder already exists.  You can just ignore that warning.
* The search terms "will " and "will$" will, however, match "Will Smith Death Certificate".
+
{{RobinInstallationBoilerplate}}
  
To modify the search strings, you should create entries '''at the bottom of''' your cust_text.php file that '''completely redefine''' $admtext['presearchvalue'].  That is, you should start with a line such as
+
== Language Strings ==
<syntaxhighlight lang="php" enclose="div">
+
This mod defines several strings for the Admin program that defines my mod options, but two language strings that are used for the operation of field buttons are worth mentioning here.
$admtext['presearchvalue'] = "Census:census";
+
* <code>$admtext['rrfb-buttonlabels'] = "X,R,D,A";</code> defines the four letters that identify the four types of field buttons.
</syntaxhighlight>
+
* <code>$admtext['rrfb-all'] = "all";</code> defines the value that represents "All Items" to 'Results per page' fields implemented by several options.
followed by each additional search string, using the "assign and append" operator, ".=", and placing a colon after the search label (Census, Headstones, Documents1, Documents2, etc.).
 
  
This mod places its string definitions immediately after the standard cust_text.php string
 
<syntaxhighlight lang="php" enclose="div">
 
//Put your own custom messages here, like this:
 
//$text[messagename] = "This is the message";
 
</syntaxhighlight>
 
rather than at the very beginning or very end of the file, so that, if you uninstall and reinstall the mod, your own 'presearchvalue' customization will still come after the mod's definition, and will thus be used by TNG.
 
 
   
 
   
== Mod Change History ==
+
== Revision History ==
'''*** The newest version of the mod is at the top of this table ***'''
+
{| border="1" cellspacing="1" cellpadding="2" class="wikitable"
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
+
! Mod Version !! TNG Version !! Date !! Note
|-
+
|- style="vertical-align:top;"  <!-- ############################################################## -->
! Mod Version
+
| [[Media:field_buttons_v12.0.0.3.zip|12.0.0.3]]
! TNG Version
+
| 12.0+
! Date
+
| 18 Aug 2019
! Note
+
| The field buttons behave as they did before, but the Field Buttons API has changed slightly.
|-  
+
* The previous version allowed (actually, required) some mods to directly access the library's internal variables.
| 10.1.0.4
+
* The previous version didn't accommodate some situations where changes to HTML form fields should change the state of the form fields' field buttons.
 +
* Mods written for Field Buttons version 2 can sometimes result in program crashes if the Field Buttons mod is not installed.
 +
* Mods released before August, 2019 should be able to work with version 3 of the Field Buttons mod.
 +
* Mods released after August 1, 2019 cannot work with version 2 of the mod.
 +
|- style="vertical-align:top;"  <!-- ############################################################## -->
 +
| [[Media:field_buttons_v12.0.0.2.zip|12.0.0.2]]
 +
| 12.0+
 +
| 15 May 2018
 +
| No functional changes; made compatible with TNGv12.
 +
|- style="vertical-align:top;"  <!-- ############################################################## -->
 +
| [[Media:field_buttons_v10.1.0.2.zip|v10.1.0.2]]
 +
| 10.1 - 11.1.2+
 +
| 9 Jan 2018
 +
| Field buttons can now have multi-character button labels.
 +
|- style="vertical-align:top;"  <!-- ############################################################## -->
 +
| 10.1.0.1
 
| 10.1 - 11.1.2+
 
| 10.1 - 11.1.2+
| 1 Dec 2017
+
| 28 Dec 2017
| Removed the second line from the cust_text.php target location search string.
+
| New mod
Also repositioned the Predefined Search field in the form layout table to be compatible with a new version of Admin Media Search.
 
|-
 
| 10.0.3.3
 
| 10.0.3 - 10.1.3
 
| 21 Feb 2016
 
| The predefined strings dropdown list now maintains its selection after search and page operations within a search.
 
I also tweaked some of the predefined searches.
 
This mod now uses (and depends on) [[Show Mod Names|Show Mod Names v2+]].
 
|-
 
| 10.0.3.2
 
| 10.0.3 - 10.1.2
 
| 01 Sep 2015
 
| Added some search terms, and implemented special processing for "$" at the end of a search term to anchor that term to the end of a target string.
 
|-
 
| 10.0.3.1
 
| 10.0.3 - 10.1.1
 
| 08 May 2015
 
| Initial release.
 
 
|}
 
|}
  
 
== Sites using this mod ==
 
== Sites using this mod ==
If you download and install this mod, please add your site to the table below.=
+
If you download and install this mod, please add your site to the table below.
  
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
 
{| border="0" cellspacing="1" cellpadding="2" class="wikitable"
Line 218: Line 160:
 
| [[User:Robinrichm|Robin Richmond]]
 
| [[User:Robinrichm|Robin Richmond]]
 
| Mod developer
 
| Mod developer
| 10.1.0.4
+
| 11.0.0.1
 
| 11.1.2
 
| 11.1.2
 +
| English
 +
|-
 +
| [http://colegenealogy.dynu.net/ Cole / Tanner Family Tree]
 +
| [[User:dlcole|David Cole]]
 +
| Public/Private
 +
| [[User:Dlcole|see here]]
 +
| [[User:Dlcole|see here]]
 
| English
 
| English
 
|}
 
|}
 +
[[Category:Mods for TNG v12]]
 
[[Category:Mods for TNG v10]]
 
[[Category:Mods for TNG v10]]
[[Category:admin_media.php mods]]
+
[[Category:genstyle.css mods]]
 +
[[Category:admin_genconfig.php mods]]
 +
[[Category:admin_updateconfig.php mods]]
 
[[Category:cust_text.php English mods]]
 
[[Category:cust_text.php English mods]]

Revision as of 15:05, 2 October 2019

Field Buttons
Summary This strictly optional utility mod installs a Javascript library that supports "Field Buttons" that are placed in HTML forms by other mods.
Validation
Mod Updated 2 Oct 2019
Download link
v12.0.0.3
TNG 12.0
Download stats
Author(s) Robin Richmond
Homepage Robin Richmond's Genealogy Database
Mod Support My Mod Support form or TNG Community Forums
Contact Developer My Mod Support form
Latest Mod v12.0.0.3
Min TNG V 10.1
Max TNG V 12.2
Files modified
Modifies admin_genconfig.php, admin_updateconfig.php, genstyle.css, English cust_text.php;
Installs js/fieldbuttonsmod.js; Installs shared files: rrsetup_modoptions1_cssjs.php, img/rrmodadmin_wikilogo.png
Related Mods
Notes
This is a utility mod that supports other mods, but is not required by them.


Purpose of the Mod

To support the use of "Field Buttons" by other mods. Field buttons are one-character buttons that are attached to HTML form fields by other mods and that do simple editing tasks like clearing a field or restoring its initial value. The Field Buttons mod does not define field buttons in forms; it just enables field buttons by installing

  • A Javascript library that is used by various TNG programs only if this mod has been installed, and
  • A mod option that control whether each type of field button is active.

This mod is needed only if a TNG site administrator

  • Installs at least one mod that places field buttons in an HTML form, and
  • Wants to see field buttons.

That is, if this mod has not been installed, no errors will occur; Field Buttons that have been defined by various other mods will simply not appear.

The buttons are configurable in that

  • The one-character labels for the field buttons are defined in cust_text.php, and can be changed for different languages.
  • Any of the four types of field buttons can be disabled through the mod's option at Admin >> Setup >> General Settings, in the new subform titled Robin's Mods.

Field Buttons

Field Buttons are hyperlinks formatted as buttons, that act as shortcuts to common editing tasks. With a single click on a field button, a particular value to will be assigned to the "attached" form field. There are four types of field buttons:

  • X - Clear the field
  • R - Reset/Reload the initial value; the value that was in place when the form was loaded.
  • D - Default; Set the value to a default that was defined elsewhere, such as by a TNG system parameter or Mod Manager option.
  • A - Set an 'All items' value. (At this writing, A buttons have been used only with "Results Per Page" fields on search forms)

Note that it would be very rare for all four buttons to be attached to one form field. Only the applicable buttons should be attached to any given form field.

The four letters X, R, D, and A are used in documentation and in code to identify the field buttons, and they are the default on-screen labels for the buttons. But the labels are configurable through a translation string. In addition, a set of four fields in the Admin >> Setup >> General Settings >> Miscellaneous screen allow individual buttons to be suppressed in all forms on the TNG site.

Buttons are "attached" to a form field in that

  • They follow it without intervening spaces, and the form field and its field buttons are wrapped by a tag that doesn't allow line breaks, and
  • The buttons' field names are based on the fieldname of the field that they are attached to. The buttons' field names are essentially what causes them to modify their form field.

Visualizations

This screen clip illustrates 5 field buttons on 2 fields in the Admin>>Reports program that has been modified by the Admin_Reports_Search mod.

  1. The search field has X and R buttons. There is no meaning in the search field to a default value (remember, the initial value is covered by the R button) or an "all items" value (which would just be an empty search field).
  2. The 'Results per page" field has R, D, and A buttons.
    • You never want an empty 'Result per page' field, so there is no X Button.
    • The R button restores the initial value - the value that was present when the form was loaded.
    • The D button sets a default value, which, in this case, is the TNG system variable $maxsearchresults.
    • The A button sets a value that represents 'All Items'. That value is the word 'all' (or its translation).

Fieldbuttons-fig1.jpg

Note that

  • the X button is not needed when a field value is already empty,
  • the R button is not needed when the current value is the initial value,
  • the D button is not needed when current value is the default value, and
  • the R button is not needed when the current value is the 'All Items' value.

When a button is not needed, it is shaded out, but still physically present on the screen.

The R buttons in the screen clip above tell us that it does not represent the initial state of a form, because we can see the R buttons. R buttons are always shaded out when the form is first loaded, because, by definition, the form field values when the form is loaded are the initial values. Here's what the same form might look like when first loaded, if the search value is empty, and the Results per page value is the site default value (in this case, 30).

Fieldbuttons-fig2.jpg

The search field's R and X buttons are both shaded out, but still present (and barely visible). The 'Results per page' field's R and D buttons are also shaded out, and only its A button is visible.

If the user enters the search string "children", and clicks on the A button, we'll see this:

Fieldbuttons-fig3.jpg

where the search field's X button is visible because the search field has a non-empty value, both R buttons are visible because both fields have changed, and the 'Results per page' field's D button is visible because the field's value is not the default of 30. Now, only the A button is shaded out.

If the X button is clicked, it will disappear, as will the value in the attached field:

Fieldbuttons-fig4.jpg

If we then do a search, the next page will look like this:

Fieldbuttons-fig5.jpg

which is very similar to figure 3.

Another Field Buttons example: The Mod Comparison Report kickoff form, just after being loaded, showing three fields that have X, R, and D buttons. (All three have default values that are defined by the Mod Manager Options.)
  • In the 'Author to search for field', the default value is being displayed, and it is not empty, so X is visible, and R and D are hidden.
  • In the 'Include mods whose names contain' field, the default value is empty and is being displayed, so all three buttons are hidden.
  • In the 'Exclude mods whose names contain' field, the value being displayed is not the default, and is not empty, so X and D are displayed, but, as is always the case when a form has just been displayed, D is hidden.

Fieldbuttons-after.jpg

The setup form at Admin>>Setup>>General Settings>>Robin's Mods after the Field Buttons mod has been installed. The four fields define the active status of each of the four types of field button. The four values are saved in the configuration variable $rrconfig['FieldButtonFlags'] in a comma-delimited string, typically as '1,1,1,1'.
Fieldbuttons-after-options.jpg

(In truth, I'm not sure that it will ever make sense for just one or two buttons types to be deactivated. Deactivating all four button types has the same effect as uninstalling the mod, but it could be useful to deactivate the field buttons temporarily without having to uninstall and later reinstall the mod.)

Related Mods

Mods that implement Field Buttons include

Compatibility & Dependencies With Other Mods

No mods are strictly dependent on this mod, but there is a functional dependency in that, when other mods define Field Buttons in their HTML forms, this mod must be installed for those field buttons to be visible. No errors will occur if the Field Buttons mod is not installed in conjunction with mods that define Field Buttons. The forms will simple act as if the Field Buttons were not defined in the first place.

Installation

This mod uses the standard installation procedure, though it should be noted that this mod contains a mod subfolder that is shared with other mods that implement the "Inner Mod Menu" and that put their options in Admin >> Setup >> General Settings >> Robin's Mods. As a result, as you unzip or copy the mod, you might get a warning noting that a folder already exists. You can just ignore that warning.

[Show Installation Details]

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]

Language Strings

This mod defines several strings for the Admin program that defines my mod options, but two language strings that are used for the operation of field buttons are worth mentioning here.

  • $admtext['rrfb-buttonlabels'] = "X,R,D,A"; defines the four letters that identify the four types of field buttons.
  • $admtext['rrfb-all'] = "all"; defines the value that represents "All Items" to 'Results per page' fields implemented by several options.


Revision History

Mod Version TNG Version Date Note
12.0.0.3 12.0+ 18 Aug 2019 The field buttons behave as they did before, but the Field Buttons API has changed slightly.
  • The previous version allowed (actually, required) some mods to directly access the library's internal variables.
  • The previous version didn't accommodate some situations where changes to HTML form fields should change the state of the form fields' field buttons.
  • Mods written for Field Buttons version 2 can sometimes result in program crashes if the Field Buttons mod is not installed.
  • Mods released before August, 2019 should be able to work with version 3 of the Field Buttons mod.
  • Mods released after August 1, 2019 cannot work with version 2 of the mod.
12.0.0.2 12.0+ 15 May 2018 No functional changes; made compatible with TNGv12.
v10.1.0.2 10.1 - 11.1.2+ 9 Jan 2018 Field buttons can now have multi-character button labels.
10.1.0.1 10.1 - 11.1.2+ 28 Dec 2017 New mod

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 11.0.0.1 11.1.2 English
Cole / Tanner Family Tree David Cole Public/Private see here see here English