Field Buttons

From TNG_Wiki
Revision as of 20:11, 3 December 2017 by Robinrichm (talk | contribs)

Jump to: navigation, search
Field Buttons
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.
Validation
Mod Updated {{{mod_last_update}}}
Download link 10.1.0.1
TNG 11.0
TNG 10.1.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 10.1.0.2
Min TNG V 10.1
Max TNG V at least 11.1.2
Files modified
Modifies admin_genconfig.php, admin_updateconfig.php, English cust_text.php;
Installs js/fieldbuttons.js
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, by installing

  • 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.

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
  • Wants to see Field Buttons in forms.

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.

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:

  • 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.)

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 (1)

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.

  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, and the X button serves the purpose of clearing the field.)is perhaps an empty field).
  2. The 'Results per page" has R, D, and A buttons.
    • 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.
    • And 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.

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).
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 click 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.

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 Details section below.

Compatibility With Other Mods

This mod is compatible with other mods that modify the Admin >> Setup >> General Settings screen.

Dependencies

This mod is not dependent on any other mods, nor are any other mods strictly dependent on this mod. But, as noted above, when other mods install Field Buttons, this mod must be installed in order for those field buttons to be visible.

Related Mods

Mods that implement Field Buttons include

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

  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.

In the event of a problem

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

Visualizations (2)

AFTER: The Mod Comparison Report kickoff form, just after being loaded, where 3 fields have X, R, and D buttons. (All 3 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 the R and D buttons are hidden.
  • In the 'Include mods whose names contain' field, the default value is empty and is being displayed, so all 3 buttons are hidden.
  • In the 'Exclude mods whose names contain' field, the value being displayed is not the default, and is not empty, so the X and D buttons are displayed, but, as is always the case when a form has just been displayed, the D button is hidden.

Fieldbuttons-after.jpg }}

AFTER: The Admin>>Setup>>General Settings>>Miscellaneous Form

After the Field Button status options have been installed, the bottom of the defines the status of each button type. The four values are saved in one comma-delimited string, typically as '1,1,1,1'.
Fieldbuttons-after-options.jpg }}

Detailed Instructions

=

The search strings

$admtext['presearchvalue'] = "Census:census";

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

//Put your own custom messages here, like this:
//$text[messagename] = "This is the message";

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

*** The newest version of the mod is at the top of this table ***

Mod Version TNG Version Date Note
10.1.0.4 10.1 - 11.1.2+ 1 Dec 2017 Removed the second line from the cust_text.php target location search string.

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 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

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 10.1.0.4 11.1.2 English