Template Tags

{exp:channel:entries} tag parameters

To calculate the reading time, add the following parameter to the {exp:channel:entries} tag which renders the full content of your entry:

calculate_reading_time="yes"

If you would like to adjust the words per minute used in the calculation add the wpm parameter:

wpm="150" (optional, default is 200)

There will be 2 variables available within the {exp:channel:entries} tag. Just like any other custom field added to an ExpressionEngine channel, it will be available with the name you assigned it, and it will display the total seconds of the calculated reading time:

{reading_time}

or if you used a different field name:

{name_of_your_field_here}

Reading Time Pro will also set another variable with the prefix finished_ that will display user friendly text such as in 10 minutes or less than 1 minute. You can optionally add a format parameter format="%H:%i:%s" to change the display of the reading time.

{finished_reading_time:relative}

or if you used a different field name:

{finished_name_of_your_field_here:relative}

'Cache warming'

If the entry you are saving is managed by the Structure or native Pages module, or the channel is configured with a Live Preview URL, Reading Time Pro will attempt to reset the saved reading time value. This is especially helpful if you are displaying the reading time with one of the variables above in a summary view of the entry before the full content of the entry is rendered on the front-end to a regular site visitor.

Template Examples

If your entry detail template contains the full text of your entry, your entries tag may look something like this.

{exp:channel:entries channel="blog" calculate_reading_time="yes" wpm="150" limit="1"}
    {title}
    {reading_time}
    {finished_reading_time:relative}
{/exp:channel:entries}

And your entry listing template may look like this since you want to display the already calculated time.

{exp:channel:entries channel="blog" limit="20"}
    {title}
    {reading_time}
    {finished_reading_time:relative}
{/exp:channel:entries}

You can also sort and search your entries by reading time.

{exp:channel:entries channel="blog" search:reading_time="> 120" orderby="reading_time" sort="desc"}
    ...
{/exp:channel:entries}

Customize :relative display

If you do not like the display text when using {finished_reading_time:relative} you will need to update or create a local core_lang.php file to override the default display from ExpresssionEngine.

In your user/language folder create an english (or whatever languages your site has) folder with a new file called core_lang.php, e.g. user/language/english/core_lang.php. Insert the following code into that file, then it should change how :relative text is displayed.

<?php  if ( !defined('BASEPATH')) exit('No direct script access allowed');

$lang = [
    'future' => 'whatever you want %s.',
];

Displaying total reading time

You can also use the following variables outside of an {exp:channel:entries} tag to display the total calculated reading time of all entries listed. This only works if the template contains 1 or more {exp:channel:entries} tags that contain a Reading Time Pro custom field that contain calculated values.

{total_reading_time}
{total_finished_reading_time:relative}

Usage outside of {exp:channel:entries} tags

If you want to use Reading Time Pro anywhere on your site other than inside of a {exp:channel:entries} tag, just use the module tag around your content. Using this tag will not save the calculated reading time to the database, it will be calculatd every page load.

Note that the same tag parameters reading_time_field and wpm parameters are supported, but both are optional when using the module tag. The variables will default to {reading_time} and {finished_reading_time:relative} unless otherwise defined.

{exp:reading_time_pro}
    ... Custom content ...
    {reading_time}
    {finished_reading_time:relative}
    ... More custom content ...
{/exp:reading_time_pro}