Introduction

Current version: 1.4.1

This simple plugin allows you to get approximate statistics on the lines in a textarea. It's useful for, as an example, creating an auto-expanding textarea.

Building

If you want to build the files yourself, follow these instructions:

1. Install Node.js.
2. Install Grunt by opening a command line and typing: npm -g install grunt
3. Download the Textarea Line Count source by either cloning this repository, or downloading a zip/tar file. See the Downloads tab above.
4. Open a command line, point it to the root directory of the source (the folder containing grunt.js, and invoke grunt. On Windows, this means typing grunt.cmd. On other platforms, type grunt.
5. The normal and minified versions will be written to the dist folder.

If any errors occur during the build process (for example, if lint throws a warning/error), please comment on my blog or open a new ticket.

License

This project is under an MIT license.

Basic usage

Example:

var result = $.countLines("#textarea");

The selector you pass to the function must only select a single textarea. result will now contain five useful statistics:

• result.actual: The number of lines in the textarea. No wrapping detection is used for this statistic.
• result.wrapped: The number of lines in the textarea that wrap at least once. A line that spans three lines (visually) will only count as one wrapped line.
• result.wraps: The total number of times all lines wrap. If a textarea contains two lines: one that spans two lines (visually) and one that spans three lines (visually), this statistic will report 3. This is because the first line wraps once, but the second line wraps twice. Note: This statistic is usually correct. It is only ever off by 1 or 2 (explained below).
• result.visual: The approximate number of lines that the user actually sees in the textarea. Note: This statistic is usually correct. It is only ever off by 1 or 2 (explained below).
• result.blank: The number of blank lines.

Advanced usage

You can pass either a selector or a jQuery object to the function. So:

var result = $.countLines("#textarea");

is equivalent to:

var result = $.countLines($("#textarea"));

Plugin options

To pass options to the plugin, call it like this:

var result = $.countLines("#textarea", {*options go here*});

There are four options you can modify to customize the functionality of the plugin.

• recalculateCharWidth: When you first call the plugin, the average width of a character in the textarea is calculated and stored using $.data on the element. This average is used to calculate lines of text. If you plan on changing font attributes (face, size, etc.) between calls to the plugin, set this option to true.
• charsMode: To calculate the average character width of a character in the textarea, a handful of characters are measured. This property changes where the plugin gets this sample of characters from. There are five possible settings:
  1. random: Takes 12 random alphanumeric characters and/or punctuation. This is the default.
  2. alpha: Use all alphanumeric characters
  3. alpha_extended: Use alphanumeric characters, plus some punctuation
  4. from_ta: Use 15 random characters from the textarea itself. If there are not at least 15 characters available, it defaults to alpha mode
  5. custom: Use a list of characters you define yourself. You define these characters using the chars property, detailed below.

• chars: If charsMode is set to custom, this is the property that defines the custom characters you want to use to calculate the average character width with. The default property is the uppercase and lowercase alphabet, and numbers 0-9. For this property, you can use a string of characters, such as "abcdef", or an array like ["a", "b", "c", "d", "e", "f"]
• fontAttrs: To clone the textarea (for the purpose of finding the average character width), this plugin must have a set of attributes to clone. This property is a list of attributes to clone. The default is ["font-family", "font-size", "text-decoration", "font-style", "font-weight"]. To override these attributes, set fontAttrs to an array of the attributes of your choosing. The attributes you provide replace the default attributes, as opposed to extending them.

About accuracy

The biggest challenge I faced while writing this plugin was balancing accuracy with complexity. Because it is hard to accurately detect how many times a line wraps, the result.wraps and result.visual statistics will be off from time to time (see above for what these mean.) However, they will only ever be off by about 1 or 2 lines. Hopefully no one is planning on using this plugin in an application that requires absolute accuracy, or else they will be disappointed.