Extension:ABCjs

ABCjs

Release status: beta

Implementation Page action, Edit page
Description provide support for rendering abc music notation on mediawiki pages
using the abcjs javascipt package, and for setting tune related categories
when editing pages.
Author(s) Lawrie Brown
Latest Version 1.0
License CC By NC SA
MediaWiki tested on 1.29+
Download http://bushtraditions.wiki/tunes/extensions/ABCjs.zip

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.

Contents

Installation


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

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_3.3.2-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


Acknowledgements

Copyright © 2018 Lawrie Brown