JavaScript Development Annotation

JavaScript coding can be fun. Until you run into an elusive bug.

Notations to help find and fix bugs while coding JavaScript generally can be done with (not a comprehensive list):

• Alert boxes containing the notation,
• Updating a div's content with the notation, or
• Using document.write() to print the notation.

But those aren't always appropriate. An example is when the site is live and interrupting someone's use of the page would be undesirable.

If the time required to transfer the JavaScript to a testing page is unacceptable, then you're stuck.

Until now.

The debugging system presented here lets you publish annotations without interrupting current users on the page. The annotations are stored in a file on the server.

In other words, instead of annotating on the web page itself, the annotations are stored in a file on the server.

The annotations may be variable names and values, loop counts, or other information — whatever may reveal what you need to know for debugging or making coding decisions for your project.

This is how the system works:

1. At points within the JavaScript (where variables or other information you want to know more about are located), you send data to a JavaScript relay function.

2. The JavaScript relay function uses Ajax to send your annotation to a PHP script on the server.

3. The PHP script appends the annotation to a file.

We'll take the above in reverse order — because the PHP script is required for the Ajax code to send the annotation to, and the Ajax code is required to receive an annotation.

The PHP Script for JavaScript Annotations

Here is the source code of the PHP Script. No customization is required.

<?php
/* JavaScript Annotations
   Version 1.0
   September 12, 2020
   Will Bontrager Software LLC
   https://www.willmaster.com/
*/
if( isset($_POST['filename']) and isset($_POST['annotation']) )
{
   file_put_contents($_POST['filename'],"{$_POST['annotation']}\n",FILE_APPEND);
}
exit;
?>

Save the above source code as jsnotes.php or other appropriate *.php file name. The instructions in this article will assume the jsnotes.php file name.

Upload jsnotes.php to your server and make a note of its URL.

The Ajax Function for JavaScript Annotations

Below is the source code for the Ajax function, which is the JavaScript function that will send your annotations to jsnotes.php located on your server. The Ajax function has one customization, addressed below the source code, and followed with an installation note.

<script>
function Annotate(filename,annotation)
{
   var url = "/php/jsnotes.php"; // Location of PHP annotation file updating script.
   var http = new XMLHttpRequest();
   if(! http) { return; }
   var params = new Array();
   params.push( "filename=" + encodeURIComponent(filename) );
   params.push( "annotation=" + encodeURIComponent(annotation) );
   http.onreadystatechange = function(){}
   http.open("POST",url,true);
   http.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
   http.send(params.join("&"));
}
</script>

At the third line of JavaScript in the above code, you'll see the /php/jsnotes.php value for the url variable.

Replace /php/jsnotes.php with the relative URL to your installation of the jsnotes.php script.

The relative URL would be the URL to jsnotes.php minus the leading protocol and domain name parts. Thus, URL https://example.com/php/jsnotes.php would become /php/jsnotes.php as a relative URL.

Insert the the Ajax function for JavaScript annotations into the web page that you are debugging. It can be anywhere on the page. Immediately above the </body> tag is a good place.

Using JavaScript Annotations

Now, with the PHP script on the server and the Ajax function on the page, you can make annotations.

An annotation is set up by inserting a line of JavaScript into your code. When the JavaScript runs, that line will send your annotation to the Ajax function, which will send it to the PHP script jsnotes.php on your server. The PHP script will store your annotation in a file.

The code format for making an annotation is:

Annotate("[FILENAME]","[ANNOTATION]");

Put the Annotate() function where the variable or other item is located that you want to save information about:

1. Replace [FILENAME] with the file name to store the annotation. If the file exits, the annotation will be appended.

   Probably all of your annotations will be to the same file name. If you wish, certain annotations can be specified for one file name and other annotations for another file.

2. Replace [ANNOTATION] with your annotation.

   Annotation examples are below.

Here is a simple example. The variable result that will be stored is the value of 2 multiplied by 6. Then an annotation is made of the value stored in the result variable.

var result = 2 * 6;
Annotate("file.txt","result="+result);

With the above, then when the JavaScript runs the annotation will look like this in the file.txt file.

result=12

This next example is a loop that iterates 11 times, counting from 0 through 10.

A variable total is initialized with value 0. At each iteration, the iteration value (variable i) is multiplied by itself and the sum added to the total variable.

The annotation is the iteration value and the value of the total variable.

var total = 0;
for( var i=0; i<=10; i++ )
{
   total += i * i;
   Annotate("file.txt","i="+i+" and total="+total);
}

With the above, when the JavaScript runs, the annotation looks something like this in the file.txt file. See the note further below about annotation order in the file.

i=0 and total=0
i=1 and total=1
i=2 and total=5
i=3 and total=14
i=4 and total=30
i=5 and total=55
i=6 and total=91
i=7 and total=140
i=8 and total=204
i=9 and total=285
i=10 and total=385

When the JavaScript runs and annotations are sent to the PHP script jsnotes.php in rapid succession, they might not always be saved in the file in the same order as you sent them.

The reason is that every annotation that is sent causes a new Ajax sequence and launches the PHP script anew. Some launchings may take a bit longer than others, letting a subsequent annotation arrive before the one sent an intant earlier. The process speed depends on how busy your computer is at that very second, the speed and resources of your server, and the reliability of the internet.

Thus, the annotations for the above example loop might infrequently appear out of order in your annotation file. As an example, they might be something like this, with the i=6… and i=7… lines reversed.

i=0 and total=0
i=1 and total=1
i=2 and total=5
i=3 and total=14
i=4 and total=30
i=5 and total=55
i=7 and total=140
i=6 and total=91
i=8 and total=204
i=9 and total=285
i=10 and total=385

You now have a system to publish annotations related to your JavaScript code to a file on the server without interrupting current users of the web page. The annotations can be any information that may assist your project.

(This article first appeared with an issue of the Possibilities newsletter.)

Will Bontrager