Categories

Text Hover

Author: Scott Reilly
Version: 4.1
First released: 2009-07-15
Last update: 2021-06-30
Compatibility: WP 4.9 – 5.7.3
Download: [ zip ]
Description:

Add hover text (aka tooltips) to content in posts. Handy for providing explanations of names, terms, phrases, abbreviations, and acronyms.

Extended Description

This plugin allows you to easily define help text that appears when a visitor hovers their mouse over a word or phrase in a post or page.

Via the plugin’s settings, simply specify the words or phrases that you want to be associated with hover text, and of course, the desired hover texts themselves. The format is quite simple; an example of which is shown here:

WP => WordPress
Matt => Matt Mullenweg
The Scooby Shack => the bar where the gang hangs out

Additional features of the plugin controlled both via settings and filters:

  • Hover text can be enabled for comments (it isn’t by default)
  • Hover text can be made case insensitive (it is case sensitive by default)
  • Hover text can be limited to doing only one replacement per term, per post (by default, all occurrences of a term are given hovertext)
  • Hover text can be rendered using the default browser tooltip (by default, the better-looking qTip2 library is used)
  • Hover text can be expanded to affect other filters

Note: This is not the same as my Text Replace plugin, which defines terms or phrases that you want replaced by replacement text when displayed on your site. Text Hover instead adds the hover text as additional information for when visitors hover over the term, which is otherwise displayed in the post as you typed it.

Links: Plugin Homepage | Plugin Directory Page | GitHub | Author Homepage

Hooks

The plugin exposes a number of filters for hooking. Typically, the code to utilize these hooks would go inside your active theme’s functions.php file. Bear in mind that all of the features controlled by these filters are configurable via the plugin’s settings page. These filters are likely only of interest to advanced users able to code.

c2c_text_hover_filters (filter)

The ‘c2c_text_hover_filters’ hook allows you to customize what hooks get text hover applied to them.

Arguments:

  • $hooks (array): Array of hooks that will be text hovered.

Example:

/**
 * Enable text hover for post/page titles.
 *
 * @param array $filters Filters handled by the Text Hover plugin.
 * @return array
 */
function more_text_hovers( $filters ) {
    $filters[] = 'the_title'; // Here you could put in the name of any filter you want
    return $filters;
}
add_filter( 'c2c_text_hover_filters', 'more_text_hovers' );

c2c_text_hover_third_party_filters (filter)

The ‘c2c_text_hover_third_party_filters’ hook allows you to customize what third-party hooks get text hover applied to them. Note: the results of this filter are then passed through the c2c_text_hover_filters filter, so third-party filters can be modified using either hook.

Arguments:

  • $filters (array): The third-party filters whose text should have text hover applied. Default array( 'acf/format_value/type=text', 'acf/format_value/type=textarea', 'acf/format_value/type=url', 'acf_the_content', 'elementor/frontend/the_content', 'elementor/widget/render_content' ).

Example:

/**
 * Stop text hovers for ACF text fields and add text hovers for a custom filter.
 *
 * @param array $filters
 * @return array
 */
function my_c2c_text_hover_third_party_filters( $filters ) {
    // Remove a filter already in the list.
    unset( $filters[ 'acf/format_value/type=text' ] );
    // Add a filter to the list.
    $filters[] = 'my_plugin_filter';
    return $filters;
}
add_filter( 'c2c_text_hover_third_party_filters', 'my_c2c_text_hover_third_party_filters' );

c2c_text_hover_filter_priority (filter)

The ‘c2c_text_hover_filter_priority’ hook allows you to override the default priority for the ‘c2c_text_hover’ filter.

Arguments:

  • $priority (int): The priority for the ‘c2c_text_hover’ filter. The default value is 2.
  • $filter (string): The filter name.

Example:

/**
 * Change the default priority of the 'c2c_text_hover' filter to run after most other plugins.
 *
 * @param int $priority The priority for the 'c2c_text_hover' filter.
 * @return int
 */
function my_change_priority_for_c2c_text_hover( $priority, $filter ) {
    return 1000;
}
add_filter( 'c2c_text_hover_filter_priority', 'my_change_priority_for_c2c_text_hover', 10, 2 );

c2c_text_hover (filter)

The ‘c2c_text_hover’ hook allows you to customize or override the setting defining all of the text hover terms and their hover texts.

Arguments:

  • $text_hover_array (array): Array of text hover terms and their hover texts. This will be the value set via the plugin’s settings page.

Example:

/**
 * Add dynamic text hover.
 *
 * @param array $text_hover_array Array of all text hover terms and their hover texts.
 * @return array
 */
function my_text_hovers( $text_hover_array ) {
    // Add new term and hover text
    $text_hover_array['Matt'] => 'Matt Mullenweg';
    // Unset a term that we never want hover texted
    if ( isset( $text_hover_array['Drupal'] ) )
        unset( $text_hover_array['Drupal'] );
    // Important!
    return $text_hover_array;
}
add_filter( 'c2c_text_hover', 'my_text_hovers' );

c2c_text_hover_text_comments (filter)

The ‘c2c_text_hover_text_comments’ hook allows you to customize or override the setting indicating if text linkification should be enabled in comments.

Arguments:

  • $state (bool): Either true or false indicating if text linkification is enabled for comments. The default value will be the value set via the plugin’s settings page.

Example:

// Prevent text linkification from ever being enabled in comments.
add_filter( 'c2c_linkify_text_comments', '__return_false' );

c2c_text_hover_case_sensitive (filter)

The ‘c2c_text_hover_case_sensitive’ hook allows you to customize or override the setting indicating if text hover should be case sensitive.

Arguments:

  • $state (bool): Either true or false indicating if text hover is case sensitive. This will be the value set via the plugin’s settings page.

Example:

// Prevent text hover from ever being case sensitive.
add_filter( 'c2c_text_hover_case_sensitive', '__return_false' );

c2c_text_hover_once (filter)

The ‘c2c_text_hover_once’ hook allows you to customize or override the setting indicating if text hovering should be limited to once per term per piece of text being processed regardless of how many times the term appears.

Arguments:

  • $state (bool): Either true or false indicating if text hovering is to only occur once per term. The default value will be the value set via the plugin’s settings page.

Example:

// Only show hovertext for a term/shortcut once per post.
add_filter( 'c2c_text_hover_once', '__return_true' );

c2c_text_hover_use_pretty_tooltips (filter)

The ‘c2c_text_hover_use_pretty_tooltips’ hook allows you to customize or override the setting indicating if text hovering should use prettier tooltips to display the hover text. If false, the browser’s default tooltips will be used.

Arguments:

  • $state (bool): Either true or false indicating if prettier tooltips should be used. The default value will be the value set via the plugin’s settings page.

Example:

// Prevent pretty tooltips from being used.
add_filter( 'c2c_text_hover_use_pretty_tooltips', '__return_false' );

Find out more at the plugin’s WordPress Plugin Repository page.

Screenshots

Click to see full-size image.

  1. A screenshot of the admin options page for the plugin, where you define the terms/acronyms/phrases and their related hover text

    A screenshot of the admin options page for the plugin, where you define the terms/acronyms/phrases and their related hover text

  2. A screenshot of the plugin in action for a post when the mouse is hovering over a defined hover text term using the pretty tooltips

    A screenshot of the plugin in action for a post when the mouse is hovering over a defined hover text term using the pretty tooltips

  3. A screenshot of the plugin in action for a post when the mouse is hovering over a defined hover text term using default browser tooltips (in this case, Chrome on OSX)

    A screenshot of the plugin in action for a post when the mouse is hovering over a defined hover text term using default browser tooltips (in this case, Chrome on OSX)

Installation

  1. Whether installing or updating, whether this plugin or any other, it is always advisable to back-up your data before starting
  2. Install via the built-in WordPress plugin installer. Or download and unzip text-hover.zip inside the plugins directory for your site (typically wp-content/plugins/)
  3. Activate the plugin through the ‘Plugins’ admin menu in WordPress
  4. Go to the Settings -> Text Hover admin settings page and customize the settings (namely to define the terms/abbreviations and their explanations).
  5. Optional: Configure other plugin settings as desired.
  6. Use the terms/abbreviations in posts and/or pages (terms/abbreviations appearing in existing posts will also be affected by this plugin)

Release Log

4.1 (2021-06-29)

  • New: Add new setting “More filters” to allow for user-specified filters to be processed
  • Change: Update plugin framework to 064
    • 064:
    • New: For checkbox settings, support a ‘more_help’ config option for defining help text to appear below checkbox and its label
    • Fix: Fix URL for plugin listing donate link
    • Change: Store donation URL as object variable
    • Change: Update strings used for settings page donation link
    • 063:
    • Fix: Simplify settings initialization to prevent conflicts with other plugins
    • Change: Remove ability to detect plugin settings page before current screen is set, as it is no longer needed
    • Change: Enqueue thickbox during 'admin_enqueue_scripts' action instead of during 'init'
    • Change: Use is_plugin_admin_page() in help_tabs() instead of reproducing its functionality
    • Change: Trigger a debugging warning if is_plugin_admin_page() is used before 'admin_init' action is fired
    • 062:
    • Change: Update is_plugin_admin_page() to use get_current_screen() when available
    • Change: Actually prevent object cloning and unserialization by throwing an error
    • Change: Check that there is a current screen before attempting to access its property
    • Change: Remove ‘type’ attribute from style tag
    • Change: Incorporate commonly defined styling for inline_textarea
    • 061:
    • Fix bug preventing settings from getting saved
    • 060:
    • Rename class from c2c_{PluginName}_Plugin_051 to c2c_Plugin_060
    • Move string translation handling into inheriting class making the plugin framework code plugin-agnostic
      • Add abstract function get_c2c_string() as a getter for translated strings
      • Replace all existing string usage with calls to get_c2c_string()
    • Handle WordPress’s deprecation of the use of the term “whitelist”
      • Change: Rename whitelist_options() to allowed_options()
      • Change: Use add_allowed_options() instead of deprecated add_option_whitelist() for WP 5.5+
      • Change: Hook allowed_options filter instead of deprecated whitelist_options for WP 5.5+
    • New: Add initial unit tests (currently just covering is_wp_version_cmp() and get_c2c_string())
    • Add is_wp_version_cmp() as a utility to compare current WP version against a given WP version
    • Refactor contextual_help() to be easier to read, and correct function docblocks
    • Don’t translate urlencoded donation email body text
    • Add inline comments for translators to clarify purpose of placeholders
    • Change PHP package name (make it singular)
    • Tweak inline function description
    • Note compatibility through WP 5.7+
    • Update copyright date (2021)
    • 051:
    • Allow setting integer input value to include commas
    • Use number_format_i18n() to format integer value within input field
    • Update link to coffee2code.com to be HTTPS
    • Update readme_url() to refer to plugin’s readme.txt on plugins.svn.wordpress.org
    • Remove defunct line of code
  • New: Add get_default_filters() as getter for core filters, third-party filters, or both
  • Change: Allow displayed dropdown values for ‘when’ setting to be translated
  • Change: Improve settings page help text by adding, rephrasing, relocating, and tweaaking some formatting
  • Change: Change text_to_hover setting from being a textarea to inline textarea
  • Change: Move translation of all parent class strings into main plugin file
  • Change: Output newlines after block-level tags in settings page
  • Change: Omit ‘cols’ attribute for textarea since it is overridden
  • Change: Note compatibility through WP 5.7+
  • Change: Update copyright date (2021)
  • Change: Change plugin’s short description
  • Change: Tweak plugin’s readme.txt tags
  • Change: Sync installation instructions in README.txt with what’s in readme.txt
  • Fix: Use correct textdomain for a string translation
  • Unit tests:
    • Change: Restructure unit test directories and files into tests/ top-level directory
      • Change: Move bin/ into tests/
      • Change: Move tests/bootstrap.php into tests/phpunit/
      • Change: In bootstrap, store path to plugin file constant so its value can be used within that file and in test file
      • Change: Move tests/*.php into tests/phpunit/tests/
      • Change: Remove ‘test-‘ prefix from unit test files
      • Change: Rename phpunit.xml to phpunit.xml.dist per best practices
    • New: Add additional punctuation-related test cases
    • New: Add helper function get_core_filters() and get_3rd_party_filters() to DRY up data reuse
  • New: Add a few more possible TODO items
  • Change: Updated screenshot for settings page

4.0 (2020-07-16)

  • New: Add new setting to allow control over when text hovers are handled early or late in text processing process
  • New: Add filter c2c_text_hover_filter_priority for filtering hook priority for text hover handler
  • New: Allow text to hover string to begin and/or end in punctuation.
  • New: Add TODO.md and move existing TODO list from top of main plugin file into it
  • Change: Update plugin framework to 050
    • 050:
    • Allow a hash entry to literally have ‘0’ as a value without being entirely omitted when saved
    • Output donation markup using printf() rather than using string concatenation
    • Update copyright date (2020)
    • Note compatibility through WP 5.4+
    • Drop compatibility with versions of WP older than 4.9
  • Change: Remove plugin setting page help text indicating order matters (it hasn’t since v3.8)
  • Change: Note compatibility through WP 5.4+
  • Change: Drop compatibility with versions of WP older than 4.9
  • Change: Update links to coffee2code.com to be HTTPS
  • Unit tests:
    • New: Add get_filter_names() as a helper method for getting the default and third-party filter names
    • New: Add unhook_default_filters() as a helper method to unhook plugin’s default filters hooked to text_hover()
    • New: Add test case for hover text that includes HTML
    • New: Add tests for enqueue_scripts(), options_page_description()
    • New: Add test for setting name
    • New: Add tests for setting defaults
    • New: Add explicit tests to ensure falsey hover text values don’t alter original text
    • New: Add explicit tests to ensure text replacements don’t occur within abbr tag contents or in any tag attributes
    • Change: Store plugin instance in test object to simplify referencing it
    • Change: Remove unnecessary unregistering of hooks in tearDown()
    • Change: Add $priority argument to test_hover_applies_to_default_filters()
    • Change: Remove duplicative reset_options() call
    • Change: Rename unit test function so that it is treated as a unit test
    • Change: Use HTTPS for link to WP SVN repository in bin script for configuring unit tests (and delete commented-out code)
  • Change: Update screenshot

3.9.1 (2020-01-12)

  • Fix: Revert to apply to the the_excerpt filter, which was mistakenly changed to get_the_excerpt
  • Change: Update some inline documentation relating to third-party plugin hook support
  • Unit tests:
    • Change: Implement a more generic approach to capture default values provided for a filter
    • New: Add test to verify the lack of any defined hover text doesn’t remove zeroes from text
    • Fix: Correct typo in function name used

Copyright & Disclaimer

Copyright © 2009-2021 by Scott Reilly (aka coffee2code)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Discussion / Support

Have any questions, comments, or suggestions? Please provide them via the plugin’s WordPress.org support forum. I’ll do my best to reply in a timely fashion and help as best I can.

Unfortunately, I cannot provide guaranteed support, nor do I provide support via any other means.

Was this plugin useful useful to you? Consider giving it a rating. If you’re inclined to give it a poor rating, please first post to the support forum to give me a chance to address or explain the situation.

7 replies on “Text Hover”

[…] Text Hover von Scott Reilly ermöglicht es normalen Text mit einer “Hover” Funktion auszustatten. So können zum Beispiel, wenn man mit der Maus über den Text fährt einzelne Begriffe erklärt, oder zusätzliche Informationen angezeigt werden. Das Plugin funktioniert mit WordPress Versionen WP 2.2+, 2.3+ und 2.5+ Verwandte Artikel […]