jQuery eTruncate

eTruncate is a jQuery plugin that easily allows you to hide/show some html elements like some paragraphs on long texts. It can be used as an easy way to improve user experience by hiding parts of long unconfortable lists and show them again with a click to provide more information only to those users who are really interested in reading your contents.

State of the art

eTruncate has been developed by Andrea Mangano and Luciano Mammino at ORYZONE for the ORYZONE website. It has been used to hide parts of some really long descriptions within their portfolio. ORYZONE want to share this plugin and make it open source because they truly believe that only by sharing our experiences we all can become better. So, please, don't hesitate to use the plugin, discover bugs and provide useful suggestions to make this plugin better and better.

Do you need to see before you believe?

Check out the demo page!

Usage

Like most of the jQuery plugins the usage is very simple. You should just have a jQuery selector and call the specific plugin function. In this case you should code something like the following prototype:

$(SELECTOR).eTruncate(OPTIONS);

For example, let's suppose you have a lot of paraghraps on the body of a web page and you want to show just the first one, hide the others and provide a button that allows you to show more/less paragraphs. You should do something like this:

HTML markup:

<body>
	<p>Hi this is the paraghraph number 1</p>
	<p class="more">this is the second</p>
	<p class="more">and then follows the last one!</p>
</body>

Javascript

$("body").eTruncate();

The SELECTOR, "body" in this case , is used to select a container (or a list of containers). The plugin will search inside each container for the elements to hide, hides them and creates a button to show them back again. By default it will search for all the elements with the "more" class placed inside the container. You can obviously customize the behaviour of the plugin by providing a structured options object.

Options

Follows a table that contains a list of all the available options:

Option	Default value	Description
elements	`".more"`	the selector that identifies the elements that will be hidden
createButton	`true`	a flag that indicates if a link button to show/hide the hidden elements should be created
buttonContainer	`null`	a selector that indicates where the show/hide button should be placed. If null, the button will be appended after the each hidden element
buttonCode	`'<span><a href="#"></a></span>'`	the html code used to create the show/hide button (the text will be placed inside the <a> tag)
showText	`"More"`	the text that will appear on the button used to show more text
showClass	`"show"`	the class attached to the button when it has to show more text
hideText	`"Less"`	the text that will appear on the button when it is used to hide text
hideClass	`"hide"`	the class attached to the button when it has to hide text
startStatus	`"hidden"`	the initial status of the exceeding text (use "hidden" if you want to hide it at onLoad or use "show" otherwise)

Accessing to the eTruncate object instance

After having initialized an eTruncate instance using a given selector you can access the related eTruncate object whenever you want. Basically the plugin works by attaching the generated eTruncate instance to the related DOM element by using the common jQuery .data() method. So you have basically two ways to access the object instance:

By reading the DOM element data
By using an alternative plugin instantion

Let's see a quick how-to. Suppose you've already instantiated eTruncate using the $("#container") selector:

$("#container").eTruncate();

If you prefer the first method you can simply check the data contained within the $("#container") selector:

$("#container").data("eTruncate"); // jQuery 1.2.3+

$("#container").data().eTruncate; // only for jQuery 1.4+

If you would like to use the second method you must call the plugin function as if you wanted to instantiate it, but by using the special string parameter "instance":

$("#container").eTruncate("instance");

Working programmatically with the eTruncate instance

Once you got the eTruncate instance you can operate programmatically with it by accessing all its public attributes and methods. For instance you can easily show, hide or toggle the connected DOM elements by calling respectively hideElements(), showElements() or toggleElements(). If you want to dive further read the complete api documentation.

Demos?

You'll find some more commented demos on the demos folder. Give them a look if you still want to see other ways to use this plugin.

Compatibility & Tests?

eTruncate has been developed for jQuery 1.4.3. It has been tested successfully on mac with Safari 5.0, Firefox 3.5, Chrome 7.0, Opera 10.6, Internet explorer (6, 7 and 8). Qunit tests are provided on the test folder. If you find some problems please open a new issue. Tnx!

Licensing

What the hell! This is not english! This is "Macaronic English" !!!

We, the developers, are both Italian guys. Our english knowledge is just "scholastic", so our english is really far from perfection. Please be quite if this document is not correct. We just hope that it's clear enough! If your english is better than ours (surely it is), please feel free to send us some suggestion to improve the whole plugin documentation: you'll be officially rewarded with a beer (maybe a virtual one, but that's just a detail :P).

Thank you for being interested on this project ! ;)

Oryzone/eTruncate