Copyright © 2016 David A. Randolph Copyright © 2016 David A. Randolph
We make abcDE available by itself in both human-readable and minimized formats. We also provide a prepackaged release with all third-party dependencies included and a minimized version of same.
AbcDE is deployed as a JavaScript library, which can be easily leveraged within an HTML document to provide a customized editor.
The following HTML provides an abcDE editor with all features enabled and no constraints placed on user preferences.
<html>
<head profile="http://www.w3.org/2005/10/profile">
<link rel="stylesheet" type="text/css" href="https://dvdrndlph.github.io/didactyl/abcde/css/abcDE.css">
<script src="https://dvdrndlph.github.io/didactyl/abcde/lib/abcDE_full.js" type="text/javascript"></script>
</head>
<body>
<div id="abcde"></div>
<script type="text/javascript">
window.onload = function() {
var abcDE = new AbcDE();
abcDE.renderUI({
file_input:true,
url_input:true,
preset_select:true
});
}
</body>
</html>
A call like the following to AbcDE.render() would be suitable for a controlled experiment where users must provide complete fingering data for a specific piece:
abcDE.renderUI({
preset:'first',
output:'append',
validate:'complete',
url:'http://dvdrndlph.github.io/didactyl/mxl/OpenWTC/pf24.mxl'
});
You may also initialize the editor to specific abc (or abcd) content by including a TEXTAREA element with ID "abc_source" above the "abcde" DIV tag, like so:
<body>
<textarea id="abc_source">X:1
T:Fragment A
C:Czerny
M:C
L:1/16
Q:"Allegro"
K:C
V:1 treble
V:2 treble
V:1
!p!egfg efde cc'bc' abga|]
V:2
[GC]4 z4 [GE]4 z4|]
</textarea>
<div id="abcde"></div>
<script type="text/javascript">
window.onload = function() {
var abcDE = new AbcDE();
abcDE.renderUI({
file_input:true,
url_input:true,
preset_select:true
});
}
</body>
Important: Qualtrics support is currently not working under Safari. Please use Chrome if you are using abcDE with Qualtrics.
Working with Qualtric's unofficial, but very useful, JavaScript API can be a tedious task. AbcDE provides special features to make this process as easy as possible.
To use these features, however, you must adopt naming conventions for the embedded data elements used to save fingering data. Full abcD output will be written to variables like this:
abcD_1
Fingering data in abcDF format will be written to variables like this:
abcDF_1
You must add appropriately named embedded data elements in a block at the end of your survey. The digits included in the element names must correspond to the X identifier in the corresponding abc input for a question.
In the Look & Feel window for your survey, click the Advanced tab. Enter the following URL in the External CSS field:
https://dvdrndlph.github.io/didactyl/abcde/css/abcDE.css
(Note that it is important to use secure HTTP (https) URLs when working with Qualtrics to avoid access errors.)
Enter text like the following in the Header field:
<script src="https://dvdrndlph.github.io/didactyl/abcde/lib/abcDE_full.js" type="text/javascript"></script>
<script type="text/javascript">
Qualtrics.SurveyEngine.addOnload(function () {
var sourceField = document.getElementById('abc_source');
if (! sourceField) {
return;
}
var abc = sourceField.value;
if (! abc) {
return;
}
var abcDE = new AbcDE();
abcDE.renderUI({output:'append',
preset:'first',
restore:'always',
validate:'complete',
qualtrics:this});
return true;
});
</script>
Finally, add Text questions with HTML formatted like the following:
<textarea id="abc_source" style="display:none;">
% abcDidactyl v5
% abcD fingering 1: 35xx3x2x15xx3x2x@xxxx
% Authority: Carl Czerny (1839)
% Transcriber: David Randolph
% Transcription date: 2016-01-22 12:58:01
% Test of Qualtrics integration.
% abcDidactyl END
X:3
T:A
C:Czerny
M:C
L:1/16
Q:"Allegro"
K:C
V:1 treble
V:2 treble
V:1
!p!egfg efde cc'bc' abga|]
V:2
[GC]4 z4 [GE]4 z4|]
</textarea>
<div id="abcde"</div>
Here the exercise displayed in the survey (thanks to the preset:'first' option to abcDE.renderUI()) would be initialized to the "fingering 1" abcDF specification. Results would be written to the abcD_3 and abcDF_3 embedded data elements, as dictated by the X:3 setting in the "abc_source" input.
Renders an abc Didactyl Editor within the DIV element with ID "abcde" on the page.
Assumes such a DIV exists on the page.
Accepts a hash of arguments to determine the specific behaviors of the editor, as specified below.
Allow user to select a file from the local file system to edit. Defaults to false.
Include the Transcriber and Authority names in the abcD content returned through the JavaScript API. By default, such information is suppressed.
Control how fingering data entered by the user is recorded in any saved or viewed abcD content. A new fingering block may be appended to the abcD block, or it may replace the fingering block used to initiate the session.
If not specified, defer to user preference.
Parse any input abcD content and load either the first fingering sequence specified or the last sequence. If not specified, defer to user preference on the matter.
Allow the user to browse different fingering sequences specified in an abcD input file. Defaults to false.
Configure editor to be used with the Qualtrics survey tool.
Display a BACK button in Qualtrics to navigate to prior questions. Defaults to false.
Determine when previously entered work saved by the browser should be restored. If ask is specified, prompt user to learn if data should be restored.
If not specified, defer to user preference.
(If integrating with Qualtrics, set to always both to ensure that data is retained and to avoid multiple prompts from being issued. Qualtrics appears to be doing some reloading of content under the covers.)
Initialize the editor with the abc content provided at the specified URL.
Allow the user to load abc content from a URL to edit. Defaults to false.
Control how fingering input is validated. A complete validation requires that a fingering be provided for each note (pitch) in the input abc. An automatic validation first applies heuristics in an attempt to infer a complete fingering.
If not specified, no validation is performed.
Returns the "Authority" responsible for the entered fingering. Returns the empty string unless include_pii is set to true.
Returns user's entered comments about entered fingering data.
Returns the fingering data entered by the user as a string.
Returns the complete abcD file, including the user's fingering data.
Returns the "Transcriber" responsible for the entered fingering. Returns the empty string unless include_pii is set to true.
Returns the fingering data as a string if and only if the requested validation is successful. Alerts user to the validation problem and returns an empty string if the validation fails.
Returns the complete abcD file, including the user's fingering data, if and only if the requested validation is successful. Alerts user to the validation problem and returns an empty string if the validation fails.
Returns the ID of the X (tune identifier) field from the input abc string. Convenient for distinguishing exercises posed in Qualtrics.