WRT Reading Tools

Complete Documentation v1.1.3

Description	Adds a bar with reading information (time, word count, views) and accessibility tools (font resizing, contrast, clean print) to WordPress content.
Version	1.1.3
Author	LevelNetwork.it
Minimum Requirements	WordPress 5.4+, PHP 7.4+

1. Introduction

WRT Reading Tools is a comprehensive plugin designed to enhance the reading experience and accessibility of content on your WordPress site. It adds an elegant, customizable bar above or below Posts and Pages, providing readers with useful metadata and interactive tools.

The plugin is lightweight, translation-ready, and offers extensive customization options via the administration panel, including a live color preview.

2. Key Features

2.1 Information Components

• Word Count: Automatically calculates and displays the total number of words in the main content.
  • Uses an advanced DOM/XPath method for higher accuracy, including a fallback system. You can define specific CSS selectors to target or exclude areas from being counted.
• Estimated Reading Time: Shows the time needed to read the article in minutes, calculated based on word count and a configurable Words Per Minute (WPM) speed.
• View Counter: Tracks and displays the number of article views. It uses AJAX for maximum compatibility with caching systems, includes security nonces, and cookie tracking to prevent duplicate counts.
  • Note: Disabled by default; must be enabled in settings. Logged-in administrators are not counted.

2.2 Accessibility and Utility Tools

• Font Resizer: "+" and "-" buttons to increase or decrease the font size of the main content. Includes an optional "Reset" button. Stores user preferences via LocalStorage.
• Contrast Mode (Night Mode): A toggle to activate/deactivate a high-contrast or night mode. Stores the user's preference. A wide selection of button icons is available directly from the settings.
• Clean Print: A button to print a clean version of the main content only, formatted for printing while hiding unnecessary elements like the bar itself, sidebars, or footers. Uses a hidden iframe for precise results.

2.3 Backend and Customization Features

• 50 Built-in Color Palettes: A large selection of predefined color schemes with a live preview directly on the settings page.
• Target & Exclude Selectors: Crucial settings to define the theme's CSS selectors that the font resizer and print function should act upon, and specific elements to ignore (like injected ads or author boxes), ensuring compatibility with almost all themes.
• Statistics Metabox: Adds a box in the post edit screen (sidebar) showing total views, allowing a custom starting value for that post, and an AJAX button to reset statistics.

3. Installation and Initial Configuration

1. Upload the plugin folder to the /wp-content/plugins/ directory or install it via the dashboard (Plugins > Add New > Upload Plugin).
2. Activate the plugin.
3. Navigate to Settings > Reading Tools to access the configuration.

4. Usage Guide and Best Practices

The settings page is organized into logical sections.

4.1 Display Settings

• Show On: Choose where to automatically display the bar (Posts only, Pages only, Both, or "Manual Placement Only" to use shortcodes only). The homepage is always excluded automatically.
• Position: Above or Below the content.
• Show on Mobile: Option to hide the bar on small screens via CSS.

4.2 Target Selectors - Crucial

• Font Resizer Target: Enter the CSS selector for your theme's main text container (e.g., .entry-content or #main-content). If the +/- buttons don't work, this selector is likely incorrect.
• Clean Print Target: Enter the selector for the specific area to be printed. Usually, this is the same as the Font Resizer target.
• Word Count Target (Optional): Specific selector for word calculation. If left empty, it falls back to the filtered content.
• Exclude Selector CSS (Optional): Comma-separated list of elements to completely ignore (e.g., .ad-banner, .related-posts, #author-box). Content inside these will NOT be counted, resized, or printed.

4.3 Components & Options

• Enable/Disable individually: Word Count, Reading Time, View Counter, Font Resizer.
• Configure advanced options:
  • WPM: Words per minute for time estimation (Default: 200).
  • Global Start: Initial view value for new posts.
  • Cookie Hours: Validity period for the view tracking cookie (Default: 6 hours).

4.4 Toolbar Buttons

• Enable/Disable additional buttons: Size Reset, Contrast, Print.
• Contrast Button Icon: Select the icon for the contrast button, with a live preview in the palette section.

4.5 Color Palette

• Choose from 50 modern color palettes. The Live Preview area will instantly show how the bar will appear, including info icons, buttons, and chosen contrast icons.
• Note on Custom CSS: For security compliance with WordPress.org guidelines, the Custom CSS field has been removed from the plugin. To add specific style overrides, please use the native WordPress customizer under Appearance > Customize > Additional CSS.

5. Shortcodes

To ensure stability and data consistency, only one unified shortcode is supported:

• [lnwrt_only_tools] - Displays only the interactive button group (Resizer +/-, Reset, Contrast, Print), based on which buttons are enabled in global settings.
  • Usage Example: [lnwrt_only_tools id="123"] (ID is optional, useful for forcing HTML element uniqueness or post context).
  • Note: For buttons to function, the plugin assets (JS/CSS) must be loaded on the page. This usually happens if the main bar is enabled for that content type, even if hidden via CSS.

6. View Statistics Metabox (Admin)

In the edit screen for Posts and Pages (sidebar), you will find the "WRT View Stats" box:

• Total Views: Displays the current formatted count.
• Reset (Button): Immediately clears views via AJAX (requires confirmation). The count updates after a page refresh.
• Start Count At: Allows setting a specific starting value for *this* post.
  • Note: This field is editable only if the post is in draft/unpublished status or if the current count is exactly 0. Once tracking begins (>0), the starting value is no longer editable to maintain data integrity. If empty, it uses the global default.

7. Technical Notes for Developers

Main Hooks and Constants

• The plugin defines several constants in the main file (levelnetwork-wrt-reading-tools.php) for versions, paths, and meta/nonce keys.
• Uses wp_localize_script to pass data to the frontend in the unified lnwrt_frontend_params object (or lnwrt_admin_params in the backend).
• Main filter: the_content (priority 20) for automatic bar insertion.
• Available filters for developers:
  • lnwrt_metabox_post_types: Modify post types where the metabox appears.
  • lnwrt_get_color_palettes: Add or modify built-in palettes.
  • lnwrt_show_on_post_type: Fine control over bar display per post type.
  • lnwrt_frontend_localize_params / lnwrt_admin_localize_params: Filter data passed to JS.

Word Count Calculation Method (DOM/XPath)

The plugin attempts to load filtered content into a DOMDocument, executes an XPath query based on the configured selector to extract clean text (excluding elements matching the Exclude Selector), and counts the words. If the selector is complex or DOM loading fails, it uses a fallback based on minimal cleaning of the full content via wp_strip_all_tags.