Field Buttons
| In TNGv14, this mod has been absorbed into Mod Settings Blocks. This article is still the best documentation of Field Buttons.
Mods Settings Blocks now has a mod setting (in a Mod Settings Block, of course) that can disable Field Buttons, which are enabled by default. |
| Field Buttons | ||||
|---|---|---|---|---|
| Summary | Installs a Javascript library that supports "Field Buttons" that are placed in HTML forms by other mods. | |||
| Validation | ||||
| Mod Updated | 6 Oct 2019 | |||
| Download link | (Retired in TNGv14)
v13.0.0.3a
v12.0.0.3
| |||
| 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 | v13.0.0.3 | |||
| Min TNG V | 10.1 | |||
| Max TNG V | 13 | |||
| Files modified | Modifies admin_genconfig.php, admin_updateconfig.php, genstyle.css, English cust_text.php; Installs js/fieldbuttonsmod.js; | |||
| Related Mods | Admin_Branches, Admin Cemeteries Search, Admin Places Search, Admin Reports Search Cemetery Edit, Mod Manager Compare, and many others. | |||
| 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 f this mod has be 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
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.
Mod Options
This mod's options are defined in a Mod Settings Block at Admin >> Setup >> General Configuration, in the new subform named "Mod Settings Blocks. The only options are four checkboxes that enable each of the four types of field buttons. (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.)
Other Mods
Related Mods
The Mod Settings Blocks mod packages this mod's options into what I call a "Mod Settings Block", which is a set of form fields that formatted and labeled so that it stands out among other options in an Admin>>Setting form. Mod Settings Blocks is a prerequisite for this mod; it must be installed before this mod can be installed. About 17 mods define Fields Buttons, including:
- 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.
- Reports-Floating Results. The new form that this mod implements in showreport.php has three 'Results per page' fields with field buttons.
- Cemetery Edit attaches X and R field buttons to 5 text fields, including the textarea field for Notes.
- 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)
Although numerous mods define field buttons, no field buttons will be visible in any TNG page unless the Field Buttons mod is installed. No errors will occur if the Field Buttons mod is not installed; the pages that define them will simply act as if the Field Buttons were not defined in the first place.
Compatibility
There are no mod conflicts or compatibility issues.
Installation
This mod uses the standard installation procedure, though it should be noted that, In TNGv12 only 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 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
- 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.
Problems?
- Try using the Mod Manager Remove capability
- Contact me through My Mod Support form.
Visualizations
Example 1
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).
- 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).
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).
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:
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:
If we then do a search, the next page will look like this:
which is very similar to figure 3.
| Example 2: 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.)
|
| The Field Buttons options in their Mod Settings Block
A Mod Settings Block is an outlined subform within an Admin>>Setup program that contains the options for a single mod. What is most notable about a Mod Settings Block is that a hyperlink directly to a Mod Settings Block displays only that block (i.e. only one mod's options), not all of the other options in the form or subform. Here, you see the this mod's Mod Settings Block, in admin_genconfig.php, at Admin>>Setup>>General Settings. The triangular arrow next to the subfolder heading Mod Settings Blocks is pointing to the right, meaning that the subform is not open, and that your site's other mod settings blocks are not visible. If you were to open the subform by clicking on the heading, you would see the mod settings blocks for other mods that you have installed.
|
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 |
|---|---|---|---|
| 13.0.0.3a | 13 | 6 Oct 2020 | No functional changes. With the upgrade to TNGv13, the mod options are handled by the required Mod Settings Blocks mod rather than a shared Includes library. |
| 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.
|
| 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 | 13.0.0.3b | 13.0 | English |
| The Cole / Tanner Family Tree | David Cole | Public/Private | see here | see here | EN, DE, FR, ES, NL |
