Can I host TuneGraphs on my own site?

A number of people have seen the TuneGraphs on abcnotation.com and asked if they could include them on their own website.

The short answer is yes, although there are a number of restrictions.

If you are interested in this possibility, read on.

Requirements

First check the requirements. You must have:

  1. Sufficient similarities within your collection of tunes in order that the TuneGraph engine can find similar tunes. This may be possible even in a small collection of tunes: for example the TuneGraph demonstrator has been built with ~300 morris tunes; only a relatively small collection, but with lots of similar versions of the same tune.
  2. Abc code embedded within HTML pages rather than in downloadable abc files.
  3. A unique URL for every tune. The simplest way to achieve this is to have a single tune per page, but if there are multiple tunes per page an alternative to use the HTML “id” attribute. So for example the 3rd tune on the page http://example.com/page could be wrapped with <div id=’0003′>…</div> and then its unique URL is http://example.com/page#0003.

Checking

Next – before reconfiguring your site – check with me that it’s going to be possible. I will need to check that the abcbot can index your site successfully (and this is always harder with embedded abc code). I will also check that the TuneGraph engine can find sufficient similarities within the site by generating a custom set of TuneGraphs for your site (these will only link to other tunes in your site and not to other tunes on other sites).

Infrastructure

Next, you will need to put in the infrastructure for the TuneGraphs to use (although I would recommend trying this on a couple of example pages before applying to the entire site).

The simplest way to do this is to wrap every tune in a <div> element which both gives the TuneGraph viewer something to work with and identifies the tune. The <div> element needs to have the “class” attribute set as “divAbcTuneGraphContainer” and “id” as the number of the tune on the page (starting from 0001 and written with leading zeros so that each id contains 4 digits).

For example, in the TuneGraph demonstrator, each tune displayed has a title element (using an <h3> tag) and then the abc code element (using a <pre> tag to format it). These elements must then be wrapped in the <div> element so that for, say, the third tune on the page would be encoded as

<div class="divAbcTuneGraphContainer" id="0003">
<h3>Tune title</h3>
<pre>
X:1
T:Tune title
K:C
CDEF GABc|
</pre>
</div>

You can put whatever HTML elements you like inside the <div> (for example, you might want to display the abc code in a <textarea> or <p> paragraph element).

Furthermore, if you have only one tune per web page you can simplify the <div> by omitting the “id” attribute.

In addition, on each page you will need to include the following 4 JavaScript files. I recommend that you download them (from my site, using the links below, or the originating site) and serve them from your own site. It’s probably best to include them right at the bottom of the page just before the closing </body> tag.

The code to include them is

<script src="[path]/TuneGraphViewer.v2.js" type="text/javascript"></script>
<script src="[path]/d3.v3.min.js" type="text/javascript"></script>
<script src="[path]/abcjs_basic_1.10-min.js" type="text/javascript"></script>
<script src="[path]/TuneGraphConfig.v2.js" type="text/javascript"></script>

where [path] is the path to the javascript folder on your site.

Finally you will need the following definitions in your CSS file (or somewhere in each page):

div.divAbcTuneGraphCanvas {
 width: 300px;
 height: 300px;
}
div.divAbcTuneGraphScore {
 width: 300px;
}

How it works

The way that the TuneGraphConfig JavaScript code works is to look for all of the elements in the “divAbcContainer” class on the page.

It then extracts the contents of this <div> (e.g. the <h3> and <pre> elements in the example above) and replaces them with a <table> element. The table has one row with three cells: the left hand cell contains the original contents of the <div>, the middle cell has the TuneGraph canvas <div> displayed in it, and the right hand cell is a <div> used to display the scores of similar tunes.

You can find examples in the TuneGraph demonstrator pages showing usages with a single tune per page and multiple tunes per page.

Customisation

You can customise the TuneGraph usage in a number of ways.

Firstly you can change the size of “divAbcTuneGraphCanvas” and “divAbcTuneGraphScore” using the CSS definitions, although I’m not sure they will work if they are much smaller. As you might expect, “divAbcTuneGraphCanvas” is the class name for the <div> element containing the canvas – i.e. where the TuneGraph is displayed; “divAbcTuneGraphScore” is the class name for the score element, where the the scores of similar tunes appear.

You may also wish to change the location/configuration of the canvas and score <div> elements particularly if your site is often viewed on mobile devices, as a table with 3 columns will not display well on such devices.

In order to do this, just include canvas and score elements manually for each tune, with “id” attributes that match the tune they are associated with. If the TuneGraphConfig code detects any elements in either class “divAbcTuneGraphCanvas” or “divAbcTuneGraphScore”, then it won’t construct the table.

So for example to match the example tune above, with “id” set to “0003”, include:

<div class="divAbcTuneGraphCanvas" id="0003.canvas"></div>
<div class="divAbcTuneGraphScore" id="0003.score"></div>


								

Tags: , , ,

Leave a Reply