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"

• wpm="150" If you would like to adjust the words per minute used in the calculation add the wpm parameter. (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}

The finished_ prefix variables will not work when used inside of a Grid > Relationship field tag, e.g.{grid_field:relationship_field:finished_reading_time}.

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}

Hidden config

Reading Time Pro has a hidden config value, that when added to your config.php file, and combined with the calculate_reading_time="yes" parameter, will always re-calculate the reading time of an entry and save the value to the custom field. Part of the advantage of using Reading Time Pro is that the calculated reading time is saved to the database for optimal performance, and subsequent views of the entry will not require a re-calculation. Using this option means that a database query will be executed every time the entry is displayed in the {exp:channel:entries} tag. Generally you would wait for an entry to be saved, which will clear the reading time, or remove the reading time in the module settings page, however, you can use this hidden setting to bypass those two methods of resetting the reading time values.

$config['rtp_always_calculate'] = 'y';