forked from MarcDiethelm/jQuery-Shorten
-
Notifications
You must be signed in to change notification settings - Fork 0
/
jquery.shorten.usage.html
229 lines (199 loc) · 9.85 KB
/
jquery.shorten.usage.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Shorten - A jQuery Plugin for Truncating Styled Text</title>
<style type="text/css" media="Screen">
.ruler { padding: 5px 0 5px 10px; border-bottom:1px dashed #000; background-color:#ffc; }
.demoText { width:500px; margin:5px 0; border: 1px dotted #000; }
.testText { width:500px; margin:47px 0 0; border: 1px dotted #000; }
.testText p, .demoText p { margin:0; }
.testText .styled, .demoText .styled {font-family:impact;font-size:1.75em;font-style:italic;}
.testText .tiny, demoText .tiny {font-family:tahoma;font-size:0.70em;font-weight:bold;}
/*.testText p, demoText p { overflow:hidden; } *//* Recommended: if not hiding the text before it's shortened. */
.testText p, demoText p { visibility: hidden; } /* Optional: hide the element before shortening its content. */
/* demo visual stuff */
body { font-family: sans-serif; font-size: small; max-width: 800px; }
.demo { margin: 20px 0; }
._100px { width: 99px; border-left: 1px dotted #888; float: right; clear: both; background-color: #fafafa; color: #ccc; }
.caption { font-size: smaller; color: #888; }
body > code { font-family: monospace; white-space: pre-wrap; border: solid #999; border-width: 0 0 0 10px; display: block; background-color: #fafafa; margin-bottom: 20px; }
.code-inline { font-family: monospace; background-color: #f4f4f4; padding: 2px;}
h2 { margin-top: 30px;}
</style>
</head>
<body>
<p>
<small>Get the latest version at <a href="https://github.com/MarcDiethelm/jQuery-Shorten">https://github.com/MarcDiethelm/jQuery-Shorten</a>.</small>
</p>
<h1>jQuery Shorten Documentation and Demo</h1>
<p>
This jQuery plugin automatically truncates single-line text to fit in a block or pre-set width while you can configure
how the text ends (<a href="http://en.wikipedia.org/wiki/Ellipsis">ellipsis</a>). The default is the triple-dot character
("…", &hellip;, Unicode: 2026) but you can use anything you want, including markup. If you're looking for CSS3 text-overflow
functionality this plugin implements it, and more.
</p>
<div class="demo">
<div class="demoText test1">
<div class="ruler"><code>.shorten()</code> (fit parent)</div>
<p class="unstyled">Zero configuration, unstyled <p> element shortened to fit the parent <div>'s width.</p>
<p class="styled">This is a bit of styled text that could be any length, but has to fit the parent width.</p>
<p class="tiny"><!-- inner markup will be stripped --><span style="color:pink;">This is a bit of tiny text that could be any length, but has to fit the parent width.
(For example, this is a really long bit of text that has to fit on a single line.)</span></p>
</div>
<span class="caption">
The parent has a dotted border and its width is set to 500px in CSS.
</span>
</div>
<small>Tip: To find out if your use case is supported you can check the <a href="test/test.html">test page</a>!</small>
<p>
This is achieved using either of two methods: First the text width of the 'selected' element (eg. span or div) is
measured using Canvas or by placing it inside a temporary table cell. If it's too big to big to fit in the element's
parent block it is shortened (initially using an educated guess for efficiency) and measured again until it (and the
appended ellipsis) fits inside the block. A tooltip on the 'selected' element displays the full original text.
</p>
<p>
If the browser supports truncating text with CSS ('text-overflow:ellipsis') then that is used (but only if the text to append is the default "…").
</p>
<p>
If the text is truncated by the plugin any markup in the text will be stripped (eg: "<a" starts stripping, "< a"
does not). This behaviour is dictated by jQuery's <span class="code-inline">.text(val)</span> method. The appended text may contain HTML however (a link or span for example).
</p>
<p>
Usage example ('selecting' a div with an id of "element"):
</p>
<code>
<div style="width:500px;">
<div,span,p... class="foo">text</div,span,p...>
</div>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="jquery.shorten.js"></script>
<script type="text/javascript">
$(function() {
$(".foo").shorten();
});
</script>
</code>
<p>
By default the plugin will use the parent block's width as the maximum width and the "…" char as appended text.
</p>
<h2>Options</h2>
<p>
There are three ways of configuring the plugin:
<p>
1) Passing a configuration hash as the plugin's argument, eg:
</p>
<code>
.shorten({
width: 400,
tail: ' <a href="#">more</a>',
tooltip: false
});
</code>
<p>
2) Using two optional arguments (deprecated!):
width = the desired pixel width, integer
tail = text/html to append when truncating
</p>
<p>
3) By changing the plugin defaults, eg:
</p>
<code>
$.fn.shorten.defaults.tail = ' <a href="#">more</a>';
</code>
<div class="demoText test3" style="position: relative;">
<div class="ruler"><code>.shorten({width: 400}), .shorten({width: 400, tail: '<a href="">...more</a>'})</code></div>
<div class="unstyled _100px"> </div>
<div class="styled _100px"> 400px</div>
<div class="tiny _100px"> </div>
<p class="unstyled">This is a <p> element that could be any length, but has to fit a given pixel width.</p>
<p class="styled">This is a bit of styled text that could be any length, but has to fit a given pixel width.</p>
<p class="tiny">Too short, no need to truncate.</p>
</div>
<span class="caption">
Truncating with options set.
</span>
<h2>Default settings</h2>
<code>
$.fn.shorten.defaults = {
tail: "&hellip;",
tooltip: true
};
</code>
<h2>Notes</h2>
<p>
- There is no default width (unless you create one).
</p>
<p>
- You may want to set the element's CSS to <span class="code-inline">{visibility:hidden;}</span> so it won't initially flash at full width in slow browsers. The plugin unhides it when it's done.
</p>
<code>
.shortenText {
overflow:hidden; /* Recommended: if not hiding the text before it's shortened. */
visibility: hidden; /* Optional: hide the element before shortening its content. */
}
</code>
<p>
- The <a href="http://www.w3.org/TR/2003/CR-css3-text-20030514/#text-overflow-props">CSS3 spec</a> requires the element to be a block for text-overflow.
And Chrome additionally requires <span class="code-inline">white-space:nowrap</span> and <span class="code-inline">overflow:hidden</span>.
Shorten sets all selected elements to <span class="code-inline">display:block</span> and <span class="code-inline">white-space:nowrap</span>.
When using text-overflow it's also setting the element to <span class="code-inline">overflow:hidden</span>.
</p>
<p>
- jQuery < 1.4.4: Shorten doesn't work for elements who's parents have <span class="code-inline">display:none</span>, because
<span class="code-inline">.width()</span> is broken (returns negative values).<br />
see: <a href="http://bugs.jquery.com/ticket/7225">jQuery bug #7225</a>. Workarounds:
<ul>
<li>Use jQuery 1.4.4+</li>
<li>Supply a target width in options.</li>
<li>Use better timing: Don't use <span class="code-inline">display:none</span> when shortening (maybe you can use
<span class="code-inline">visibility:hidden</span>). Or shorten after changing display.</li>
</ul>
</p>
<p>
- Text in floated elements gets its target width from the element itself, not from the parent container.
</p>
<p>
- Only supports ltr text for now.
</p>
<hr />
<p>
Tested with jQuery 1.3+
</p>
<p>
Based on a creation by M. David Green (www.mdavidgreen.com) in 2009.
</p>
<p>
Heavily modified/simplified/improved by Marc Diethelm (http://web5.me/).
</p>
<p>
<strong>Get the latest version at <a href="https://github.com/MarcDiethelm/jQuery-Shorten">https://github.com/MarcDiethelm/jQuery-Shorten</a>.</strong>
</p>
<script type="text/javascript" src="jquery/jquery-1.4.4.js"></script>
<script type="text/javascript" src="jquery.shorten.js"></script>
<script type="text/javascript">
$(function() {
var newWidth = 500; // the maximum target width, in pixels
$("p.unstyled", ".test1").shorten(); // Zero configuration, default ellipsis
$("p.styled", ".test1").shorten({tail: '… <a href="#">more</a>'});
$("p.tiny", ".test1").shorten({tail: " – really long substitution text"});
newWidth = 400;
$("p.unstyled, p.tiny", ".test3").shorten({width: newWidth});
$("p.styled", ".test3").shorten({width: newWidth, tail: '… <a href="#">more</a>'});
});
</script>
<!-- Support this free plugin -->
<div style="position:fixed; right:0; top: 0px; padding: 0 20px 3px; text-align:center; line-height:2.5; opacity:.75; background: #f8f8f8; border:1px dotted #ccc; border-bottom-left-radius: 8px 8px; -moz-border-radius-bottomleft: 8px 8px; -webkit-border-bottom-left-radius: 8px 8px;">
<small>Wanna show some love..?</small><br />
<a href="http://flattr.com/thing/104330/jQuery-Shorten" target="_blank">
<img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Support via Flattr" border="0" />
</a>
<br />
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="EY7ASLWWDBW58">
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" title="Donate via PayPal" alt="Donate via PayPal">
</form>
<div>
</body>
</html>