Skip to content

Adam Greenwell

Getting Started With The Hits List

Requirements

  • WordPress 6.2 or newer, tested up to WordPress 7.1.
  • PHP 7.4 or newer.

Installation

  1. Upload the the-hits-list folder to /wp-content/plugins/.
  2. Activate The Hits List from the WordPress Plugins screen.
  3. Open Settings > The Hits List.
  4. Configure tracking and display options.
  5. If Top 10 data is detected, use the import tool to migrate existing counts.

Once active, The Hits List tracks eligible views for public content. The settings control which users and counters are included.

Initial Setup

Review the settings screen before placing popular-post output in a visible site area:

  • Decide whether logged-in users should be counted.
  • Leave Overall count and Daily count enabled if you want lifetime totals and recent reports. Hourly buckets are collected with daily counts.
  • Choose REST API or AJAX under Tracker Type. AJAX is a selectable alternative when REST is blocked, not an automatic retry method.
  • Decide whether view counts should display automatically on single posts.
  • Review display defaults for popular-post output.
  • Set Daily Data Retention. The default is 180 days; hourly retention defaults to 48 hours. Lifetime totals are not aged out, but deletion, count edits, imports, and maintenance can remove or replace them.
  • Import Top 10 data if you are replacing Top 10.

Check Tracking With Your Page Cache

Open a public article as a visitor who should be counted and check that its count increases. If you have a full-page cache, repeat the check on a cached page.

The tracker nonce is generated when a page is rendered. Cached HTML can eventually serve an expired nonce and tracking requests will return 403. Version 1.6.0 does not renew that nonce automatically. Work with your hosting/cache provider to keep cached tracker configuration fresh or exclude affected pages from caching. Dynamic Post Count updates the number shown to readers; it does not refresh the tracker nonce.

Add The Hits List – Popular Posts in the block editor, use the Popular Posts widget, or place [thl_list] in content.

In the block's Popular Posts Settings, choose Order by > Most views for a views ranking or Trending for recent changes relative to each article's baseline. Choose a list or grid layout and select public post types, category/post filters, thumbnails, excerpts, and counts as needed.

Use these controls to narrow a list:

  • Enable Custom period? for Daily range and Hour range. A daily range of 7 includes today and the preceding six days. For an hour-only window, leave Daily range empty and enter an Hour range such as 6.
  • Enable Exclude current post to hide the article being viewed on a singular post/page. Archives and editor previews are unchanged.
  • Set Maximum post age (days) to 30 for articles published today or in the preceding 29 calendar days. 1 means today; 0 leaves age unlimited. This is separate from the period used to count views.

Hour-only windows within hourly retention use hour buckets, including the current partial hour. Longer hour windows, or an hour range combined with a Daily range above 1, fall back to whole days, so their actual span can be wider than the entered hour range.

Shortcode Examples

[thl_list limit="5"]
[thl_list limit="5" order_by="trending" exclude_current_post="1"]
[thl_list limit="5" max_age_days="30" include_categories="12,34"]
[thl_list limit="5" daily="1" daily_range="7"]
[thl_list limit="5" daily="1" hour_range="6"]

Category and post filters use comma-separated IDs: include_categories, exclude_categories, include_post_ids, and exclude_post_ids. Use post_types="post,page" for multiple public content types. layout="grid" and grid_columns="3" change the layout. Shortcode list size is limited to 1–10 posts.

Display A Single Count

Add The Hits List – Post Views. Under Post Views Settings, leave Post ID at 0 to use the current post, or enter a specific ID. Toggle Show when zero as needed. The block follows the site's Count Display Format.

The shortcode equivalents are [thl_views] for the current post and [thl_views id="123"] for a particular post.

Common placements include:

  • Sidebar or footer widget areas.
  • Block editor layouts.
  • Post content, using shortcodes.
  • Homepage or section-front modules.
  • Theme templates that need custom placement.

Confirm the active theme renders titles, images, and excerpts cleanly before promoting the output into prominent site surfaces.

Dashboard And Editor Review

The dashboard has Daily Top Posts, All-Time Top Posts, Views Over Time, Trending Now, and Refresh Candidates cards. Users who can manage site options have access by default.

To give editors or another role access, open Settings > The Hits List > Dashboard Access, select Additional Dashboard Roles, and save. This grants the cards without granting settings access. If a developer capability override is active, its notice explains that it decides access instead.

Under Content List Columns > Show View Columns For, select Posts, Pages, or the public custom post types you use. Posts is selected by default. On each content list, use Screen Options to show Total Views, Today's Views, or condensed Views. Click Total Views or Today's Views to sort. The condensed Views column is display-only and combines lifetime/today counts in one cell.

Inspect An Article

Ensure Show Editor Metabox is enabled, then open an article you can edit and find The Hits List > Article performance. Review lifetime views, the 7 days or 30 days report, and Daily counts and coverage. Both ranges show completed days in the site's timezone and exclude today. Without JavaScript, both reports and their tables remain available.

Limit Metabox to Admins restricts count and display controls to users who can manage site options. Article editors can still read reports and use refresh actions. Viewing reports, changing the report range, and ordinary content saves do not change counts.

Reports can show recorded totals while marking their history unknown or incomplete. A percentage needs covered history for both periods and a nonzero baseline. New articles, paused tracking, pruned rows, imports, or a failed read can make a comparison unavailable. Expanding retention does not restore previously deleted rows. Coverage describes retained recorded data, not a guarantee that every browser view was captured.

Trending may show provisional results with new-article, thin-baseline, or coverage labels. It compares three completed days with the preceding fourteen by default. Use those labels when judging the score.

Follow Up On A Refresh

In Refresh Candidates, use Snooze 30 days to set an article aside temporarily. Use Undo snooze in the confirmation notice or the article's Refresh follow-up panel to restore it sooner. Snoozes expire automatically and affect only the refresh shortlist.

When updating an article:

  1. Save the article changes first.
  2. Choose Mark refreshed on the dashboard or in Refresh follow-up.
  3. Return to the editor panel to inspect the seven-full-day before/after report.

The refresh day and today are excluded. The after window accumulates completed days; it will not show a percentage until the full window and its history are usable. Ordinary saves do not create a refresh marker. Marking the article again starts a new follow-up reference.

Keep Content Out Of Rankings

To suppress one article, check Suppress this post from rankings in its editor controls and save it. If those controls are restricted, ask a site administrator to apply the setting.

For a group of posts, open Settings > The Hits List > Ranking Suppression, select categories or tags by name, and save. A match against any selected term suppresses the post. Child Categories is off by default; enable it to include all descendants of selected categories.

These rules affect public popular/trending lists and dashboard rankings, including Refresh Candidates. Tracking, article reports, and counts remain available. To restore eligibility, clear the individual checkbox and any matching category/tag rules. If rendered lists are stored in a page cache, clear that cache after changing rules.

Export Or Restore Counts

Under Export And Import View Counts, choose CSV or JSON and click Export Counts. The download contains current-site overall and daily counts, not hourly buckets, settings, or refresh markers. Keep a full site backup if you need those too.

To restore a compatible export, upload it under Import View Counts and choose Replace existing counts. This sets the entries in the file to their imported values; it does not replace all unrelated counts. Add to existing counts is for a deliberate merge and adds the values again every time the file is imported.

Check that post IDs match the intended articles on the receiving site. Imports write to that current site, even when the file came from another multisite site. Imported daily rows do not establish uninterrupted tracking coverage.

Deleted Content And Maintenance

Permanently deleting a post removes its lifetime, daily, and hourly counts. Moving it to Trash preserves them by default. On multisite, permanent site removal clears that site's shared count rows; archival and soft deletion do not.

After upgrading to 1.6.0, a one-time background sweep repairs older orphaned rows in small batches. Existing posts are preserved, including drafts, private posts, attachments, and Trash. Check its progress and per-table removal totals on Settings > The Hits List; the multisite report is for network administrators. Let WordPress cron run so the sweep can continue. Errors are shown and retried; a notice qualifies totals if a failed progress save means only saved batches can be reported.

If you use WP-CLI, preview selected posts before clearing their counts:

wp the-hits-list delete-post-counts 123 456 --dry-run
wp the-hits-list delete-post-counts 123 456

The articles remain intact. All post IDs are validated before any deletion. On multisite, the default is the current WP-CLI site; use --blog-id=2 for another existing site. The command reports rows per table, warns when an ID has no counts, and exits nonzero on partial failure. Rerun to remove remaining rows; deletions are not transactional.

Next Steps