README

This Craft plugin provides Twig functions to display information about your texts. It allows you to measure the readability of your content, calculate the average reading time or access other text statistics like sentence count.

Installation

The plugin is available on Packagist and can be installed using Composer. You can also download the latest release and copy the files into craft/plugins/textstatistics/.

$ composer require carlcs/craft-textstatistics

Settings

The plugin can be configured with a craft/config/textstatistics.php config file to set the default template used to render the reading time string and to set a default words per minute value.

TextStatisticsModel

When you generate text statistics using the getTextStatistics function the plugin returns a TextStatisticsModel with the following properties populated. Most of the data is calculated with the excellent Text Statistics library by Dave Child. For information about the provided readability scores have a look these Wikipedia articles:

Properties

textLength
letterCount
syllableCount
wordCount
sentenceCount
readingTime
readingTimeMinutes
readingTimeString
gunningFog
fleschKincaid

Templating Examples

A single article

{% do addToTextStatistics(entry.text) %}

{% set statistics = getTextStatistics() %}
{{ statistics.readingTimeString }}

{# outputs "21 minutes" #}

Adjust WPM according to text language

{% set wpm = {
    'en': 200,
    'fr': 180,
} %}

{% set statistics = getTextStatistics(null, wpm[craft.locale]) %}
{{ statistics.readingTimeString }}

{# outputs "moins de 5 minutes" #}

Usage with a Matrix field

{% for block in entry.article %}

    {% if block.type == 'text' %}
        {% do addToTextStatistics(block.text) %}
        {{ block.text }}
    {% endif %}

    {% if block.type == 'image' %}
        {% set image = block.image.first() %}
        {% if image %}
            {% do addToReadingTime(10) %}
            <img src="{{ image.getUrl() }}" alt="{{ image.title }}">
        {% endif %}
    {% endif %}

{% endfor %}

{% set statistics = getTextStatistics() %}

Twig functions

addToTextStatistics( text, articleId )

Adds text to the data storage so you can later perform text statistics calculations from it.

text (required) – The text to add to the data storage for text statistics. It can contain HTML tags, the plugin removes them before doing its calculations.
articleId (default '') – An ID to identify the article. Only required if you have multiple articles for text statistics on the same page.

{% do addToTextStatistics(entry.myRichTextField) %}

Alternativly you can use the Twig filter.

{{ entry.myRichTextField|addToTextStatistics }}

addToReadingTime( seconds, articleId )

Adds time to the data storage to further influence the reading time returned with the text statistics.

seconds (required) – Time in seconds to add to the data storage for text statistics.
articleId (default '') – An ID to identify the article. Only required if you have multiple articles for text statistics on the same page.

{% do addToReadingTime(15) %}

getTextStatistics( articleId, wpm, readingTimeTemplate )

Performs the text statistics calculations for an article and returns the result as a TextStatisticsModel.

articleId (default '') – An ID to identify the article. Only required if you have multiple articles for text statistics on the same page.
wpm (default 200) – The average reading speed used for the reading time calculations in words per minute units.
readingTimeTemplate (default ) – The Twig template code used to render for the reading time string.

{% set statistics = getTextStatistics() %}
{{ statistics.gunningFog }}

{# outputs "12.1" #}

Requirements

PHP 5.4+

carlcs / craft-textstatistics

Maintainers

Details