5. FAQ
First thing is to read all the online documentation available (Installation, Usage, Wiki, and of course this section) as they should address most of the questions you might have about this plugin.
If WordPress Popular Posts is not working as expected on your website and none of the FAQs listed below provide an answer to the issue(s) you may be having then doing some initial troubleshooting could give you some clues about what's going on.
The Health Check & Troubleshooting plugin and its Troubleshooting Mode will allow you to disable plugins and even switch to a different theme without affecting your visitors. For them your website will continue to work as usual, same theme and same active plugins as before. It only affects the user who enabled the Troubleshooting Mode (you). This is useful because this way you can check whether the problem is being caused due to a conflict with another plugin and/or your current theme.
So:
- Install the Health Check & Troubleshooting plugin and enable its Troubleshooting Mode mode.
- Go to Plugins and make sure that only WordPress Popular Posts is activated (and that all of your other plugins are disabled), then try to reproduce the problem.
- If the issue is gone and WordPress Popular Posts is working as expected then the problem is likely being caused by at least one of your other plugins. Reactivate one of them, check again and repeat until the issue reappears to find the culprit(s).
If you prefer a video tutorial you may want to check out Automattic's How to health check or troubleshoot plugins and themes video to learn how to use the Health Check & Troubleshooting plugin.
If the problem persists even with all of the other plugins deactivated, try switching to a different WordPress theme for a moment (eg. Twenty Twenty), make sure that WPP is the only active plugin, and check again. If switching themes didn't make a difference then please open a new issue or stop by the support forum to report the problem.
Alternatively if you have a Staging website already set up (or plan to get one) you can also disable all of your plugins there -except for WPP- and do the tests as described above - but in this case installing the Health Check & Troubleshooting plugin won't be necessary.
Stopping by the Support Forum is also a good idea if you can't find an answer here. Please share as much information as possible (what the issue is, how to reproduce it, active plugins, site URL, etc) so I can help. Do make sure to check whether someone else has reported the same issue already though.
Remember: read first. It'll save you (and me) time.
-GENERAL FAQs-
The idea of creating this plugin came from the need to know how many people were actually reading each post. Unfortunately WordPress doesn't keep views count data of your posts anywhere. Because of that -and since I didn't find anything that would suit my needs- I ended up creating WordPress Popular Posts: a highly customizable, easy-to-use WordPress plugin that keeps track of what's popular on your site so you can showcase it to your visitors!
Out-of-the-box WordPress doesn't keep track of post/page views count, only comments count. WordPress Popular Posts adds the ability to track post/page views to your WordPress site for you from the moment you first installed the plugin.
When sorting popular posts by views, WordPress Popular Posts will use the post/page views data it started caching since the moment you installed it to rank the top posts according to the settings you have configured in the plugin. WordPress Popular Posts can also rank the popularity of your posts based on comments count as well.
Yes, generally speaking WordPress Popular Posts should work with most (if not all) page caching solutions available out there (eg. WP Super Cache, W3 Total Cache, WP Rocket, SiteGround's Page Optimizer, WPEngine's page cache, etc). However, please note that:
- When you first install WordPress Popular Posts and after every plugin update, flushing your site's page cache is highly recommended to make sure that WPP can insert its JavaScript code into your posts and pages correctly.
- Your caching plugin's page cache must expire at least once per day (every 12 hours would be best) so WPP can keep track of your post/page views. The reason for this is that WPP uses a security token (or nonces as the WordPress team calls them) to prevent the misuse of the plugin by external actors. Said token expires roughly every 12-24 hours by default and so it's recommend having your site recreate its page cache every 12 hours in order for WPP to obtain a new security token and do its job as expected. Alternatively -although not really recommended for security reasons- you could also have WordPress Nonces last at least as long as your site's cache lifetime, that way it won't be necessary to have your caching plugin regenerate its cache every 12 hours or so.
- Some page caching solutions include a JS minification/bundling feature. In some cases this (the minification/bundling thing) isn't handled properly, breaking WPP's ability to track visits to your posts & pages. See here for more details: Is WordPress Popular Posts compatible with plugins that minify/bundle JavaScript code?
Also, you'll want to make sure to enable the Load popular posts list via AJAX feature to keep your caching plugin from caching your popular posts list(s):
- Go to Settings > WordPress Popular Posts > Tools.
- Under Data, set Load popular posts list via AJAX to Enabled, then click on the Apply button below to save changes.
- Finally, clear your site's page cache for changes to take effect.
Yes, WordPress Popular Posts should work just fine with most/all security plugins out there as long as they allow WPP access to the REST API (/wp-json). WPP relies on the REST API to register page views, load your popular posts lists, etc.
If you must restrict access to the REST API for some reason -eg. to improve security- then please make sure to allow WordPress Popular Posts access to its REST API endpoints so it can do its job. Some security/firewall plugins provide a way to whitelist access to specific endpoints and/or namespaces while blocking everything else, check the documentation of your security/firewall plugin or reach out to its developer for more details.
Some of these plugins can at times be a bit too aggressive when minifying / bundling JavaScript code which often leads to stuff being broken. In WPP's case this usually means that the plugin stops tracking visits normally, or that your popular posts list won't display properly / at all, etc.
If this is your case then please try clearing said plugin's JavaScript cache and check again. If the problem persists after that and WPP still doesn't work as expected then you may need to tune your JavaScript Bundling / Minification settings a bit.
For example:
- If you're using the W3 Total Cache plugin, go to its Minify settings page and under Never minify the following JS files add
/wp-content/plugins/wordpress-popular-posts/assets/js/wpp.min.js, then click on Save Changes and then also on the Empty All Caches button for changes to apply immediately. - If you're using the WP Fastest Cache plugin, go to its settings page and click on the Exclude tab. Under Exclude JS, click on the Add Rule button, then add
wpp.min.jsand click on Save. Lastly, go to the Delete Cache tab and click on Delete Cache and Minified CSS/JS button. - If you're using the WP Rocket plugin, go to its File Optimization tab and under Exclude JavaScript Files add
/wp-content/plugins/wordpress-popular-posts/assets/js/(.*).js(or/wp-content/plugins/wordpress-popular-posts/assets/js/wpp.min.js). Finally, go to WP Rocket > Dashboard and click on the Clear Cache button so changes are applied to your site right away. - If you're using the WP Optimize plugin, go to its Minify page then click on the JavaScript tab. Under Exclude JavaScript from processing add
/wordpress-popular-posts/assets/js/and save changes. Additionally, you may also need to disable the Process HTML option under the Minify Status tab as well. Finally, if you're using WP Optimize's Page Caching feature please go to its Cache page and click on Purge Cache for changes to take effect. - If you're using the Fast Velocity Minify plugin, go to its settings page and click on the Pro tab, then under Ignore List add
/wordpress-popular-posts/assets/js/. When you're done, scroll down to the bottom of the page and click on Save Changes. Next, click on the Status tab and click on the Delete button under Purge the cache files so these changes are applied right away. - If you're using the Merge + Minify + Refresh plugin, add this line to the box under Ignore these files (one per line):
https://www.my-domain.com/wp-content/plugins/wordpress-popular-posts/assets/js/wpp.min.js(replacewww.my-domain.comwith your actual domain name) and save changes. Remember to click on Purge All afterwards for changes to take effect. - If you're using the Hummingbird plugin by WPMU DEV head to Hummingbird > Asset Optimization, then under Configuration > Exclusions click on File exclusions, select the wpp-js option and click on Publish Changes. When you're done, go to Hummingbird > Caching > Page Caching and click on the Clear Cache button so these changes are applied to your website right away.
Other plugins provide similar ways to exclude specific .js files from their JavaScript minification/bundling process. Please make sure to check their documentation and/or get in touch with their respective developers for more details.
There are a number of reasons that might explain why you are seeing this message:
- No one has seen or commented on your posts/pages since WordPress Popular Posts' activation, give it some time (or continue reading below if you feel something's not working as expected).
- No one has seen or commented on your posts/pages within the configured Time Range, so go out there and promote your content a bit in order to attract more visitors to your website.
- There might be something on your website that's preventing WordPress Popular Posts from working as expected, see WordPress Popular Posts is not tracking visits, what's going on?
This usually means that there's an issue somewhere on your website:
- Do you have a caching plugin installed on your site? If so, please read this FAQ: Is WordPress Popular Posts compatible with caching plugins?
- Are you using a plugin to minify assets on your site (eg. Autoptimize, Fast Velocity Minify, etc)? If so, please read Is WordPress Popular Posts compatible with plugins that minify/bundle JavaScript code?
- Are you using a security / firewall plugin? If so, please check out this FAQ: Is WordPress Popular Posts compatible with security / firewall plugins?
- Are you using a plugin that disables / restricts access to the REST API? If so, please read Is WordPress Popular Posts compatible with security / firewall plugins?
- There may be a conflict with another plugin (or plugins) on your website. Please check the troubleshooting instructions for more details.
- Your theme does not have the wp_head() tag in its
<head>section, required by WPP to keep track of what visitors are viewing on your site. - WordPress Popular Posts was unable to create its database tables (
_popularpostsdata,_popularpostssummaryand_popularpoststransients) so please make sure that your hosting provider has granted your account permissions to create, update and modify tables in the database.
Checked all of these already and the issue is still present? Following the troubleshooting instructions may help.
Performance and efficiency are very important (and often critical) for any project, as I'm sure we can all agree. WordPress Popular Posts has been built with this idea in mind.
However, and due to its nature, the WordPress Popular Posts plugin can be resource-intensive and so without the right configuration there's a good chance that your website might experience some performance degradation:
- You have a medium / high traffic website without object caching enabled; or,
- Besides WordPress Popular Posts, there are also other resource-intensive plugins and/or scripts running on your site; or,
- Your hosting provider either does not provide support for the InnoDB storage engine or it has been disabled, something that can have a noticeable performance impact on your database server when using this plugin (see Checking InnoDB Availability or consult directly with your hosting provider); or,
- A combination of any/all of the above.
To make sure your site's performance stays up to par please check out the Performance suggestions section.
My current theme does not support widgets (booooo!) Can I show my most popular posts in any other way?
Yes, there are other options: you can use the wpp shortcode, which allows you to embed your popular listing directly in the content of your posts and/or pages; or you can use the wpp_get_mostpopular() template tag. Both options are highly customizable via parameters.
By default the plugin will register every page view from all visitors, including logged-in users. If you don't want WPP to track your own page views, please go to wp-admin > Settings > WordPress Popular Posts > Tools and change the "Log views from" option from Everyone to your preferred choice.
The plugin will pick the post thumbnail from one of the following options (see Settings > WordPress Popular Posts > Tools > Thumbnails > Pick image from):
- Featured Image (default).
- First image on post.
- First attachment.
-
Custom field (your custom field must return either an image URL -eg.
https://www.example.com/some-image.jpg- or an attachment ID).
If no image is found then a "No thumbnail" image will be displayed instead.
Please make sure that:
- you have assigned one to your post (see How does WordPress Popular Posts pick my posts' thumbnails? for more details);
- at least the gd extension for PHP is installed and enabled on your server, otherwise WPP won't be able to generate thumbnails (see Settings > WordPress Popular Posts > Debug, under System Info);
- the image file actually exists on your server, otherwise WordPress Popular Posts won't be able to create a thumbnail from it.
Fortunately yes. Go to wp-admin > Settings > WordPress Popular Posts > Tools and check under Thumbnails. You'll find the Default thumbnail option which you can use to set your own default thumbnail image.
Ideally the thumbnail you're going to use should be already set with your desired width and height - however, the Media uploader will give you other size options as configured by your current theme.
It depends:
- If you're seeing an image that says "No thumbnail" then please read this FAQ: I'm seeing a "No thumbnail" image, where's my post thumbnail?
- If your thumbnails are broken / not loading at all then it's likely that there's a conflict with another plugin. For example, if you're using a plugin that lazy loads images (Smush, ShortPixel, Optimole, etc) then this might cause WPP's thumbnails to break due to a conflict with WPP's own Image Lazy Loading feature and in that case either disable WPP's Lazy Loading feature and let your other plugin lazy load your thumbnails or have your image lazy loading plugin ignore -if possible- any images that contain the
wpp-thumbnailCSS class.
If none of the above suggestions help fix the issue then please follow the instructions from this FAQ to do some basic debugging and figure out what's going on: I need help with your plugin! What should I do?
Where can I find the list of parameters accepted by the wpp_get_mostpopular() template tag / [wpp] shortcode?
You can find it here: Parameters.
Simply type in your custom post type(s) (eg. book, recipe, movie, etc) into the Post Type field from the widget. If you're using either the wpp_get_mostpopular() template tag or the [wpp] shortcode, use the post_type parameter for this.
- If you're using the WordPress Popular Posts widget or the WordPress Popular Posts block you can enable the Use custom HTML markup option under HTML Markup settings to customize the HTML structure of your popular posts list in conjunction with WPP's built-in Content Tags and/or your own custom Content Tags (see Display Tags and Author image for a real life example) so your popular posts list looks exactly the way you want it to. You can also try your hand at creating a widget theme.
- If you're using the wpp_get_mostpopular() template tag and/or the [wpp] shortcode, use the parameters wpp_start, wpp_end and post_html to customize the output (see Parameters for documentation and examples). You can use Content Tags (see above) here as well.
- You can also customize the HTML markup via WordPress filters by hooking into wpp_custom_html or wpp_post. Please check the Filters page for more details.
Here are a couple of examples on customizing the widget to get you started.
Sure, here you go: Popular Posts RSS Feed.
I would like to clear all data gathered by WordPress Popular Posts and start over. How can I do that?
If you go to wp-admin > Settings > WordPress Popular Posts > Tools, you'll find two buttons: Clear cache and Clear all data. The first one just wipes out what's in cache (Last 24 hours, Last 7 Days, Last 30 Days, etc.), keeping the historical data (All-time) intact. The latter wipes out everything from WordPress Popular Posts data tables - even the historical data.
Note that this cannot be undone so proceed with caution.
Starting from version 3.0.0, WPP checks for WordPress Multisite. While I have not fully tested it I believe WPP should work just fine with Multisite (and if it doesn't, please let me know).
-STYLING FAQs-
Yes, WPP includes a stylesheet called wpp.css located at /wp-content/plugins/wordpress-popular-posts/assets/css/. However, it doesn't include any predefined design, just some basic CSS rules.
Each time WordPress Popular Posts is updated the wpp.css stylesheet gets reset and I lose all changes I made to it. How can I keep my custom CSS?
Copying your modified wpp.css file into your theme's folder (eg. /wp-content/themes/twentytwentyone/wpp.css) will prevent future plugin updates from overwriting it with the default wpp.css file.
If you're trying to customize one of the built-in widget themes (eg. Cards Compact) though please have a look at the Customizing an existing theme section from the Wiki to learn what's the proper way to do this so that future plugin updates don't overwrite your changes.
If none of the included themes fit your taste and/or you'd like to use a specific design with your Popular Posts list you can customize WPP's HTML markup to make it look exactly the way you want.
If you're not familiar with HTML/CSS in general -or if you don't have the time to do this yourself- you may want to consider contacting the people who's in charge of maintaining your website and have them assist you with this. You could also hire a freelance developer to get this done (I may also be available for freelance work if you're interested).
You can disable the stylesheet via wp-admin > Settings > WordPress Popular Posts > Tools.
-WIDGET-SPECIFIC FAQs-
It allows you to show a heading for your most popular posts listing. If left empty, no heading will be displayed at all.
This filter allows you to decide which post types to show on the listing. By default it will retrieve posts only (which should be fine for most cases).
You can show more than one post type by adding them into the field, comma separated (eg. post, page). Custom Post Types are supported, too.
This allows you to filter posts by a given taxonomy. You could for example have a WPP widget that lists all popular posts that belong to a specific category (eg. Web Development); or exclude those posts that use a specific tag.
To use it simply add the ID(s) of the term(s) (eg. the category ID) to the Taxonomy field. A negative sign in front of the ID (eg. -25) will exclude posts that are associated to this term ID. You can specify more than one ID with a comma separated list (eg. 24,3,-25).
To obtain the ID of your taxonomy -in case you don't know how to- you can use a plugin such as Reveal IDs by Oliver Schlöbe. It'll add an ID column to your Categories / Tags screen.
Similarly to the Taxonomy filter, this one lets you filter posts by author ID. You can specify more than one ID with a comma separated list (but unlike the Taxonomy filter, you can't exclude author with a minus sign... yet).
You can use a plugin like Reveal IDs to see the IDs of your users in the Users Screen of your dashboard.
If checked, WordPress Popular Posts will show how your readers are rating your most popular posts. This feature requires having WP-PostRatings plugin installed and enabled on your blog for it to work.
If checked, you will be able to customize the HTML markup of your popular posts listing. For example, you can decide whether to wrap your posts in an unordered list, an ordered list, a div, etc.
For more details, check How can I use my own HTML markup with your plugin?
-OTHER STUFF THAT YOU (PROBABLY) WANT TO KNOW-
Yes, here's the complete list of supported languages.
I want to translate your plugin into my language / help you update a translation. What do I need to do?
If you're interested in helping translate WordPress Popular Posts into your language please go to WPP's Translation Project, find your locale and submit your translation suggestions. A Translation Editor from the WordPress team will then review them and if everything's fine your translations will be added to the plugin.
You can also translate WPP for your website only using a gettext editor, like Poedit for example. For this you'll find a .pot file bundled with the plugin under the i18n folder that you can use to create your translation files. Check this handy guide for more details (skip Step 1 as you don't need to do that.)
When you're done, move the resulting .po and .mo files (eg. wordpress-popular-posts-es_ES.po and wordpress-popular-posts-es_ES.mo) into /wp-content/languages/plugins/ so the plugin picks up your translation.
If it fits the nature of my plugin and it sounds like something others would like to have then there's a pretty good chance that I will implement it (and if you can provide some sample code with useful comments that'd be awesome).
If the theme/plugin you're talking about is a free one that can be downloaded from somewhere then sure I can try it out and see what's going on.
Premium/paid themes/plugins are a different matter though. Testing compatibility with stuff that requires me having to buy a license is likely not going to happen unless: a) I already have a legal copy of said theme/plugin, or b) I have access to a valid license key so I can download a copy of said theme/plugin.
Updates will come depending on my work projects (I'm a full-time web developer) and the amount of time I have on my hands. Quick releases will happen only when/if critical bugs are spotted.
The Support Forum is usually the best way to get in touch with me for plugin related matters. I check it constantly so there's a good chance you'll get a reply from me within a few hours (except maybe during weekends and/or holidays.)