Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 383 lines (332 sloc) 16.393 kb
0de8b69 Paul Gallagher staging for initial release
authored
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html>
4 <head>
5 <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
6
7 <title>jTab - Guitar Chord and Tab Library</title>
29ae488 Paul Gallagher final for first release
authored
8 <meta name="description" content="jTab is a javascript-based library that allows you to easily render arbitrary guitar chord and tabulature (tab) notation on the web"/>
0de8b69 Paul Gallagher staging for initial release
authored
9 <meta name="keywords" content="guitar,chord,tab,tabulature,music,notation,javascript,css,svg,html,xhtml"/>
10
8ec25cf Paul Gallagher externalise site css; tweak formatting
authored
11 <link type="text/css" rel="stylesheet" href="css/jtab-site.css"/>
0de8b69 Paul Gallagher staging for initial release
authored
12
13 <!-- START: for jtab -->
14 <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />
8ec25cf Paul Gallagher externalise site css; tweak formatting
authored
15 <link type="text/css" rel="stylesheet" href="css/jtab-helper.css"/>
0de8b69 Paul Gallagher staging for initial release
authored
16 <script src="javascripts/prototype.js" type="text/javascript"></script>
17 <script src="javascripts/raphael.js" type="text/javascript"></script>
18 <script src="javascripts/jtab.js" type="text/javascript"></script>
19 <!-- END: for jtab -->
20 </head>
21 <body>
22
23 <div id="header">
24 <h1>jTab - Guitar Chord and Tab Notation for the Web</h1>
25 <p>
26 jTab is a javascript-based library that allows you to easily render arbitrary guitar chord and tabulature (tab)
27 notation on the web. Automatically. It works in most modern browsers that support javascript, CSS and scalable vector graphics (SVG) -
28 for example, Internet Explorer 7 and Firefox 3.
29 </p>
30
31 </div>
32
33 <div id="menu">
34 <ul>
35 <li><a href="#">About jTab</a></li>
36 <li><a href="#examples">Live Examples</a></li>
37 <li><a href="#notation">Notation Reference</a></li>
38 <li><a href="#download">Download</a></li>
39 <li><a href="#install">How To Install</a></li>
40 <li><a href="#help">Troubleshooting and Tips</a></li>
41 <li><a href="#feedback">Feedback &amp; Contribute</a></li>
42 <li><a href="#limitations">Limitations</a></li>
1e73507 Paul Gallagher added jTab in the wild section
authored
43 <li><a href="#inthewild">jTab in the Wild</a></li>
0de8b69 Paul Gallagher staging for initial release
authored
44 </ul>
45 </div>
46
47
48
49
50 <div id="content">
51 <a name="about"><h2>About jTab</h2></a>
52 <p>
53 Guitar tab is all over the internet, but it is usually in either a fixed/non-interactive form, or painstaking ASCII format.
54 jTab is a javascript-based library that lets you change that. It automatically converts a simple text notation
55 into a web-friendly graphical representation on the fly.
56 </p>
57 <p>
58 You can use it to post snippets on your blog, host user contributions on a web site, or just for personal transcription purposes.
59 It is also scriptable with javascript for more sophisticated applications.
60 </p>
61 <p>
62 Technically, jTab is a javascript-based library that renders notation using CSS and scalable vector graphics (SVG).
63 It works in most modern browsers that support javascript, CSS and scalable vector graphics (SVG) -
64 for example, Internet Explorer 7 and Firefox 3.
65 </p>
66 <p>
29ae488 Paul Gallagher final for first release
authored
67 jTab is written and maintained by <a href="http://tardate.com">Paul Gallagher</a> and released as open source for all to exploit.
68 Aside from just scratching a personal itch, jTab was greatly inspired by
0de8b69 Paul Gallagher staging for initial release
authored
69 Dmitry Baranovskiy's fantastic work on the <a href="http://raphaeljs.com/">Rapha&euml;l</a> SVG library,
29ae488 Paul Gallagher final for first release
authored
70 and Alex Gorbatchev's <a href="http://www.dreamprojections.com/syntaxhighlighter/">syntaxhighlighter</a> (for opening the door to what is possible!).
0de8b69 Paul Gallagher staging for initial release
authored
71 </p>
72
73
74
75 <a name="examples"><h2>Live Examples</h2></a>
76 <p>
77 Show don't tell! So before going further, here are some examples of jTab in action.
29ae488 Paul Gallagher final for first release
authored
78 More examples are available <a href="examples.htm">here</a>.
0de8b69 Paul Gallagher staging for initial release
authored
79 </p>
80
81 <h3>Interactive/Explicit Rendering using Javascript</h3>
82 <p>
29ae488 Paul Gallagher final for first release
authored
83 jTab can be used to render notation in real-time using Javascript. This could be based on user input (like here), or with the notation feed
0de8b69 Paul Gallagher staging for initial release
authored
84 being generated or retrieved from some system or web service.
85 </p>
8ec25cf Paul Gallagher externalise site css; tweak formatting
authored
86 <span>Try it out. Enter a phrase here (see <a href="#notation">notation</a> for help):</span>
87 <input id="notation" size="40"><input type="button" value="jTab this!" onclick="jtab.render('tab',$('notation').value);">
0de8b69 Paul Gallagher staging for initial release
authored
88 <div id="tab"><i>jTab will render your phrase here</i></div>
89
de2713f Added ability to just press 'Enter' instead of clicking on button to try...
Jason Ong authored
90 <script type='text/javascript'>
91 $('notation').observe('keypress', function(e){
92 if (e.keyCode == 13) {
93 jtab.render('tab',$('notation').value);
94 }
95 });
96 </script>
0de8b69 Paul Gallagher staging for initial release
authored
97
98 <h3>Implicit Rendering using CSS</h3>
99 <p>
100 jTab implicitly renders tab notation on a web page that is contained in blocks marked with the special class name 'jtab'.
101 This can be used for posting transcriptions to your blog for example - just include jTab in your blog template then
102 when posting you don't need to remember anything else except to set the class name on your notation.
103 </p>
104
105 <p>Here, a chord phrase is written directly into the web page..</p>
106 <div class="jtab chordonly"> E / / / | A7 / B7 / || </div>
107 <p>Here's an example combining chords and tab notation..</p>
108 <div class="jtab">Bm $3 4 4h5p3h4 5 $2 3 5 7 7h8p7 5/7 | A $4 7 9 $3 7 6 $5 9 $4 7h9 7 $5 9\7 5/7 | </div>
109 <p>Or just tab notation..</p>
110 <div class="jtab tabonly">$4.7/9.$3.6/8.$2.5/7 9p7 $2.9.$3.9.$4.9 </div>
111
112
113 <a name="notation"><h2>Notation Reference</h2></a>
114 <p>
115 If you find this a little dry to read,
29ae488 Paul Gallagher final for first release
authored
116 see the <a href="examples.htm">examples</a> page which demostrate all these features and more.
0de8b69 Paul Gallagher staging for initial release
authored
117 </p>
118 <h3>Chord Notation</h3>
119 <p>
120 Chord notation is quite conventional e.g. C Gm F#7 Db.
121 </p>
122 <ul>
123 <li>The root note (A..G) must be uppercase</li>
124 <li>Seperate every item with spaces</li>
125 <li><strong>#</strong> indicates sharp</li>
126 <li><strong>b</strong> (lowercase B) indicates flat</li>
127 <li><strong>m</strong> (lowercase) indicates minor</li>
128 <li><strong>maj</strong> (lowercase) indicates major</li>
60c00aa Added diminished chords for A, A#, Bb, B, C, E, F
Jason Ong authored
129 <li><strong>sus</strong> (lowercase) indicates suspended</li>
130 <li><strong>dim</strong> (lowercase) indicates diminished</li>
d5e03c9 Changes to homepage:
Jason Ong authored
131 <li><strong>aug</strong> (lowercase) indicates augmented</li>
0cb9b3a Added Cadd9 chord extension
Jason Ong authored
132 <li><strong>add</strong> (lowercase) indicates extensions</li>
0de8b69 Paul Gallagher staging for initial release
authored
133 <li>Numbers (6,7,9) to indicate 6ths, 7ths, 9ths etc</li>
134 <li><strong>/</strong> indicates repeat of the previous chord</li>
135 <li><strong>|</strong> is a standard <a href="http://en.wikipedia.org/wiki/Bar_(music)" target="_blank">bar line</a></li>
136 <li><strong>||</strong> is an ending bar line</li>
137 <li>The chord library is a little limited at this point but will grow over time (see <a href="#limitations">limitations</a>)</li>
138 </ul>
b6f5af4 Paul Gallagher added CAGED documentation and examples
authored
139 <p>
140 jTab also supports <a href="http://en.wikipedia.org/wiki/Guitar_chord#CAGED_major_chords" target="_blank">CAGED major chord notation</a>.
141 This is a convenient method for indicating major chords at various positions on the fretboard.
142 </p>
143 <ul>
144 <li>Applied only to root chords C, A, G, E, and D</li>
145 <li>Position is indicated by following the chord with a colon and the position number 1 to 5</li>
146 <li>e.g. C:1, C:5, E:2, D:3</li>
147 </ul>
148
0de8b69 Paul Gallagher staging for initial release
authored
149
150 <h3>Tab Notation</h3>
151 <p>
152 Representing <a href="http://en.wikipedia.org/wiki/Tablature" target="_blank">tab notation</a> is little special to jTab,
153 but aims to be as simple as possible.
154 </p>
155 <p>
156 Basic entry of notes on a single string is done by setting the string and then following with the notation (separated by spaces).
157 <ul>
158 <li>Indicating the string is done with the dollar sign ("$") followed by the string number (1-6, high to low).
159 e.g. $2 is the B string in standard tuning</li>
160 <li>Then you can in fact follow with anything you like - fret position, slides ( / \ ) hammerons (h), pulloffs (p) etc (just avoid uppercase characters to avoid confusion with chords)</li>
161 <li>Examples:
162 <ul>
163 <li>$2 0 1 3 (a simple three note sequence on the B string)</li>
164 <li>$2 0 1 3 $1 0 1 3/5 (a sequence of notes starting on the B string, continuing on the high E string, finishing with a slide to A)</li>
165 </ul>
166 </li>
167 </ul>
168
169 </p>
170 <p>
171 What about more than one note at the same time?
172 To handle multiple notes played on different strings, join all the individual string notation together with periods (".")
173 </p>
174 <p>Examples:
175 <ul>
176 <li>$3.6.$2.5h7 $1 5 $2 7 (start with two notes on G and B strings followed by a hammeron and two individual notes)</li>
177 <li>$4.7/9.$3.6/8.$2.5/7 9p7 $2.9.$3.9.$4.9 (three notes across D,G,B strings with a slide up two steps and a twist)</li>
178 </ul>
179 </p>
180
181
182
183 <h3>Mixing Chord &amp; Tab Notation</h3>
184 <p>
185 You can mix chord and tab notation without restriction in the one phrase.
186 This will result in a tab line being drawn, with chord charts above where relevant.
187 </p>
188
189
190 <a name="download"><h2>Downloading/obtaining jTab </h2></a>
191 <p>
192 jTab is open source and free to use. You are welcome to use and reuse it however you like.
193 </p>
194 <p>
5b586f5 Paul Gallagher relocated home to jtab.tardate.com
authored
195 The project home page is at <a href="http://jtab.tardate.com/">http://jtab.tardate.com</a>
0de8b69 Paul Gallagher staging for initial release
authored
196 </p>
197 <p>
198 The master source code repository is on github (<a href="http://github.com/tardate/jtab/tree/master">http://github.com/tardate/jtab/tree/master</a>).
29ae488 Paul Gallagher final for first release
authored
199 You will always find the latest version here and be able to <a href="#feedback">contribute</a> to the project yourself.
200 </p>
201 <p>
5b586f5 Paul Gallagher relocated home to jtab.tardate.com
authored
202 There is also a version located at http://jtab.tardate.com that you can point to directly (although performance may suffer a little).
0de8b69 Paul Gallagher staging for initial release
authored
203 </p>
204
205 <a name="install"><h2>How To Install jTab on your Web Page or Site</h2></a>
206 <h3>1. Include jTab Javascript files</h3>
207 <p>
208 jTab is provided as a single javascript source file (jtab.js) that needs to be included on your page.
209 It depends on two additional libraries that must also be included: <a href="http://www.prototypejs.org/" target="_blank">Prototype</a> (prototype.js)
210 and <a href="http://raphaeljs.com/" target="_blank">Rapha&euml;l</a> (raphael.js).
211 Compatible versions of these libraries located along with jtab.js, or if you are already using a version of these libraries
212 you probably do not need to include them again.
213 </p>
29ae488 Paul Gallagher final for first release
authored
214 <p>
215 You can <a href="#download">download</a> these files and use them locally on your own site.
5b586f5 Paul Gallagher relocated home to jtab.tardate.com
authored
216 There is also a version located at http://jtab.tardate.com that you can point to directly (although performance may suffer a little).
29ae488 Paul Gallagher final for first release
authored
217 The example below shows how to pull the files direct from tardate.com.
218 </p>
0de8b69 Paul Gallagher staging for initial release
authored
219
d5e03c9 Changes to homepage:
Jason Ong authored
220 <pre>
0de8b69 Paul Gallagher staging for initial release
authored
221 &lt;head&gt;
8ec25cf Paul Gallagher externalise site css; tweak formatting
authored
222 ... (other stuff) ...
223 &lt;!-- recommended to avoid security warnings with SVG in IE8 --&gt
224 &lt;meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" /&gt;
225 &lt;!-- optional: helpers to preset jtab region heights to avoid rendering jitter --&gt
5b586f5 Paul Gallagher relocated home to jtab.tardate.com
authored
226 &lt;link type="text/css" rel="stylesheet" href="http://jtab.tardate.com/css/jtab-helper.css"/&gt;
0de8b69 Paul Gallagher staging for initial release
authored
227
8ec25cf Paul Gallagher externalise site css; tweak formatting
authored
228 &lt;!-- mandatory script includes for jtab --&gt
5b586f5 Paul Gallagher relocated home to jtab.tardate.com
authored
229 &lt;script src="http://jtab.tardate.com/javascripts/prototype.js" type="text/javascript"&gt;&lt;/script&gt;
230 &lt;script src="http://jtab.tardate.com/javascripts/raphael.js" type="text/javascript"&gt;&lt;/script&gt;
231 &lt;script src="http://jtab.tardate.com/javascripts/jtab.js" type="text/javascript"&gt;&lt;/script&gt;
0de8b69 Paul Gallagher staging for initial release
authored
232
233 &lt;/head&gt;
234 &lt;body&gt;
235 ...
236 </pre>
237 <p>
238 Note the optional jtab-helper.css file. It is used to preset jtab region heights to avoid screen layout resizing during rendering.
239 More information about that <a href="#help">here</a>.
240 </p>
241
242
243
244 <h3>2. Performing Implicit Rendering</h3>
245 Seriously, how easy is this? Just put your notation text inside any block tag (e.g. DIV) and give it the class name "jtab"..
d5e03c9 Changes to homepage:
Jason Ong authored
246 <pre>
0de8b69 Paul Gallagher staging for initial release
authored
247 &lt;div class="jtab"&gt; E / / / | Am / B / || &lt;/div&gt;
248 </pre>
249 <p>
250 The HTML code above produces the following (view the source of this page to prove it yourself!):
251 </p>
252 <div class="jtab chordonly"> E / / / | Am / B / || </div>
253
254 <h3>3. Explicit Rendering with Scripting</h3>
255 <p>
256 You can script the rendering of a guitar tab phrase into any HTML block using a line of javascript to call the jtab.render() function.
257 jtab.render() takes two parameters. The first is the ID or name of the HTML element to render the tab into, and the second is the actual line of tab notation (a string).
258 Obviously, you can bring all your javascripting expertise to bear: the tab notation may be preset in the page, pulled from a database, the result of a web services call, entered by the user, or ...
259 </p>
d5e03c9 Changes to homepage:
Jason Ong authored
260 <pre>
0de8b69 Paul Gallagher staging for initial release
authored
261 &lt;div id="mytab"&gt;&lt;/div&gt;
262 &lt;script type="text/javascript"&gt;
263 jtab.render('mytab','Am7 C');
264 &lt;/script&gt;
265 </pre>
266 <p>
267 Actual result is this:
268 </p>
269
270 <div id="mytab"><i>jTab rendering here..</i></div>
271 <script type="text/javascript">
272 jtab.render('mytab','Am7 C');
273 </script>
274
275
276
277
278 <a name="help"><h2>Troubleshooting and Tips</h2></a>
279
280 <h3>Page layout jitters while rendering jTab</h3>
281 <p>
282 jTab automatically resize HTML DOM objects to fit the notation it is rendering.
283 Because of this, page layout main jitter around as the page elements are changing size.
284 To avoid this, you can pre-size your jtab elements to avoid the resizing.
285 </p>
286 <p>
287 At the moment, the standard height of jTab renderings is as follows:
288 <ul>
289 <li>Chord and tab diagram: 218px</li>
290 <li>Chord-only diagram: 118px</li>
291 <li>Tab-only diagram: 100px</li>
292 </ul>
293 Note that width is indeterminate - it depends on your notation.
294 </p>
295 <p>
296 An optional stylesheet is included in the jTab kit (css/jtab-helper.css)and can be included in you pages:
297 </p>
0c034fd Paul Gallagher minor formating and contribution text changes
authored
298 <pre>&lt;link type="text/css" rel="stylesheet" href="http://jtab.tardate.com/css/jtab-helper.css"/&gt;
0de8b69 Paul Gallagher staging for initial release
authored
299 </pre>
300 <p>
301 The stylesheet presets the jtab class to the maximum possible height, and provides class modifiers if you know you
302 will only have tab or chord elements present.
303 </p>
d5e03c9 Changes to homepage:
Jason Ong authored
304 <pre>&lt;div class="jtab"&gt;(pre-sized for chord and tab)&lt;/div&gt;
0de8b69 Paul Gallagher staging for initial release
authored
305 &lt;div class="jtab chordonly"&gt;(pre-sized for chord only)&lt;/div&gt;
306 &lt;div class="jtab tabonly"&gt;(pre-sized for tab only)&lt;/div&gt;
307 </pre>
308
309
310 <h3>Inline blocks and IE</h3>
311 <p>
312 Implicit rendering with normally inline blocks (like a SPAN tag) can be an issue in IE.
313 Rendering a series of SPAN tags may result in the guitar tabs being written over each other (it seems IE does not automatically
314 adjust the size of the block to fit the rendered guitar tab, whereas Firefox does for example).
315 </p>
316 <p>
317 Solution: just avoid inline blocks. Hold your guitar tab in a DIV tag for instance.
318 </p>
319
320 <h3>Implicit rendering isn't happening?</h3>
321 <p>
322 jTab hooks the window.onload function in order to "automagically" do its implicit, CSS-based rendering.
323 It plays well with other onload handlers installed <i>before</i> jTab, however if anything on your page
324 installs an onload handler <i>after</i> jTab, it may overwrite the jTab hook and prevent it running.
325 </p>
326 <p>
327 Solution 1: restructure your page so that jtab.js is included after anything else that may interfere with it.
328 <br/>
329 Solution 2: include an explicit call to the rendering function at the end of your page:
330 </p>
d5e03c9 Changes to homepage:
Jason Ong authored
331 <pre>
0de8b69 Paul Gallagher staging for initial release
authored
332 &lt;script type="text/javascript"&gt;
333 jtab.renderimplicit();
334 &lt;/script&gt;
335 </pre>
336
337 <a name="feedback"><h2>Feedback &amp; Contribute</h2></a>
338 <p>
339 jTab is officially a 'weekend' project, hence there's always more that could be done (see 'limitations' below) ;-)
340 Feedback is eagerly sought, particularly for things like:
341 <ul>
342 <li>Additional chords you want to see supported</li>
343 <li>Spotted any incorrect fingerings?</li>
0c034fd Paul Gallagher minor formating and contribution text changes
authored
344 <li>Browser incompatibility or rendering issues?</li>
0de8b69 Paul Gallagher staging for initial release
authored
345 <li>Features you'd really like to see included</li>
346 <li>Or just let me know how you are using jTab and what you think!</li>
347 </ul>
348 </p>
0c034fd Paul Gallagher minor formating and contribution text changes
authored
349 <p>
1e73507 Paul Gallagher added jTab in the wild section
authored
350 The best way to contribute is to join in the project on <a href="http://github.com/tardate/jtab/tree/master" target="_blank">github</a>. Fork and update, or just log an issue in the issues list.
0c034fd Paul Gallagher minor formating and contribution text changes
authored
351 </p>
0de8b69 Paul Gallagher staging for initial release
authored
352
353 <a name="limitations"><h3>Limitations</h3></a>
354 <p>
355 jTab is a new project, so there are definitely some things it can't do at the moment. Some of the main things to note:
356 </p>
357 <ul>
358 <li>Chord library is relatively limited at the moment (expanding .. they just need typing in!)</li>
359 <li>Chord diagrams don't support variations: generally only the most common, usually open fingering is supported</li>
360 <li>Chord diagrams don't render a barre symbol or other common annotations.</li>
361 <li>No explicit support for alternate tunings</li>
362 <li>Currently only six-string beasts. No bass, lutes, mandolins, banjoes etc etc.. sorry ;-) </li>
363 </ul>
1e73507 Paul Gallagher added jTab in the wild section
authored
364
365
366 <a name="inthewild"><h2>jTab in the Wild</h2></a>
367 <p>
368 Here are some places where you can see jTab in action:
369 </p>
370 <ul>
371 <li><a href="http://chordmaster.tardate.com/" target="_blank">ChordMaster 2000</a> - a tool to help you learn chord fingerings for guitar</li>
372 </ul>
373 <p>
374 Let us know if you find more to be listed here.
375 </p>
0de8b69 Paul Gallagher staging for initial release
authored
376 </div>
377
378 <div id="footer">
379 </div>
29ae488 Paul Gallagher final for first release
authored
380
0de8b69 Paul Gallagher staging for initial release
authored
381 </body>
0cb9b3a Added Cadd9 chord extension
Jason Ong authored
382 </html>
Something went wrong with that request. Please try again.