“JavaScript Endnotes” Instructions

What they are
How they work
Pros and cons
Note to users of version 1

What they are

“JavaScript Endnotes” allow a web author to create an HTML document containing endnotes which are dynamically renumbered as new notes are added, in a similar manner to the <NOTE> tag supported in many WIKI applications. The document may be divided into as many sections as desired, each with its own independently-numbered set of notes. Notice that the accompanying demo contains two such sections.

The two required files are the JavaScript file and the CSS file, downloadable from the main page. Details of the display can be easily altered by anyone with a little knowledge of HTML. No knowledge of JavaScript is required.

For anyone with a little experience of hand-coding HTML, “JavaScript Endnotes” are relatively easy to use and customize. For HTML documents which require frequent revision, they make the handling of endnotes almost as easy as in a desktop Word-processing application, and avoid the need for moving back-and-forth between a word-processed version of a document and an HTML version, which can cause character-conversions and other problems. If you like what you see in the demo, I recommend creating a small trial project using “JavaScript Endnotes” to see if they are right for you.

Around 2002 I developed a script similar to this, except that it is processed server-side (using ColdFusion Markup Language or CFML). I still use it regularly and have found it valuable for many projects, some of them coded from scratch and others converted from older word-processed documents. For example, my very long page on The Harris family of Sandy Cove, which contains over 300 endnotes, was originally a WordPerfect file and has been drastically reformatted on several occasions without any manual renumbering of notes, or having to be revised in anything other than a text editor.

For some time, I have hoped to develop a version of the endnote script which posed no server requirements and would be platform-independent. The present implementation is a first attempt at that goal. Strictly speaking, it does not even require access to a web server, because if the files are required only for personal use, they can be accessed from a local drive. I therefore hope it will be useful to those with access only to an HTML server, but also to group projects where there is shared creation of files and not everyone on the team is able to upload files to a web server.

How they work

In what follows, it is assumed that the required JavaScript file and CSS file just mentioned are residing in the same directory as the file in which the “JavaScript Endnotes” are to be used. Experienced web-developers can easily rewrite the references in the files to point at some other directory if desired.

The document should have a structure something like the following excerpt from the source-code for the demo file (with all code pertaining to the endnotes highlighted):


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Javascript Endnotes demonstration</title>
<!-- links to other style sheets may be placed here if desired -->
<link rel=stylesheet href="endnoteStyle.css" TYPE="text/css">
</head>
<body>

<h1>Javascript Endnotes demonstration</h1>

<noscript>
JavaScript must be enabled for this page to display correctly.
</noscript>

<div class="endnoteBlock">

<p>
<b>Thomas Baxter</b>, of Mansfield, Nottinghamshire, was b. 1784-85 in
Nottinghamshire, and was still alive in 1851. He m. by 1807, <b>Anne ____</b>,
b. 1790-91 (aged 50 in 1841, 60 in 1851) in Nottinghamshire, still alive in 1851.
They are enumerated in the 1841 census of Mansfield, in which Thomas is called a
wood sawyer.<span class="endnote">1841 Census of England, Nottinghamshire,
registration district: Mansfield, subdistrict: Mansfield, enumeration district 3,
pp. 21-22; PRO HO107/859/2, folios 14v, 15r.</span> They are enumerated in the
1851 census, in which he is called a labourer, and it is mentioned that he was
deaf, and blind in one eye.<span class="endnote">1851 Census of England,
Nottingamshire, registration district: Mansfield, subdistrict: Mansfield,
enumeration district 1j, p. 27; PRO HO107, piece 2124, folio
212.</span>
</p>

<script type="text/javascript" src="endnotePlacement.js"></script>

</div>


<div class="endnoteBlock">

<p>
<b>John Jarratt</b>, of Brightside, Ecclesall Bierlow, b. probably in 1813,
between April and November,<span class="endnote">The various reports of
John Jaratt&rsquo;s age we have found are consistent with one another, and taken
together, imply a date of birth between April 1813 and Nov. 1813.</span>
</p>

<script type="text/javascript" src="endnotePlacement.js"></script>

</div>

</body>
</html>

The rules of construction are simple:

The CSS file (endnoteStyle.css) must be linked to somewhere in the file (customarily in the HEAD).
The <noscript>…</noscript> tagset is there as a courtesy to those using JavaScript-disabled browsers, but it isn’t really required.
a <div class="endnoteBlock">…</div> tagset is optionally used to mark each section of the document which is to have an independently-numbered block of endnotes.
if no <div class="endnoteBlock">…</div> tagset is present, all notes are treated as belonging to a single group.
a <script type="text/javascript" src="endnotePlacement.js"></script> tagset is placed at the end (but inside of) each block, or at the end of the document (but inside the BODY tag), at the point where the endnotes are to be generated.
a <span class="endnote">…</span> tagset is placed in the text at each point where a number pointing at an endnote is to appear.
Any additional CSS, SCRIPT or span tagsets, or other HTML, may be used wherever desired, providing it does not cause naming conflicts with the above.

Pros and cons

“JavaScript Endnotes” have some features which I hope will make them appealing to a wide variety of users:

Ease of coding: As mentioned, little knowledge of HTML is required to use this script, and the only tool needed to process the files is a text editor. After the initial setup is complete, the work involved in adding new notes to a file is negligible. All work can be previewed from a local drive; in fact if it is not intended for publication it need never be uploaded to a web server at all.
Ease of upgrading: The script is DOM-based and there is no reason to anticipate that browser support for it will ever diminish (in fact, it is more likely to improve). The JS and CSS files are external to the text files to facilitate version-control, and any necessary upgrades in the future can be easily implemented.
Ease of collaboration: A group of web authors all using this script could combine their work at any time in the process without risk of endnotes falling out of alignment with the text. Provided the script is used correctly, it is impossible for an endnote to become mismatched with a number in the text, no matter how much it is moved.
For advanced users: The script is well-suited to the automated concatenation of files. Furthermore, the tag-based markup required to support this script is by nature database-safe. Thus, unless a database-driven application is specifically designed to strip HTML tags out of field input, a document can be broken into suitable pieces, stored in a database, and reassembled without affecting its capability of being processed to generate endnotes, provided that the resulting page also includes the required SCRIPT tag(s) in the appropriate location(s).
For developers: As per the Creative Commons Licence linked to at the bottom of this page, provided appropriate credit is given and the source-material is not used for commercial gain without permission, developers may incorporate these scripts in web applications or software, or adapt them as desired.

However, no warantee whatsoever is made or implied for this script, and there are a few specific caviats which must be acknowledged in order to avoid possible disappointment:

Browser requirements: The browser must have JavaScript enabled, and support the innerHTML property. The <noscript>…</noscript> tagset should serve as sufficient notice to those using JavaScript-disabled browsers, but the message could be elaborated if desired (for example, with a link to instructions for how to restore JavaScript). Presumably the vast majority of users who have JavaScript turned off have some specific reason for having done so, and know how to restore it. But if the audience for your pages is more likely than average (about 6% of users) to have JavaScript disabled, the use of this script may not be appropriate.
Structural requirements of files: Although the script has been tested in a variety of scenarios and is believed to be quite robust, it cannot be guaranteed to work in files which are not well-formed HTML; for example pages containing multiple BODY tags, or pages with nesting errors or bleeding tags.
CSS: Because the <div class="endnoteBlock">…</div> tagsets are block-level elements (which is necessary in order that they may contain other block-level elements), these div tags will interrupt the style of elements (such as paragraphs) in which they are contained. Thus, if using styles, special case has to be taken to ensure that these containers will inherit the appropriate style from their own parent(s), such as the BODY tag. Thus for example if a style is applied to P tags sitting directly inside the body of an existing document, and these P tags contain endnotes, the style should be transferred to the BODY tag.
Investing in a new file format: Because the content of the notes must be interspersed throughout the text rather than gathered together at the end of a document (or at the end of a section of a document), there may initially be a considerable amount of manipulation required to convert older files to the required format, and the process is essentially a one-way trip. If this script generates sufficient interest, I will flesh out these instructions and add some suggestions as to how best to accomplish such conversions. In the meantime — and I cannot emphasize this enough — you should retain copies of all documents in their original format in case you change your mind about using the script.
Editing of files: Few if any existing WYSIWYG HTML editors will render the document in the intended manner. Documents using “JavaScript Endnotes” can (with the usual reservations) be edited in such applications, but the contents of the notes will be displayed in their original locations in the text, not as actual endnotes.
Rendering of files: With version 1 of this script, unwanted line breaks sometimes appeared before the note numbers. It is believed that this problem has been corrected in version 2.
Archiving of files: Because the script rewrites the document’s HTML on-the-fly, the resulting rebuilt document has only a transient existence. As rendered by the web brower, it can be printed (including printed to PDF), and it can be copied and pasted into other applications (for example MS Word or MS Wordpad) with no more loss of formatting than for any other HTML. However, the rendered version cannot be saved. Thus, for example, the “Edit with Microsoft Office Word” feature in Internet Explorer doesn’t work because Word is fed the raw HTML and linked JavaScript of the original file. This situation could conceivably improve if future web browers were to add a “save-as-rendered” feature, but for now, I know no way of saving a flattened version of the file as pure HTML. If archiving of files is important to the project and PDFs aren’t sufficient, this script is probably not an option.
Accessibility: The same reservations described above with respect to saving the resulting file apply to text-reading devices, which would see the raw HTML and linked JavaScript of the original file. The page would, in effect, contain in-text citations (perhaps quite long) labelled as endnotes. The situation is not unprecendented because the HTML CITE tag can be used for in-text citations, although presumably not for very long ones. It would be presumptuous of me to speculate as to how this would affect the experience of a visually-impaired person in using the page, and I would welcome actual response on this matter.

Note to users of version 1

Version 1 of this script used <div class="endnote">…</div> where this version uses <span class="endnote">…</span>. HTML files written using version 1 need only this one change to be made, and they will work with the new endnotePlacement.js and endnoteStyle.css files.

John Blythe Dobson
University of Winnipeg Library
Released 25 May 2007
Suggestions welcome

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License.