Extension:ABCjs

The ABCjs extension provides support for rendering abc music notation on mediawiki pages using Paul Rosen and Gregory Dyke's abcjs javascipt package, and for setting tune related categories when editing pages.

This extension is likely used along with the abcExport extension that supports exporting content from pages containing abc music notation as an abc notation file or as a pdf of the rendered score.

Installation

Installation of ABCjs requires installing the extension code and the supporting abcjs javascipt package into your wiki.

• Download and unzip the extension code so the files are saved in a directory called ABCjs in your extensions/ folder.
• Download the latest abcjs_basic (or abcjs_midi) and abcjs_plugin javascript files from abcjs (where) into your extensions/ folder.
• Edit the sandbox.html file to reference the abcjs_basic/abcjs_midi file you have.
• Add the following code at the bottom of your LocalSettings.php:

  wfLoadExtension('ABCjs');
  

• Configure as required. In particular, ensure $wgABCjs_plugin refers to the abcjs_plugin javascript file you downloaded.
• Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

You can then redefine any of the following globals after the wfLoadExtension statement in your LocalSettings.php:

$wgABCjs_plugin

name of abcjs plugin file (in this extension dir) to use, eg.

$wgABCjs_plugin = "$wgScriptPath/extensions/ABCjs/abcjs_plugin_5.12.0-min.js";

$wgABCjs_abcTag

string marking the start of some abc notation in a wiki page. Default <pre id=abc>

$wgABCjs_abcTagEnd

string marking the end of some abc notation in a wiki page. Default </pre>

$wgABCjs_abcCat

Category tag used to indicate that abc notation is used on this page, and that additional key, meter & rhythm category tags should be added or updated after it. Default Tune

$wgABCjs_abcHide

Namespace where abc notation hidden, just score shows. Default Set

$wgABCjs_abcMax

max count of abc tunes to render when notation hidden. Default 100

$wgABCjs_debug

set true for debug diagnostic display when running. Default false

$wgABCjs_UserDebug

set true for abcjs debug diagnostic on User pages. Default false

See ABCjs/extension.json in your extensions/ folder for the default values of these variables.

Usage

Once installed, the extension operates automatically whenever pages are displayed or edited.

More specifically, the inclusion of the abcjs_plugin used to render abc music notation on the page as a score occurs when any page, other than '''Special''' pages, is displayed.

The edit checks occur whenever pages in the (Main) and User namespaces are edited, which is where tune content that should be rendered is assumed to be located. These scan for any abc notation content surrounded by $wgABCjs_abcTag (<pre id=abc>) and $wgABCjs_abcTagEnd (</pre>) tags on pages in category $wgABCjs_abcCat (Tune). It locates any key, meter and rhythm abc tags, and generates suitable mediawiki category tags for each of these, placing them after the existing $wgABCjs_abcCat category tag.

You may wish to provide a template for tune pages that includes these details. Such a template could be provided to page edits by the MultiBoilerplate extension for example. The template may look like:

<pre id=abc>

T:title of tune
M:meter
L:note length
R:rhythm (use multiple R: tags for multiple suggested rhythms)
K:key
|"D"D D A A|"G"B B "D"A2
</pre>

<!-- Additional notes and comments, links to related material, e.g. recordings, info on tune, collector etc can be included below this line using standard wikitext markup. -->

<!-- Please DO NOT CHANGE any of the following lines. The category tags will be automatically created/updated when you save the page. -->
[[Category:Tune]]

This extension also includes a basic HTML ABC sandbox page (using the basic (editor) abcjs module) that lets you enter abc notation and view the rendered result immediately. You can link to this file from inside the wiki using code like:

See the [{{SERVER}}{{SCRIPTPATH}}/extensions/ABCjs/sandbox.html ABC sandbox]

Technical Details

This extension adds a BeforePageDisplay() hook to include and configure the abcjs javascipt package, that renders abc music notation as a score, on all pages that match the required content criteria (see extension comments for details). Management of the Tune classification tags is assisted by adding EditPage::attemptSave hook that scans the abc notation of a tune page being saved, and automatically adds/updates the required Key, Meter and Rhythm Category tags at the end of the page.

See also

• abcExport extension

Acknowledgements

Copyright © 2018 Lawrie Brown