Dance Lists on Your Own (Non-Strathspey) Web Sites

The Problem

If you’re using the Strathspey SCD Database, you may have found that “dance lists” are a pretty nifty feature. They can take much of the hassle out of planning lessons or devising and publishing programmes for social functions. And they’re really easy to add to your web page as long as that web page is hosted on my.strathspey: A simple

<<dlist-table:My Dancelist>>

(where “My Dancelist” is the name of your dance list in the database) will do the trick.

If your web site isn’t on my.strathspey, however, things are a little bit more difficult. On your dance list’s page in the database there is a tab that lets you copy HTML code for the dance list to paste into your own web site, but this is inconvenient. In particular, if the dance list changes after the fact, you need to manually fix your own site by re-copying the HTML code from the database.

In this post we present a new approach that lets you add a dance list to your own web site such that it will be fetched from the database when required. This means that any changes or updates to the dance list in the database will automatically be reflected on your own site. Bliss!

The Solution

The basic approach is to include a short JavaScript snippet in your page that will do the actual work. JavaScript is a programming language which is popular on the Web, but you won’t have to do any actual programming – if you follow the examples displayed below you should have little trouble. (Of course a working knowledge of HTML would come in very useful.) On the other hand, if you’ve ever worked with something like the Google Maps API, this should really be child’s play.

A complete sample document is available from the Strathspey site. You can use this to try the various steps shown here.

To add a dance list to your web page, first put an HTML “div” tag in the place where you would like the dance list to show up later. (The dance list will probably turn out to be a biggish HTML table, just so you know what you’re getting yourself into.) Something like

<div id="dlist">
  (Please enable JavaScript to see the dance list.)
</div>

would be suitable. The “class=“dlist”” is required so our JavaScript code will find the “div” later. (The actual class name is irrelevant; you could use something else or even an “id=…” attribute.)

Then we need to load the actual JavaScript code, which you can retrieve from the Strathspey site or copy and put on your own site. It is best to put something like

<script type="text/javascript"
        src="https://media.strathspey.org/scddb/js/jquery.danceList.js"></script>

(replace the URL with one pointing to wherever you have put the JavaScript file on your own site if you want to host your own copy.) As a matter of fact, our code makes use of the very popular jQuery framework, which must also be available when our code is loaded¹. If you haven’t loaded jQuery before, anyway, the instructions should really look like

<script type="text/javascript"
        src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
<script type="text/javascript"
        src="https://media.strathspey.org/scddb/js/jquery.danceList.js"></script>

(the first two lines will fetch jQuery from the official jQuery distribution network).

In case you’re wondering why we don’t offer a “minified” version of the jquery.danceList.js plugin: It’s only 25 lines and so far we haven’t bothered. If there is strong demand for it we’d be happy to sort this out.

The only remaining task on the JavaScript side is actually loading the dance list. Here’s how:

<script type="text/javascript">
  $("#dlist").danceList({
      name: "My Dancelist"
  });
</script>

This will replace the content of the “div” tag with ID “dlist” by the dance list from the server. There will be a very brief delay while the JavaScript plugin goes out to fetch the dance list, but after that it will look like it was part of your web page all along.

The parameter to the “danceList” function is a JavaScript object whose properties describe how the dance list should appear. The following properties are currently defined:

name

The name of the dance list in question. This must match the name of the dance list in the Strathspey SCD Database exactly (including uppercase and lowercase letters and punctuation). The dance list in question must also be set to “Public”.

columns

Specifies the columns that will appear in the dance list. The parameter is a (quoted) string, each character of which stands for one column: “#” is the dance number, “N” the dance name, “T” the dance type, “S” the dance “shape” (type of set and number of couples), and “P” a published source for the dance. Each column is included in the output if and only if the corresponding letter shows up in the “columns” property. Note: The order of the columns is fixed and cannot be changed by changing the order of the letters in the “columns” propertie.

footer

Similar to “columns”, but describes the content of the table footer. “C” stands for a link to a crib sheet, “D” for a link to a diagram page, and “V” for a link to the video page for this dance list. (Note that we don’t guarantee that there will actually be a crib, diagram, or in particular video for any dance in the list. You will have to make do with what you get, or else try to get appropriate material added to the database.)

cribs_url

A URL for a crib sheet for the dance. If you don’t specify this, the database will insert a link to the PDF document that the database can generate. In many cases this will be perfectly adequate; the facility is there so you can point to your beautifully illuminated MiniCrib version instead.

diagrams_url

This is like “cribs_url” except it deals with diagrams rather than cribs.

show_header

Whether the table header should be displayed. Use “true”, “yes”, or “1” to confirm this; any other value turns it off. By default the header is on.

show_footer

Like “show_header”, but for the footer. (Duh.)

table_class

Specifies one or more CSS classes for the “table” tag (see below).

Doing It In Style

If you’ve tried this with a simple HTML page you will probably have noticed that the dance list looks rather ugly. This is simple to fix using CSS, and we make available a sample style sheet for your convenience. You can use this by adding

<link rel="stylesheet" type="text/css"
      href="https://media-dev.strathspey.org/scddb/css/danceList.css"
      media="screen">

to the “head” section of your HTML file (where the other CSS files are mentioned), or feel free to copy it from our machine to yours and tweak it until you like the way the dance list looks.

The dance list is a fairly simple HTML table. The nesting of HTML elements looks like

div.dlist                   [Enclosing element]
  table.table.danceList
    thead
      tr
        th.danceNumber
        th.danceName
        th.danceType
        th.danceShape
        th.dancePublication
    tbody
      td
        td.danceNumber
        td.danceName
        td.danceType
        td.danceShape
        td.dancePublication
    tfoot

(the table footer is used for a link to the dance list’s page in the Strathspey SCD database, and for the shortcut links to the crib and diagram sheets and the video page).

You can use the classes mentioned in this overview to re-style the dance list to your liking by making appropriate CSS definitions in a place where the browser can see them.

Conclusion

At this point this facility is still fairly experimental. If you use it, feel free to let me know how you get on, report bugs, or make suggestions for enhancements. Enjoy!

Footnotes

1. We're aware that jQuery is no longer what the cool kids are using. Feel free to write your own code for the JavaScript framework of your choice, based on the content of jquery.danceList.js. (It’s really very simple indeed.)