# Grav ReadingTime Plugin

**ReadingTime** is a [Grav](http://github.com/getgrav/grav) plugin which allows Grav to display the reading time of a page's content. This is especially useful for blogs and other sites as it gives the reader a quick idea of how much time they will need to set aside to read the page in full.

Enabling the plugin is very simple. Just install the plugin folder to `/user/plugins/` in your Grav install. By default, the plugin is enabled.

# Installation

To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the resulting folder to `readingtime`.

>> It is important that the folder be named `readingtime` as this is the folder referenced in the plugin's code.

The contents of the zipped folder should now be located in the `/your/site/grav/user/plugins/readingtime` directory.

>> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) plugins, and a theme to be installed in order to operate.

# Usage

### Initial Setup

Place the following line of code in the theme file you wish to add the ReadingTime plugin for:

```
{{ page.content|readingtime }}
```

You need to pass a Twig Filter 'readingtime' to display the reading time values. You can translate the labels with this example:

```
{{ page.content|readingtime({'minutes_label': 'Minuti', 'minute_label': 'Minuto', 'seconds_label': 'Secondi', 'second_label': 'Secondo'}) }}
```

I used Italian translation for the labels, you can change with your language.

If you need you can change the format with this avariable variables (the code is default format):

```
{{ page.content|readingtime({'format': '{minutes_short_count} {minutes_text}, {seconds_short_count} {seconds_text}'}) }}
```

Available variables:

|      Variable     |       Description       |                                   Example                                    |
| :---------------- | :---------------------- | :--------------------------------------------------------------------------- |
| `{minute_label}`  | Minute Label (Singular) | `minute`                                                                     |
| `{minutes_label}` | Minutes Label (Plural)  | `minutes`                                                                    |
| `{second_label}`  | Second Label (Singular) | `second`                                                                     |
| `{seconds_label}` | Second Label (Plural)   | `seconds`                                                                    |
| `{format}`        | Display Format          | `{minutes_text} {minutes_short_count}, {seconds_text} {seconds_short_count}` |

Not available to edit but used in the format variable:

|         Variable        |               Description                | Example |
| :---------------------- | :--------------------------------------- | :------ |
| `{minutes_short_count}` | Displays Minutes with Abbreviated Digits | `2`     |
| `{seconds_short_count}` | Displays Seconds with Abbreviated Digits | `9`     |
| `{minutes_long_count}`  | Displays Minutes in Double Digits        | `02`    |
| `{seconds_long_count}`  | Displays Seconds in Double Digits        | `09`    |

Display variables for text labels:

|     Variable     |                                   Description                                    |  Example  |
| :--------------- | :------------------------------------------------------------------------------- | :-------- |
| `{minutes_text}` | Displays the Minutes Text Label (Singular or Plural, Based on Number of Minutes) | `minute`  |
| `{seconds_text}` | Displays the Seconds Text Label (Singular or Plural, Based on Number of Seconds) | `seconds` |

>> NOTE: Any time you are making alterations to a theme's files, you will want to duplicate the theme folder in the `user/themes/` directory, rename it, and set the new name as your active theme. This will ensure that you don't lose your customizations in the event that a theme is updated. Once you have tested the change thoroughly, you can delete or back up that folder elsewhere.

### Include image views
The number of seconds to view images is added to the reading time of text when `include_image_views` is set to true.

Images are identified by `<img>` tags in `page.content()`.

The default values for `seconds_per_image` (shown below) mean that the first image adds `12` seconds to the reading time, the second adds `11` seconds, the third adds `10` seconds, and so on.
Only integers, whitespace, and commas are permitted in the string.

```
seconds_per_image: '12,11,10,9,8,7,6,5,4,3'
```

If there are more images in a page than what is defined in `seconds_per_image` (e.g., more than 10 images in the default shown above) then subsequent images take the last value (`3` seconds in the default shown above).

The example below adds `5` seconds reading time for all images.

```
seconds_per_image: 5
```