Getting Started Last updated: 2021-05-17

TooLooDR is a writing concept that you can read more about on its homepage. This documentation covers all the aspects of the TooLooDR.js as a standalone library and TooLooDR that comes as a WordPress plugin.

TooLooDR is available under the GPLv3 license.

Documentation is copyright © 2021 Marko Zivanovic.

Installation

You can get the latest version of TooLooDR.js from its homepage, or download them right here:

Download the compressed, production TooLooDR 1.0.2 - 6.7kB
Download the uncompressed, development TooLooDR 1.0.2 - 19.3kB

You will want to use the first one most of the time. Use the second one if you want to extend the library, or you run into some problems you may wish to debug.

Integration

TooLooDR.js can be integrated with plain JavaScript. The example below shows you how to load TooLooDR.js in your project.

Script Tag


    <script src="path/to/tooloodr/dist/TooLooDRJ.min.js"></script>
    <script>
        var myTooLooDR = new TooLooDR("#article", {...});
    </script>
									

Usage

TooLooDR.js can be used with plain JavaScript.

Creating a TooLooDR article

To create a TooLooDR article, we need to instantiate the TooLooDR class. To do this, we need to pass it the id of the div element in which our TooLooDR ready text resides. Here's an example.


    <div id="myArticle">
      <p>
        [tl1]This is the most important part of the article[tl2], followed by the less important part[/tl2].
        [tl3]Now I'm just giving some details that are for those who really want to know more.[/tl3][/tl1]
      </p>
    </div>
									

    var myTooLooDR = new TooLooDR("#myArticle");
		

This is the actual live output you're getting from the example above:

[tl1]This is the most important part of the article[tl2], followed by the less important part[/tl2]. [tl3]Now I'm just giving some details that are for those who really want to know more.[/tl3][/tl1]

This is the TooLooDR without any user configuration. Configuration options are mentioned in the next section.

Configuration

TooLooDR is built in a way that almost everything can be configured through the options object. Because the output is plain HTML, you can also always change things manually through HTML/CSS and JS.

The buttons and levels have distinct classes, so you can use those to manipulate TooLooDR even outside of the options object.

Here is the overview of all the options and their defaults, explained in detail in the following sections.

Name Type Default Description
defaultTooLooLevel number 2 Max level number of text to be shown by default
textHighlighting boolean true Should text have a text and a background color
buttonLabels.show boolean true Should button labels (eg. tldr1) be shown
buttonLabels.tooLoo1 string tldr1 Label of 1st level button
buttonLabels.tooLoo2 string tldr2 Label of 2nd level button
buttonLabels.tooLoo3 string tldr3 Label of 3rd level button
buttonColors.tooLoo1Text string #000 Color of the 1st level button text
buttonColors.tooLoo2Text string #000 Color of the 2nd level button text
buttonColors.tooLoo3Text string #000 Color of the 3rd level button text
buttonColors.tooLoo1Background string #ffaaa7 Background color of the 1st level button
buttonColors.tooLoo2Background string #ffd3b4 Background color of the 2nd level button
buttonColors.tooLoo3Background string #d5ecc2 Background color of the 3rd level button
buttonColors.activeBorderColor string #f00 Color of the active TooLooDR button's border
readingTime.show boolean true Show approx. reading time of the shown content
readingTime.wordsPerMin string 200 Reading speed (words per minute) to calculate reading time
readingTime.labelSeparator string Separator between button label and time string
readingTime.showPercentage boolean true Show percentage of the whole article contained in the level
readingTime.percentageSeparator string Separator between time string and percentage string
levelColors.tooLoo1Text string #000 Color of the 1st level text
levelColors.tooLoo2Text string #000 Color of the 2nd level text
levelColors.tooLoo3Text string #000 Color of the 3rd level text
levelColors.tooLoo1Background string #ffaaa7 Background color of the 3rd level text
levelColors.tooLoo2Background string #ffd3b4 Background color of the 3rd level text
levelColors.tooLoo3Background string #d5ecc2 Background color of the 3rd level text

  • defaultTooLooLevel - What TooLooDR level is shown to the reader on his visit
    • By default, the second level is shown. You can change it to any level you please. From one to three.

  • textHighlighting - Turns text highlighting on/off
    • Toggle the text highlighting. Setting this option to false is like setting all the text levels background color to transparent.

Buttons

We can see an example of buttons initiated with the default setting. Let's break down all the configurable options with which we can change the button's content and appearance.

By default, buttons are contained in a paragraph which will be rendered above your first content paragraph. The paragraph containing buttons has a class named tooloodr-buttons, so you can manipulate it with your own CSS.

  • buttonLabels.show - Should button labels (eg. tldr1) be shown
    • By default, buttons have tldr1-3 labels. By setting this option to false, you will hide the label completely. That way you can for example only show time and percentage inside of a button.

  • buttonLabels.tooLoo1, buttonLabels.tooLoo2, buttonLabels.tooLoo3 - Sets the labels of buttons
    • You might want to change the labels to something that makes more sense for the content you're writing. These are the settings where you can change it individually for every button.

  • buttonColors.tooLoo1Text, buttonColors.tooLoo2Text, buttonColors.tooLoo3Text - Sets the color of button's text
    • You can change the text color of each button with these settings. It makes it easy to align it with your design or custom background color you can also set.

  • buttonColors.tooLoo1Background, buttonColors.tooLoo2Background, buttonColors.tooLoo3Background - Sets the background color of buttons
    • Similar to the above, you can change the background color of each button with these settings.

  • buttonColors.activeBorderColor - Sets the color of active TooLooDR button's border
    • If the level's text is displayed, it's nice to signal to the user which levels are active. That's easily achieved with the button border. If you don't want the border, you can set it to transparent.

Example with user configured buttons

Let's take the previous container with our TooLooDR Text.


    <div id="buttonsExample">
      <p>
        [tl1]This is the most important part of the article[tl2], followed by the less important part[/tl2].
        [tl3]Now I'm just giving some details that are for those who really want to know more.[/tl3][/tl1]
      </p>
    </div>
									

For this example we want the following:

  • Buttons labels should be 'Level 1', 'Level 2' and 'Level 3' respectively.
  • Button 1 will have white text and black background.
  • Button 2 will have white text and blue background.
  • Button 3 will have red text and yellow background.
  • The color of the active border will be green.

We can achieve the above with the following instantiation of our TooLooDR class.


    var myTooLooDR = new TooLooDR("#buttonsExample", {
        buttonLabels: {
            show: true,
            tooLoo1: 'Level 1',
            tooLoo2: 'Level 2',
            tooLoo3: 'Level 3',
        },
        buttonColors: {
            tooLoo1Text: 'white', // you can use either CSS color names or hex codes
            tooLoo2Text: 'white',
            tooLoo3Text: 'red',
            tooLoo1Background: 'black',
            tooLoo2Background: 'blue',
            tooLoo3Background: 'yellow',
            activeBorderColor: 'green',
        },
    });

You can see it in action here.

Levels

Levels refer to parts of the content transformed by TooLooDR. Everything surrounded with [tl1] tags is level 1, everything surrounded with [tl2] is level 2 and everything surrounded with [tl3] tags is level 3.

  • levelColors.tooLoo1Text, levelColors.tooLoo2Text, levelColors.tooLoo3Text - Sets the color of TooLooDR text levels
    • You can change the text color of each level by changing these settings.

  • levelColors.tooLoo1Background, levelColors.tooLoo2Background, levelColors.tooLoo3Background - Sets the background color of the button's text
    • You can change the text background color of each level by changing these settings. By default, levels have a different background to show the distinction between them, but you might want to change that to the most common white - ending up with black text on the white background.

Example with user configured levels

Let's take the previous container with our TooLooDR Text.


    <div id="levelsExample">
      <p>
        [tl1]This is the most important part of the article[tl2], followed by the less important part[/tl2].
        [tl3]Now I'm just giving some details that are for those who really want to know more.[/tl3][/tl1]
      </p>
    </div>
									

For this example we want the following:

  • All TooLooDR levels will have dark blue text color.
  • All TooLooDR levels will have a white background.

We can achieve the above with the following instantiation of our TooLooDR class.


    var myTooLooDR = new TooLooDR("#levelsExample", {
        levelColors: {
            tooLoo1Text: '#00008b',
            tooLoo2Text: '#00008b',
            tooLoo3Text: '#00008b',
            tooLoo1Background: '#fff',
            tooLoo2Background: '#fff',
            tooLoo3Background: '#fff',
        },
    });

You can see it in action here.

Reading Time

TooLooDR calculates the approximate time it takes for an average person to read the article. You can show it, or disable it, but displaying it to the reader might be beneficial. That way the reader can decide which length suits them the most.

  • readingTime.show - Shows or hides reading time and percentage
    • Setting this to false will hide both reading time and percentage. Careful, if this is set to false and button text is set to false, you will end up with buttons without any description. That might confuse your readers.

  • readingTime.wordsPerMin - Sets the reading speed (words per minute) to calculate the reading time
    • According to this research, it seems sensible to put the average reading speed to 200 words per minute. Depending on your audience, you might want to change that number. That's what this setting does.

  • readingTime.labelSeparator - Sets the separator between button label and time string
    • You can use whatever string here as a separator between the button label and calculated time.

  • readingTime.showPercentage - Shows the percentage of the whole article contained in the level
    • This will display how much percent of the whole article each level is.

  • readingTime.percentageSeparator - Sets the separator between time string and percentage string
    • If the percentage is shown, with this setting you can use whatever string you like for the separator between the time string and the percentage string.

Example with user configured reading time

Let's take the previous container with our TooLooDR Text.


    <div id="timeExample">
      <p>
        [tl1]This is the most important part of the article[tl2], followed by the less important part[/tl2].
        [tl3]Now I'm just giving some details that are for those who really want to know more.[/tl3][/tl1]
      </p>
    </div>
									

For this example we want the following:

  • Reading speed should be 10 words per minute.
  • The separator between button label and time should be a plus sign.
  • The separator between time and percentage should be a minus sign.

We can achieve the above with the following instantiation of our TooLooDR class.


    var myTooLooDR = new TooLooDR("#timeExample", {
        readingTime: {
            wordsPerMin: 10,
            labelSeparator: ' + ',
            percentageSeparator: ' - ',
        },
    });

You can see it in action here.

Writing the TooLooDR Way

There's no right way or wrong way to structure your content when writing a TooLooDR article, except some rules you can read below. However, when I came up with the idea, I also came up with a set of guidelines and rules that I thought would help me explain the concept better. You're free to ignore it, but here it is - it might prove to be useful to you.

Rules

These are the rules you have to follow for TooLooDR to work.

I'm working on making it less error-prone and more flexible, but these are the current constraints.

  • TooLooDR text must be enclosed in [tl1][/tl1] tags. That means your text must start and end with this tag.
  • All opened tags must have a closing tag. If you've opened eg. [tl2] tag, and it's not closed anywhere, it will result in errors.

General Guidelines

Take a look at this TooLooDR demo. The content of the example article is irrelevant. When I started to play with TooLooDR, I just needed something as an example, so I took one of the blog posts I wrote.

I didn’t change the text at all so it fits better into the TooLooDR. I wanted to prove that we can apply this concept even to the text that wasn’t written with it in mind (let’s call that kind of text – TooLooDR non-friendly text). You can see the original blog post here.

Having said that, there are a few things you can do when writing a TooLooDR text to make it easier to enclose parts of the content with the TooLooDR tags.

  • Keep attention to punctuation. Take care of spacings, and make sure that the flow of sentences is good with any level shown.
  • Rather than having big blocks of text as different levels, implement TooLooDR in a way where different levels are intertwined. That way, we can better present the progressive nature of the TooLooDR article.
  • Lengthiness-wise, my opinion is that percentage articles per level are around 30% for tl1 and 60% for tl2. If the difference between levels is too small, you might want to rethink how you structured the article.

Levels Explained

Level 1

Level 1 offers a bare-bones, fully stripped-down version of the article - a modern equivalent of telegram-style writing.

Level 2

Level 2 is the golden middle. It expands the dry and lifeless sentences of level 1 to a richer form, adding adjectives and adverbs. It also adds additional information to back up the claims made at the level below.

Level 3

Level 3 is your all-you-can-eat buffet of detail. This level is for those invested in the topic. It’s intended to display background information, low-level detail, everything that you as an author wanted to put in your article, but thought it would be too much.

TooLooDR for WordPress

TooLooDR for WordPress is a simple plugin that works with the help of shortcodes. The concept of writing is the same, but you don't have to care about including the JS library, changing the configuration through code, etc.

You don't have to have any technical background to be able to work with TooLooDR in WordPress. There are only some requirements to satisfy.

  • Your WordPress version is 4.7 or higher.
  • You have the WordPress Classic Editor plugin installed and activated.
  • You have the WordPressTooLooDR plugin installed and activated.

We will go through those steps quickly in the following sections.

Installation

Thank you for purchasing TooLooDR for WordPress! You are making the continuation of work on this concept possible!

Once your payment goes through, you are presented with a download link. If you miss it by any chance, don't worry. You will receive an email with the purchase confirmation and the download link. From there, you can also generate an invoice if needed.

The download is a zip file that will be named something like this: tooloodr-v1.0.2.zip Your version might differ, based on the time you purchased the plugin. This zip file is a ready, valid WordPress plugin.

To install it, log into your WordPress admin dashboard, and click on "Plugins" in the left side navigation. You will see the "upload plugin" button next to the heading that says "Add Plugins". Clicking on that button will present you with an upload form (see picture below).

Click on browse, and locate the downloaded TooLooDR ZIP file you've downloaded.

This should only take a moment, after which you will be presented with a button to activate the plugin.

Click on "Active Plugin", and that's it! Welcome to the world of TooLooDR!

Settings

After you install the plugin, the TooLooDR link will appear in the left sidebar of your WordPress admin dashboard.

Here, all in one place, you have all the configuration options for TooLooDR at your hand.

As you can see from the pictures below, the settings page is divided into 4 parts:

  1. General Settings - check all possible options and detailed explanation here.
  2. Button Settings - check all possible options and detailed explanation here.
  3. Reading Settings - check all possible options and detailed explanation here.
  4. Level Settings - check all possible options and detailed explanation here.

Everything valid for TooLooDR standalone script is also valid for this plugin.

Usage & Misc

Usage

Read the TooLooDR Writing Guidelines (especially rules). All the rules that are written in that section also apply here.

The only addition to the WordPress plugin is adding a [tooloodr] tag at the bottom of your WordPress post. See the example in the picture below.

The resulting post will look like the picture below. I used a new WordPress installation with its default theme for this example.

Misc

When I was writing the above example, I've noticed that the new default WordPress theme has unusually large buttons, so TooLooDR buttons were that same size.

You can easily change that by adding some simple CSS to your theme's style.css. Buttons containing paragraph has a class "tooloodr-buttons". Your added CSS would look something like this.


    .tooloodr-buttons button {
        padding: 10px;
        font-size: 18px;
    }
	

FAQ

General FAQ

How to contact the author?

You can write me an email to marko[at]markozivanovic.com. I will usually respond in a day, but it might take longer if it's weekend.

Wordpress FAQ

X/Y/Z is not working for me. What should I do?

There are so many combinations of different plugins and themes and who knows what else for WordPress, so it can happen that TooLooDR may not work.

If that's the case, I would really appreciate it if you would contact me and tell me what the problem is. That way I can possibly fix it for you and the others that might experience the same problem.

Which version of WordPress was the plugin tested on?

I have tested the plugin on several versions of WordPress from version 4.7 up to the newest one. It was tested both on freshly installed WordPress and on several instances that are running for some time.

How will I get the new updates?

You will be notified by email when the new update is out, and you will be able to download it. I'm currently looking into an option to implement the auto-update for the plugin.

You can also check out the roadmap to see what's currently being worked on.

I bought the plugin and I hate it. Can I get a refund?

I'm sorry to hear that. I would appreciate it if you told me what the problem is, so maybe I can fix it for everyone out there. If not, that's fine. Send me an email and you'll get a refund.

Roadmap

While the idea is simple, there are lots of things that could be built around it. Also, when working with an unknown input, many things can, and usually do go wrong.

I came up with several improvements and features that I would like to implement for the next version. You can see the things that are in the current pipeline below. That means they are actively being worked on.

I will update this section as the development progresses.

If you have any ideas for new features, or you think something should be fixed, please send me an email to marko[at]markozivanovic.com.

General

  • Friendly alerts to users about possible unclosed tags - with displaying character number where the error is or similar.
  • Make TooLooDR more resilient - eg. circumvent and problematic HTML elements that might be thrown in the middle of the text etc.

WordPress

All features and fixes in the section above will also apply to the WordPress plugin updates.

  • Make TooLooDR work with the Gutenberg editor.
  • Add logic to track stats on how many people read each TooLooDR level.