Other Projects

Documentation

Installation

  1. Download and install the Drupal Most Popular module.
  2. Download any service provider modules you wish to use.Typically, each of these has additional module requirements:
    • Drupal Service
      • Requires the Statistics module to be enabled and configured in order to collect metrics about page views.
    • Google Analytics Service
      • Requires the Google Analytics module in order to collect analytics info.
      • Requires the Google Analytics API module in order to connect with Google.
      • Requires the user running cron to have the 'administer Google Analytics settings' permission.
    • AddThis.com
      • Requires the AddThis module in order to add an AddThis widget on every page.
  3. Configure the Drupal Most Popular settings.
    • How many items to retrieve
    • Which domains and base URLs to include
    • Which intervals to use, which labels to display and in which order to display them
    • Which services to use, which labels to display and in which order to display them
    • Any service-specific settings, such as authentication credentials
    • How often to refresh data from the service
  4. Download the initial Drupal Most Popular data.
    • Go to the "Refresh Stats" tab
  5. Add the Drupal Most Popular block.
    • The block can be added in the usual way on the Block administration page.
    • No block-specific customizations are provided.  Instead, use the overall most popular configuration pages to control how the block looks.
  6. Verify that the Drupal cron job is being run regularly.
  7. Verify that you are receiving data.
    • At this point, assuming your services are configured correctly and, assuming your services are collecting analytics data, you should see it begin to appear in the Drupal Most Popular block.

Troubleshooting

If you don't see any results in the Most Popular block:

  1. Make sure to click on all of the service and interval tabs.
    • It's possible that although one service/interval might not have any data, others do.
  2. Make sure your services are collecting analytics data.
    • For the Drupal services:
      • Make sure there are comments posted.
      • Make sure you have viewed some nodes since the Statistics module was enabled.
    • For the Google Analytics service:
      • Make sure the Google page tracker appears on every page.
      • Make sure you've connected the page tracker to the correct profile.
      • Make sure you've viewed some pages since you enabled the page tracker.  Note that the Google Analytics service only counts node pages; any other types of pages are not included in the results.
      • GA does not report activity for today, so make sure that at least one day has elapsed since you started tracking page views.
      • Make sure you've given the cron user the 'administer Google Analytics settings' permission.  Despite what it's name might imply, you can safely give this permission to anonymous users.  See http://drupal.org/node/695480 for more info.
      • Check the log files on your site (admin/reports/dblog).  Every time the Google Analytics service runs, you will see a mostpopular_ga log message indicating which URLs were retrieved.  If any URLs appear here, the service is configured successfully.  This log will also show you which URLs map to nodes within Drupal; only these URLs are used.
    • For the AddThis.com service:
      • Make sure the AddThis widget is pointing to the same username and that the password is configured correctly.
      • Make sure you have used the service to email at least one page.
  3. Go to the services administration page.
    • If any of the services reports "OK", it has successfully received at least one most popular page since it was last configured.
    • If any of the services reports "Configured", it has not yet received any data since it was most recently configured. This could indicate a problem.
  4. Try to clear the caches and reset the services.
    • This will remove all the most popular items for the cache, and it will reset the values indicating the last time each service was run. This will force every service to run again the next time you click "Refresh stats".
    • Run "Refresh stats" and see whether each service is returning any values.
  5. Check the log files on your site (admin/reports/dblog).  
    • Make sure that cron is running periodically, and see what the results of the last Most Popular refresh are (which will appear as type mostpopular_cron).  
    • For Google Analytics, the list of results downloaded through the API will appear as type mostpopular_ga.  This can be extremely useful to see which URLs are included in the results and which aren't.

Included Services

Four services come pre-packaged with the Drupal Most Popular Module.  You can use any or all of these services, or create your own.

Each of the pre-packaged services retrieves a list of nodes and uses the Drupal Most Popular API functions to filter out any nodes to be excluded.  However, services could return other types of data instead, such as search terms or taxonomy keywords.

1. Drupal - Most Viewed

This module retrieves its list of the most commonly viewed nodes from the Statistics module, which updates a counter every time a page is viewed.  Unfortunately, no timestamp is stored for each page view, so it is not possible to see how many page views occured within a particular interval.

The Drupal Most Viewed module gets around this in the same way that the Hall of Fame (hof) module does: it produces a query for the number of times nodes were viewed that were published within the time interval.   This will work reliably in most cases, but it is unable to handle the case where traffic suddenly spikes on a story which was published in the past.   For example, a story published two weeks ago will never appear in the Most Viewed in the Past Week tab, even if it becomes the most popular page on the site.

To avoid this limitation, use the Google Analytics Most Viewed module instead.

2. Drupal - Most Commented

This module retrieves its list of the nodes with the most comments from a simple query to the database.  It counts the number of comments published within the given interval for every active node.

3. Google Analytics - Most Viewed

This module retrieves its list of the most popular pages by using the Google API to communicate with Google Analytics.  Any page with a Google Analytics tracking code can be retrieved.  The module uses Most Popular API functions to map the returned URLs to their associated nodes.  This allows the module to support multiple domains, filter out any nodes which should be excluded, and get an accurate titles for each node.

Google Analytics does not make data available until the next day, so when retrieving results for an interval of 24 hours or less, the query is modified to show the most recent interval for which data is available.   For example, at any time on Wednesday, the "Past 24 hours" tab would show results from Tuesday.  As a result, data from Google Analytics will not update throughout the day.

Keep in mind that the Google Analytics service only returns URLs that correspond to nodes on your system.  This means that homepages, views, etc will not be included.  This is usually the desired behavior, but if you are not getting any results, it may be why.

4. AddThis.com - Most Emailed

This module retrieves its list of the most popular pages to email to friends by using the Analytics API provided by AddThis.com.  Any page with an AddThis widget can be retrieved.  The module uses Most Popular API functions to map the returned URLs to their associated nodes.  This allows the module to support multiple domains, filter out any nodes which should be excluded, and an accurate titles for each node.

As of the time of this writing, the AddThis.com API only supports 3 intervals (day, week and month) and one sharing service (email).  The Most Emailed module attempts to map the configured list of intervals into one of the three supported by the AddThis.com API.  As a result, you may find you never get any results for a particular interval.

Assumptions

The Drupal Most Popular Module is configured in one place, and all of the data is normalized and stored in one place and displayed to any user where the block is enabled.  This should work well with most sites and is very efficient.  However, it is based on several assumptions:

1. Each site will need only one Drupal Most Popular block.

It is possible to place the Drupal Most Popular Block on a page more than once by altering the theme files, and in fact the Javascript will support this.  However, it is not possible to configure two Most Popular blocks independantly.  For example, it is not possible to configure one block to show only Most Viewed, and another block to show only Most Emailed and Most Commented.

2. There is no need to view more items than the block provides.

Each service retrieves only as many results as are specified in the configuration.  Therefore, it is not possible to provide a detailed page containing more most popular items.  The page of results displayed to non-javascript browsers still shows no more results than the block does.

3. No permission checking is necessary.

Each service retrieves a single list of results for each interval, which are cached by the Drupal Most Popular Module and displayed to every user regardless of their role.  As a result, a user may see a page in the Drupal Most Popular Block to which they don't have access, but they will still be unable to view the page if they click to it.

If your site has pages whose existance you wish to hide from certain users, you should exclude those pages from the Most Popular Module entirely, or disable the block for those users.

License

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 3 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 at http://www.gnu.org/licenses for more details.