jQuery.howmuchread

Answers your fancy questions such as
“How many characters I scrolled?”

Have you ever been in the situation that you need to know the characters you scrolled, or to scroll into the place of specific character? jQuery.howmuchread is here for you!

jQuery.howmuchread is a fancy jQuery plugin that plays with “scrolling” and “counting characters.” It can serve as a great reading counter (as its name implies), reading position indicator or somewhat neat page scroller!

jQuery.howmuchread is powered by the power of the powerful binary search algorithm, so you can find the character of the specific position precisely, and also very quickly.

• Fully customizable options
• RTL & Vertical writing-modes are supported

Download the script and include it, along with jQuery.

<script src="path/to/jquery.min.js"></script>
<script src="path/to/jquery.howmuchread.min.js"></script>
<script>
	$('article').howmuchread();
</script>

Bower components are also available.

$ bower install jquery.howmuchread

As you may noticed, whole this page is a demonstration of this plugin.

Get the count of characters you scrolled, indicated by the scroll position of the element.

Options

Options have to be passed as object, and following keys are available.

parent

(Default: self element) The element or anything that can be passed to jQuery object that will be the basis of scrolling. In other word, parent element is your “scroll area” of the target element.

borderline

(Default: 'before') String or number that determines the position where to be guessed as scrolled.

If set to 'before', character will be guessed as scrolled when it completely passes the scroll area over.

If set to 'center', character will be guessed as scrolled when it passes the center line of the scroll area.

If set to 'after', character will be guessed as scrolled when it appears in the scroll area.

If set to 'scroll', character will be guessed as scrolled by the scroll ratio of the parent element. (See this page's demo)

If set to number, character will be guessed as scrolled when it passes the line of the ratio you specified. (If set to 0, it's equivalent to 'before'.)

baseline

(Default: 'before') String or number that determines the position of the character where the character is guessed as scrolled.

If set to 'before', character will be guessed as scrolled when its top line passes the borderline over.

If set to 'center', character will be guessed as scrolled when its center line passes the borderline over.

If set to 'after', character will be guessed as scrolled when its bottom line passes the borderline over.

If set to number, character will be guessed as scrolled when its line of the ratio you specified from the top line. (If set to 0, it's equivalent to 'before'.)

wrapperId

(Default: 'howmuchread-wrapper') The string used for the id of the wrapper element. jQuery.howmuchread wraps some characters to test their position, and unwraps it immediately. Just set this parameter to avoid id conflict with your existing webpage.

getMetric

(Default: false) The boolean. If set to true, instead of returning the count of characters, this method returns the metric information of the first character guessed as “not scrolled”. Returned object at least contains following information.

top

Distance from the top of the document

left

Distance from the left of the document

right

Distance from the right of the document

bottom

Distance from the bottom of the document

width

Width of the character

height

Height of the character

position

The count of characters which is normaly returned by the method

Example

// used in this page
var metrics = $('.bodytext').howmuchread({
	parent: window,
	borderline: 'scroll',
	baseline: 'after',
	getMetric: true
});

Returns the element's full character count which is compatible with jQuery.howmuchread()

Scroll the parent element to the count-th character exists.

Options

The same options with .howmuchread() and some additionals are available.

noScroll

(Default: false) Set true not to actually perform scroll, just simulate. Much like good if combined with getMetric option.

Example

// Scroll window to the 1000th character of the document
$('body').howmuchread('scrollTo', 1000, {
	parent: window
});

MIT License © Koki Takahashi

Any contributions are very welcomed!