Text Readability

[Robin S]

Text Readability

A module that uses the PHP Text Statistics class to evaluate the readability of English text in textarea fields according to various tests.

The available readability tests are:

• Flesch Kincaid Reading Ease
• Flesch Kincaid Grade Level
• Gunning Fog Index
• SMOG Index
• Automated Reability Index
• Spache Readability Score
• Dale Chall Readability Score
• Coleman Liau Index

The results of the enabled tests are displayed at the bottom of textarea fields – either when the "book" header icon is clicked, or at all times, depending on the option selected in the module configuration. An interpretive tooltip appears when you hover any of the result values.

Requires ProcessWire >= 3.0.246 and PHP >= 7.2.0

Why is readability important?

---

Readable.com says:

Readability is partly important because Google considers it a key ranking factor. This is based on human behaviour on websites. If the average person finds website content too difficult to read, they’ll click elsewhere. Google loves readability because it improves UX. Content which is easier to understand will be easier to navigate. This will encourage readers to stay on your page. Which, in turn, improves bounce rates.

And:

A good score to work for, for the public, is a Flesch Kincaid grade level of 8. This is adequate for 85% of the public to easily understand.

The Wikipedia article on readability has useful information too.

Module configuration

---

• Select which readability tests you want to enable. For each test there is an "about" link to information about the test.
• Select whether the results of the enabled readability tests should be shown only when the header action icon is clicked (default), or if the results should always be shown.
• For multi-language sites, select which ProcessWire language represents English (as the tests are only intended for English text).

Advanced

---

If you want to disable the readability test results for a particular textarea field you can hook TextReadability::allowReadabilityResults. Example:

$wire->addHookAfter('TextReadability::allowReadabilityResults', function(HookEvent $event) {
    $field = $event->arguments(0);
    $page = $event->arguments(1);
    // Disable readability results for the "body" field on the "home" page
    if($field->name === 'body' && $page->template == 'home') $event->return = false;
});

 

https://github.com/Toutouwai/TextReadability
https://processwire.com/modules/text-readability/

[adrian]

Hey @Robin S - this is really useful, thank you as always.

A couple of thoughts.

Would you mind passing the text through Hanna first. I have a lot of tags in some content and readability is very poor unless I add this to your module.

        $hanna = $this->wire('modules')->get('TextFormatterHannaCode');
        $text = $hanna->render($text);

What do you think about adding some easy way to identify if each of the scores is good or not - at the moment you have to look up the docs, but perhaps color coding the values (red, orange, green) or some other way would help to alert us to issues.

Thanks again!

[adrian]

And/or maybe a hover tooltip that shows some more info about each particular score, eg if the Automated Readability Score is 5, then the tooltip would display:

Age: 1-18
Grade Level: 5th

If you want some help setting this up, I'd be happy to create some JSON that contained all this info for all the scores that your module could parse.

Actually, ChatPT to the rescue. This prompt "Automated Readability Index JSON of scores to ages and grades" returns:

{
  "0": { "grade": "Kindergarten", "ages": "5-6" },
  "1": { "grade": "1st Grade", "ages": "6-7" },
  "2": { "grade": "2nd Grade", "ages": "7-8" },
  "3": { "grade": "3rd Grade", "ages": "8-9" },
  "4": { "grade": "4th Grade", "ages": "9-10" },
  "5": { "grade": "5th Grade", "ages": "10-11" },
  "6": { "grade": "6th Grade", "ages": "11-12" },
  "7": { "grade": "7th Grade", "ages": "12-13" },
  "8": { "grade": "8th Grade", "ages": "13-14" },
  "9": { "grade": "9th Grade (Freshman)", "ages": "14-15" },
  "10": { "grade": "10th Grade (Sophomore)", "ages": "15-16" },
  "11": { "grade": "11th Grade (Junior)", "ages": "16-17" },
  "12": { "grade": "12th Grade (Senior)", "ages": "17-18" },
  "13": { "grade": "College Freshman", "ages": "18-19" },
  "14": { "grade": "College Sophomore", "ages": "19-20" },
  "15": { "grade": "College Junior", "ages": "20-21" },
  "16": { "grade": "College Senior", "ages": "21-22" },
  "17": { "grade": "Graduate Level", "ages": "22+" },
  "18": { "grade": "Graduate Level", "ages": "22+" },
  "19": { "grade": "Professional Level", "ages": "22+" },
  "20": { "grade": "Professional Level", "ages": "22+" }
}

So it should be easy to do the same for all the other indices.

[Robin S]

@adrian, I've added most of your requests in v0.1.1. But not the colour-coding because the results don't fall into universal good or bad categories - it depends on the intended audience, e.g. you would expect a high grade level on a website for an academic journal.

[adrian]

Thanks @Robin S - good point on the color coding. Thank you for the formatted content fix and a great implementation of the tooltip info. Much appreciated as always.

[adrian]

@Robin S - I just did a little bit of testing between various online Flesch Kincaid Reading Ease calculators and the same text resulted in very different "reading ease" scores.

Your module - 52.5
https://serpninja.io/tools/flesch-kincaid-calculator/ - 37.85
https://hemingwayapp.com/articles/readability/flesch-kincaid-readability-test - 50
https://goodcalculators.com/flesch-kincaid-calculator/ - 46.8
https://charactercalculator.com/flesch-reading-ease/ - 43.16
https://codebeautify.org/flesch-kincaid-grade-level-calculator - 31.9
https://app.readable.com/text/?demo - 50.4
ChatGTP - 47.2

ChatGPT also tells me that the reason for the differences I am seeing is due to the counting of syllables and sentence boundaries, etc so I guess the key thing is getting used to what your module returns and compare relatively with other field content on the site.

One thing I didn't understand though is why the readable.com demo wasn't returning the same score as your module given that https://github.com/DaveChild/Text-Statistics?tab=readme-ov-file#useful-links links directly to it as a demo of it in action. But looking into it, I realized that when I was pasting the text into these calculators, it was just text and not the HTML that is part of RTE field content. So, I added $text = strip_tags($text) and now I get the same 50.4 that the demo on readable.com does.

Do you think it makes sense to add that?

[Robin S]

6 minutes ago, adrian said:

So, I added $text = strip_tags($text) and now I get the same 50.4 that the demo on readable.com does.

Do you think it makes sense to add that?

Good idea, I've done that in v0.1.2

[adrian]

Sorry, now I am seeing: Deprecated: strip_tags(): Passing null to parameter #1 ($string) of type string is deprecated

I guess it needs to be after: if(!$text) return;

 

[Robin S]

45 minutes ago, adrian said:

Sorry, now I am seeing: Deprecated: strip_tags(): Passing null to parameter #1 ($string) of type string is deprecated

I'm surprised a textarea field value can be null rather than an empty string. Maybe something to do with multi-language.

I'm casting $text to string in v0.1.3 so hopefully fixed. Thanks for the report.

[adrian]

Yeah, actually that is a better approach - I was actually just falling asleep and realized that there is the possibility of an RTE with something like empty <p> </p> tags so you definitely want to strip those before checking !$text