Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
212 lines (151 loc) · 4.66 KB

DOCUMENTATION.md

File metadata and controls

212 lines (151 loc) · 4.66 KB

Documentation

Installation

You can install the addon using composer:

composer require arthurperton/popular

To publish the config (optional) use:

php artisan vendor:publish --tag=popular-config

Setup

Basic setup requires one step: add the Popular Script Tag just before your </body> tag.

{{ popular_script }}
</body>

Popular will start tracking pageviews now. The total counts will be updated every minute.

Templating

There are two ways of display pageview counts on the frontend. You can use the computed field on your entries or try the dedicated tag.

Using the Computed Field

All entries have a computed field called pageviews containing the current pageview count for that entry.

<ol>
    {{ collection:blog limit="5" sort="pageviews:desc" }}
    <li>
        <a href="{{ url }}">
            {{ title }} ({{ pageviews }})
        </a>
    </li>
    {{ /collection:blog }}
</ol>

Using the Tag

Alternatively you can use the {{ pageview_count }} tag anywhere in your template. It will get the entry id from the context:

{{ pageview_count }}

Or you can provide it using a parameter:

{{ pageview_count id="home" }}

Using a variable:

{{ pageview_count :id="some_variable" }}

Shorten Modifier

Sometimes you want to display large numbers in a shortened format. So for example 25,314 becomes 25K. The shorten modifier does that for you.

{{ pageviews | shorten }}

Some examples:

dozen: 12
lots: 25314
omg: 9245021
{{ dozen | shorten }}
{{ lots | shorten }}
{{ omg | shorten }}
12
25K
9.2M

Static Caching

Popular was designed with static caching in mind. By simply using the {{ nocache }} tag you can combine fast page loads with current pageview counts.

Pageview Count Tag

Just wrap your {{ pageview_count }} tag in a {{ nocache }} tag:

{{ nocache }} {{ pageview_count }} {{ /nocache }}

Collection Tag

No need to wrap the entire collection tag pair. Instead just use the {{ pageview_count }} tag inside the loop and wrap that in a {{ nocache }} tag:

<ol>
    {{ collection:blog limit="5" sort="pageviews:desc" }}
    <li>
        <a href="{{ url }}">
            {{ title }} ({{ nocache }} {{ pageview_count }} {{ /nocache }})
        </a>
    </li>
    {{ /collection:blog }}
</ol>

Control Panel

A Pageviews field will be shown in your blueprints automatically.

Dashboard Widget

You can add the Popular widget to your dashboard, which is (almost) a drop-in replacement for the Collection widget:

// config/statamic/cp.php
 
'widgets' => [
    'getting_started',
    [ 
      'type' => 'popular',
      'collection' => 'blog',
      'limit' => 5,
    ], 
],

Permissions

Two permissions are added:

  • view pageviews
  • edit pageviews

Configuration

You can disable to pageview tracker if you want, for example in your local environment. Just put this in your .env file:

POPULAR_TRACKER_ENABLED=false

You can also opt-out of automatically adding the Pageviews field:

POPULAR_ADD_FIELD=false

All collections are tracked by default. To include or exclude certain collections, update the config file at config/popular.php:

return [
    'include_collections' => ['*'],
    'exclude_collections' => [],
];

Commands

If you want to reset all your pageview counts to zero in one go, you can use the php please popular:reset command in your CLI. Use it with care.

Git

You probably want your collected pageviews under version control. By default this file is at storage\popular\pageviews which is included normally.

Testing

You can try out Popular locally. A scheduled task runs every minute to update the total pageview counts, so make sure the scheduler is running. You can run it locally using php artisan schedule:work.

Popular does its best to count a pageview just once per user session. So during testing, be aware that slamming that refresh button won't increase your pageview counts :)

Enjoy the addon!