Tabsaur.us Developer Guide

Tabsaurus is a new javascript library designed to help your site:

You can find the latest version, 1.2.0, at:

https://tabsaur.us/api/1.2.0/tabsaurus.js

Contents

Getting Started

Basic Parsing with Tabsaurus

Integrating Tabsaurus on your site is simple—the first thing you’ll need to do is add tabsaurus to your site's HTML code:

<script src="https://tabsaur.us/api/1.2.0/tabsaurus.js"></script>

Then, at some point after all the <pre> tags on your page have rendered, you’ll need to call the tabsaurus() method.

In testing, on most sites it works well to put this code directly after the last </pre> tag on your page. For example:

<pre> ... </pre> <script src="https://tabsaur.us/api/1.2.0/tabsaurus.js"></script> <script> tabsaurus(); </script>

You could also, for example, call this method in your <body>’s onload attribute:

<head> <script src="https://tabsaur.us/api/1.2.0/tabsaurus.js"></script> </head> <body onload="tabsaurus()"> . . . </body>

Know, however, that If you have a large number of elements on your page, particularly ads, this method can cause a flash, as the plain text tab first loads, and tabsaurus is called later to format the page.

That’s it! Tabsaurus will, on the tabsaurus() method, find any <pre> blocks, parse and analyze each line, and render richly styled charts in their place.

Advanced Configuration

Tabsaurus will start rendering your tabs out of the box, with no customization necessary. But you can pass an options object to Tabsaurus to customize both how Tabsaurus looks and works:

<script> var options = { transpose: 2, diagrams: true, style: { chords: { font: "900 17px 'Comic Sans MS', 'Comic Sans', cursive;", color: "#0000FF" } } }; tabsaurus(options); </script>

Features

Chord Detection

Tabsaurus recognizes chords, and renders them in a customizable font. When users hover their mouse over a chord, Tabsaurus automatically generates a diagram popover, using ChordBank’s massive library of chords:

   C           F        C 
My Bonnie lies over the ocean

Custom Definitions

If a chart adds custom definitions for chords, Tabsaurus will use those instead. Define a custom chord like this:

G: 320033
Which would change G’s appearance in the tab to match: 
G: 320033

   C           F        C 
My Bonnie lies over the ocean

   C           D        G
My Bonnie lies over the sea.

On Desktop, a user hovering over a chord with her mouse will bring up a diagram. If ChordBank.com has a reference page for the chord (like this one for the G chord, for example), clicking on that chord navigate to that page.

On mobile, a user can tap on any chord symbol once to bring up a diagram. Tapping on the chord again opens a reference page, while tapping elsewhere, or scrolling, dismisses the popover.

Tabs

Starting in version 1.1, Tabsaurus has rich support for drawing tabs. To opt in, use the `tabs` option:

-9-----------------|-------------|---------x--
-7h9--9p7--x---7/8-|--8\7-7~-----|-5/12--5-x--
------9p7--x-------|-------------|---------x--
-------------------|--------6b7--|---------x--
-------------------|-------------|-4---x---x--
-0-----------------|-------------|---------x--

You’ll find most of the tab symbols in your daily use are supported. See below for specific examples.

Background color

Tabsaurus assumes a white background by default. If your background color is different, set the `bg` option to a hex color of your choice:

{ tabs: true, bg: '#f6f6f6' }

Hammer ons / Pull offs

----------
-7h9--9p7-
------9p7-
----------
----------
----------

Vibrato

----------------
-10~---9~--10~--
----------------
-------7--------
-------7--------
----------------

Slide up / down

----------
-7/9--9\7-
------9\7-
----------
----------
----------

Bends

Tabsaurus supports special formatting for bends up to two and a half steps. The interval is parsed directly from the tab itself: 
--9b10----|------|------|------|-------
----------|-9b11-|------|------|-------
----------|------|-9b12-|------|-------
----------|------|------|-9b13-|-------
----------|------|------|------|-9b14--
----------|------|------|------|-------

Dead notes

-8--x--10--x--
-10-x--12--x--
-10-x--12--x--
-------11--x--
-------10--x--
-------10--x--

Bar Lines

-8--x-|-10--x--
-10-x-|-12--x--
-10-x-|-12--x--
------|-11--x--
------|-10--x--
------|-10--x--

Note Durations

Tabsaurus has basic support for note durations, both adding symbols beneath the drawn tab, and affecting spacing. You may the following symbols underneath each frame:

Symbol Name
W Whole note
H Half note
Q Quarter note
E Eighth note

Note that whole notes are not drawn, quarter notes are a full line, half notes a half, and eigth notes have a head. Dots applied to these notes will be honored. For example:

--9-------x-------------8--|-x------|---------x--------|
--7h9---9-x-------7-----7~-|-x------|-5/12--5-x--------|
----------x----------------|-x------|---------x---4----|
----------x----------------|-x------|---------x--------|
----------x-------6--------|-x------|-4---x---x--------|
--0-------x----------------|-x------|---------x--------|
  Q     E E       Q     Q    W        Q.      E   H

Advanced Options

Supplying Your Own Class or ID

By default, tabsaurus will parse all <pre> blocks on a given page.

But you can specify either an id of a single element, or a class of one or more elements, to restrict parsing, or to parse elements that are not contained within <pre> blocks.

var options = { id: 'myElementId' }; tabsaurus(options);

Note that any element specified by a class or id must, just like pre blocks, already be rendered in the DOM before the tabsaurus() method is called.

Customizing Fonts to Match Your Site

The tabsaurus() method takes an options object. You can use this to change the style of chords, lyrics, diagrams, and headings to match the rest of your site.

For example, the following code would render chords in bold comic sans:

var options = { style: { chords: { font: "900 17px 'Comic Sans MS', 'Comic Sans', cursive;", color: "#0000FF" } } }; tabsaurus(options);

Which would look like this:

   C           F        C 
My Bonnie lies over the ocean

Presently, you can override style objects using the following keywords:

Showing Diagrams for Chords at the Top of Your Chart

Your users might find it useful to have diagrams shown for chords. You can use the diagrams: true option to show diagrams at the top of your chart for any defined chords, and any chords present in your chart that ChordBank knows definitions for.

For example: var options = { diagrams: true }; tabsaurus(options); 
G: 320033

   C           F        C 
My Bonnie lies over the ocean

   C           D        G
My Bonnie lies over the sea.

Transposition

If you have user-facing controls on your site to allow users to transpose tabs, you can call the tabsaurus method more than once, including the transpose key, with a positive or negative integer to represent the transposition amount.

var options = { transpose: 2 }; tabsaurus(options);

Text Size Levels

If your site has user-facing controls to control text size, or if you want a simple way to make text larger or smaller, you may pass a value to the size key.

tabsaurus({ size: 2 });

Acceptable values are:

Value Level Values
-1 Small Lyrics 15px, Chords 12.5px
0 Normal Lyrics 17px, Chords 14px
1 Medium Lyrics 19px, Chords 15.5px
2 Large Lyrics 20.5px, Chords 17px
3 Extra Large Lyrics 24px, Chords 20px
4 Extra Extra Large Lyrics 29px, Chords 24px

For more granular control over formatting, see Customizing Fonts to Match Your Site.

Note: either size, or style can be included in the options passed to the tabsaurus() method, but not both—in cases where both are supplied, style will be used, and size will be ignored

License

Creative Commons License
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.

This means that can use tabsaurus on your site forever, even if that site is commercial, granted you abide by the conditions of the license. For more information, see the Creative Commons website.

Changelog

© 2018 Better Notes, LLC