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 part of long unconfortable list elements and show them again with a click to provide more information only to those users who are really interested on 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 part 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 became better. So, please, don't hesitate to use the plugin, discover bugs and provide useful suggestions to make this plugin better and better.
Usage
Like the most 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 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 on the button when used to show more text |
| showClass | "show" |
the class attached to the button when it has to show more text |
| hideText | "Less" |
the text on the button when 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 exceding 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 to 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 to 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 simple check the data contained within the $("#container") selector:
$("#container").data("eTruncate"); // jQuery 1.2.3+
or
$("#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 want 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 to 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().
A complete api documentation is provided into the docs/api folder.
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
Copyright ©2010 ORYZONE, released under MIT license.
What the hell! This is not english! This is "Macaroni English" !!!
We, the developers, are both Italian guys. Our english knowledge is just "scolastic", so our english is really far from perfection. Please be quite if this documents 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).
Thankyou for being interested on this project ! ;)