a jQuery plugin for HTML truncation and toggling
View this project on Github Pages
- Server-side text truncation based on character counts is always incorrect. The width of the character string "iiiii" is approximately 58% less than the width of "MMMMM" unless a monospace font is used.
- The CSS3 property "text-overflow" can only truncate a single line of text, and is not supported by IE7 and below.
- HTML truncation to a specified number of lines, including HTML that wraps around other floated elements.
- Deep-HTML truncation with preservation of all non-type3 (text) nodes
- Optional specification of a truncation suffix, e.g. …
- Toggling between truncated and un-truncated states with configurable hyperlink text
- Triggered events when the truncated state of the HTML is changed
- O(log n) execution time for n := text length
- Pre-truncation and re-truncation analyses are both performed on cloned elements to minimize DOM flicker
- Optional console logging of execution time and number of steps for performance analysis
- Ability to merge modifications to truncated HTML back into the original HTML
Invocation
$('.selector').truncate(options);
Event Binding (after invocation)
$('.selector').truncate('bind', 'show', function(){
// do something when full text is shown
});
Events are triggered on the following state changes of the selected element. No events are triggered on the initial invocation of the truncate plugin.
show Triggered when full text is shown. If options.animate is specified to be true, then this event will fire after the animation has completed.
hide Triggered when full text is truncated. If options.animate is specified to be true, then this event will fire after the animation has completed.
toggle Triggered both when full text is shown and truncated. If options.animate is specified to be true, then this event will fire after the animation has completed.
Options are passed as a flat javascript object with the following allowed keys:
The maximum number of lines to display when the element is truncated.
maxLines
Allowed Values: integer > 0
Default Value: 1
The line-height value that should be used to calculate the vertical truncation point. If unspecified, it will be calculated using the CSS value from each selected element.
lineHeight
Allowed Values: integer > 0
Default Value: null
Suffix to append to truncated text. e.g. … (non-breaking space followed by an ellipsis). truncateString
Allowed Values: any string
Default Value: ''
Indicates whether options.truncateString should be appended after anchor tags when the truncation point occurs inside an anchor tag. Since the truncateString is not part of the original anchor text, it is desirable to exclude it from the anchor tag. In cases where anchor tags display as block, however, this can cause the truncateString to display on a line below the anchor tag.
truncateAfterLinks
Allowed Values: true / false
Default Value: true
If specified, will be shown as a hyperlink appended to the truncated text. When clicked, this link will toggle the truncated element to its full-text state. e.g. ("more")
showText
Allowed Values: any string
Default Value: ''
If specified, will be shown as a hyperlink appended to the full text. When clicked, this link will toggle the full-text element to its truncated state. e.g. ("less")
hideText
Allowed Values: any string
Default Value: ''
Indicates whether the truncated element should be initially displayed in a full-text or truncated state.
collapsed
Allowed Values: true / false
Default Value: true
Indicates whether messages should be written to console.log including the truncation execution time and number of binary search steps used to truncate the full text. The usage of console.log in this plugin is always safe for inclusion in IE.
debug
Allowed Values: true / false
Default Value: false
A parent DOM element to use as the cloned element for measuring height of the cloned text. This is necessary when the text node can have its text displaced by floated elements inside a common parent.
contextParent
Allowed Values: jQuery object
Default Value: null
Indicates whether the original TEXT content should be set in a title attribute on the truncated element. This will strip all HTML for compatibility with HTML attribute syntax.
tooltip
Allowed Values: true / false
Default Value: false
Indicates whether the user-initiated transitions between truncated and full text should animate the height.
animate
Allowed Values: true / false
Default Value: false
If specified, will be passed into jQuery's $.fn.animate options parameter.
animateOptions
Allowed Values: object
Default Value: empty object
Methods are invoked via $('.selector').truncate(methodName, arguments...)
options Pass an object argument to reset the options. This does not immediately trigger an updated truncation.
update Takes an optional second argument to pass new HTML. With or without the argument, the original truncated element will be re-truncated. This is useful to hook into a callback when the truncated element can be subject to re-sizing (i.e. responsive design). If no HTML is passed, but the contents of the truncated text have been modified, the modified text will be used in place of the original.
Truncate to 3 lines with a trailing ellipsis, "Read More" text when collapsed, and no hide text.
$('.selector').truncate({
'maxLines': 3,
'truncateString': ' …',
'showText': 'Read More'
});
Truncate to 3 lines with a trailing ellipsis, relative to a context parent that includes a floated image.
var $el = $('.selector');
var $contextParent = $el.closest('.parent-selector');
$('.selector').truncate({
'maxLines': 3,
'truncateString': ' …',
'contextParent': $contextParent
});
-
Truncating HTML without consideration for the timing of web font loading will produce incorrectly truncated text. In cases where web fonts are used, either delay truncation until after the web fonts are loaded or call the "update" method after the web fonts have loaded. FontSpy is a good plugin for detecting when an external font has been loaded. It is based on Remy Sharp's usage of Comic Sans for determining whether a named font is loaded
-
The "update" method with 0 parameters will fail to recognize a change in the truncated HTML if the HTML length is the same as before the change was made.