Code cleanup and comments. Syntax highlighting performance improvements.
authorManu Sporny <msporny@digitalbazaar.com>
Sat, 09 Jul 2011 10:16:23 -0400
changeset 57 4e6d5b24ea22
parent 56 610e29eef20f
child 58 d8a4246fc82f
Code cleanup and comments. Syntax highlighting performance improvements.
playground/index.html
playground/jsonld-turtle.js
playground/lang-jsonld.js
playground/lang-turtle.js
playground/playground-examples.js
playground/playground.css
playground/playground.js
playground/prettify.css
--- a/playground/index.html	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/index.html	Sat Jul 09 10:16:23 2011 -0400
@@ -2,12 +2,7 @@
  "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> 
 <html version="XHTML+RDFa 1.0" xmlns="http://www.w3.org/1999/xhtml"
    xmlns:xhv="http://www.w3.org/1999/xhtml/vocab#"
-   xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
-   xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
-   xmlns:dcterms="http://purl.org/dc/terms/"
-   xmlns:vcard="http://www.w3.org/2006/vcard/ns#"
-   xmlns:v="http://rdf.data-vocabulary.org/#"
-   > 
+   xmlns:dcterms="http://purl.org/dc/terms/"> 
    <head> 
       <meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> 
       <title>The JSON-LD Playground</title> 
@@ -32,7 +27,7 @@
       <div id="container"> 
          <div id="header"> 
             <div class="col"> 
-               <h1>The JSON-LD Playground</h1>
+               <h1 property="dcterms:title">The JSON-LD Playground</h1>
             </div> 
          </div> 
  
@@ -105,7 +100,7 @@
  
          <div id="footer"> 
             <p id="copyright"> 
-               Website content released under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution Share-Alike license</a> except where an alternate is specified.
+               Website content released under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution Share-Alike license</a> except where an alternate is specified.
             </p> 
             <p id="legal"> 
                Part of the <a href="http://payswarm.com/">payswarm.com</a> initiative.
--- a/playground/jsonld-turtle.js	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/jsonld-turtle.js	Sat Jul 09 10:16:23 2011 -0400
@@ -1,5 +1,5 @@
 /**
- * Javascript implementation of TURTLE output for JSON-LD.
+ * Javascript implementation of TURTLE output for JSON-LD Forge project.
  *
  * @author Manu Sporny
  *
@@ -7,12 +7,22 @@
  */
 (function()
 {
+// reference to the forge JSON-LD processor
 var jsonld = forge.jsonld;
 
+/**
+ * Retrieves all of the properties that are a part of a JSON-LD object, 
+ * ignoring the "@" special character.
+ *
+ * @param obj the JSON-LD object - the last part of the triple.
+ *
+ * @return an array of cleaned keys for the JSON-LD object.
+ */
 function getProperties(obj)
 {
    var rval = [];
 
+   // accumulate the names of all non-JSON-LD special keys
    for(var key in obj)
    {
       if(key != "@")
@@ -24,16 +34,34 @@
    return rval;
 };
 
+/**
+ * Checks to see if the passed in IRI is a Blank Node.
+ *
+ * @param iri the IRI to check.
+ *
+ * @return true if the iri is a Blank Node, false otherwise.
+ */
 function isBnode(iri)
 {
    var bnodePrefix = "_:";
+   
    return (iri.substring(0, bnodePrefix.length) === bnodePrefix);
 };
 
+/**
+ * Converts an IRI to TURTLE format. If it is a regular scheme-based IRI,
+ * angle brackets are placed around the value, otherwise, if the value is
+ * a Blank Node, the value is used as-is.
+ *
+ * @param iri the IRI to convert to TURTLE format.
+ *
+ * @return the TURTLE-formatted IRI.
+ */
 function iriToTurtle(iri)
 {
    var rval = undefined;
 
+   // place angle brackets around anything that is not a Blank Node
    if(isBnode(iri))
    {
       rval = iri;
@@ -46,12 +74,21 @@
    return rval;
 };
 
-function printObject(obj)
+/**
+ * Converts the 'object' part of a 'subject', 'property', 'object' triple 
+ * into a text string.
+ *
+ * @param obj the object to convert to a string.
+ *
+ * @return the string representation of the object.
+ */
+function objectToString(obj)
 {
    var rval = undefined;
 
    if(obj instanceof Array)
    {
+      // if the object is an array, convert each object in the list
       var firstItem = true;
       for(i in obj)
       {
@@ -64,11 +101,12 @@
          {
             rval += ",\n      ";
          }
-         rval += printObject(obj[i]);
+         rval += objectToString(obj[i]);
       }
    }
    else if(obj instanceof Object)
    {
+      // the object is an IRI, typed literal or language-tagged literal
       if("@literal" in obj && "@datatype" in obj)
       {
          rval = "\"" + obj["@literal"] + "\"^^<" + obj["@datatype"] + ">";
@@ -85,12 +123,20 @@
    }
    else
    {
+      // the object is a plain literal
       rval = "\"" + obj + "\"";
    }
 
    return rval;
 };
 
+/**
+ * Converts JSON-LD input to a TURTLE formatted string.
+ *
+ * @param input the JSON-LD object as a JavaScript object.
+ *
+ * @return a TURTLE formatted string.
+ */
 jsonld.turtle = function(input)
 {
    var normalized = jsonld.normalize(input);
@@ -98,6 +144,7 @@
 
    for(s in normalized)
    {
+      // print out each key in the normalized array (the subjects)
       var subject = normalized[s];
       var iri = subject["@"]["@iri"];
 
@@ -111,15 +158,18 @@
       var count = numProperties;
       for(p in properties)
       {
+         // serialize each property-object combination
          property = properties[p];
-         rval += "   <" + property + "> " + printObject(subject[property]);
+         rval += "   <" + property + "> " + objectToString(subject[property]);
 
          if(count == 1)
          {
+            // if the item is the last item for this subject, end it with a '.'
             rval += ".\n";
          }
          else
          {
+            // if the item is the last item for this subject, end it with a ';'
             rval += ";\n";
          }
          count -= 1;
--- a/playground/lang-jsonld.js	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/lang-jsonld.js	Sat Jul 09 10:16:23 2011 -0400
@@ -1,6 +1,6 @@
 /**
  * @fileoverview
- * Registers a language handler for JSON-LD.
+ * Registers a language handler for prettify.js for JSON-LD.
  *
  * @author David I. Lehn <[email protected]>
  */
--- a/playground/lang-turtle.js	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/lang-turtle.js	Sat Jul 09 10:16:23 2011 -0400
@@ -1,9 +1,9 @@
 /**
  * @fileoverview
- * Registers a language handler for TURTLE.
+ * Registers a language handler for prettify.js for TURTLE.
  *
+ * @author David I. Lehn <[email protected]>
  * @author Manu Sporny <[email protected]>
- * @author David I. Lehn <[email protected]>
  */
 
 PR.registerLangHandler(
--- a/playground/playground-examples.js	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/playground-examples.js	Sat Jul 09 10:16:23 2011 -0400
@@ -1,14 +1,18 @@
 /**
- * The JSON-LD Sandbox is used to test out JavaScript 
+ * The JSON-LD Playground example files.
+ *
+ * @author Manu Sporny <[email protected]>
  */
 (function($)
 {
    window.playground = window.playground || {};
    var playground = window.playground;
+   
+   // setup the examples and frame examples
    playground.examples = {};
    playground.frames = {};
 
-   // Add the example of a Person
+   // add the example of a Person
    playground.examples["Person"] =
    {
       "name": "Manu Sporny",
@@ -25,7 +29,7 @@
       }
    };
 
-   // Add the example of a Place
+   // add the example of a Place
    playground.examples["Place"] =
    {
       "name": "The Empire State Building",
@@ -53,7 +57,7 @@
       }
    };
 
-   // Add the example of a Event
+   // add the example of a Event
    playground.examples["Event"] =
    {
       "ical:summary": "Lady Gaga Concert",
@@ -70,7 +74,7 @@
       }
    };
 
-   // Add the example of a Product
+   // add the example of a Product
    playground.examples["Product"] =
    {
       "@": "http://example.org/cars/for-sale#tesla",
@@ -104,7 +108,7 @@
       }
    };
 
-   // Add the example of a Recipe
+   // add the example of a Recipe
    playground.examples["Recipe"] =
    {
       "name": "Mojito",
@@ -151,7 +155,7 @@
       }
    };
 
-   // Add the example of a Library
+   // add the example of a Library
    playground.examples["Library"] =
    {
       "@": [
@@ -174,8 +178,10 @@
             "dc:title": "The Introduction"
          }
       ],
-      "@context": {
-         "@coerce": {
+      "@context": 
+      {
+         "@coerce": 
+         {
             "xsd:anyURI": "ex:contains"
          },
          "dc": "http://purl.org/dc/elements/1.1/",
@@ -183,17 +189,20 @@
       }
    };
 
-   // Add the example of a Library
+   // add the frame example of a Library
    playground.frames["Library"] =
    {
-      "@context": {
+      "@context": 
+      {
          "dc": "http://purl.org/dc/elements/1.1/",
          "ex": "http://example.org/vocab#"
       },
       "a": "ex:Library",
-      "ex:contains": {
+      "ex:contains": 
+      {
          "a": "ex:Book",
-         "ex:contains": {
+         "ex:contains": 
+         {
             "a": "ex:Chapter"
          }
       }
--- a/playground/playground.css	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/playground.css	Sat Jul 09 10:16:23 2011 -0400
@@ -1,3 +1,6 @@
+/**
+ * Styling for the JSON-LD playground UI.
+ */
 textarea:focus, input:focus {
    border: 2px solid #900;
 }
--- a/playground/playground.js	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/playground.js	Sat Jul 09 10:16:23 2011 -0400
@@ -1,15 +1,34 @@
 /**
  * The JSON-LD playground is used to test out JavaScript Object Notation 
  * for Linked Data.
+ *
+ * @author Manu Sporny <[email protected]>
  */
 (function($)
 {
+   // create the playground instance if it doesn't already exist
    window.playground = window.playground || {};
    var playground = window.playground;
-
-   playground.htmlEscape = function (s) 
+   
+   // set the active tab to the compacted view
+   playground.activeTab = "tab-compacted";
+   
+   // the counter is used to throttle colorization requests in milliseconds
+   playground.colorizeDelay = 500;
+   
+   // the colorize timeout is used to keep track of the timeout object of the
+   // colorize delay
+   playground.colorizeTimeout = null;
+   
+   /**
+    * Escapes text that will affect HTML markup.
+    *
+    * @param text the string to re-encode as HTML.
+    */
+   playground.htmlEscape = function(text) 
    {
-      return s.replace(/([&<>])/g, function (c) {
+      // replace each special HTML character in the string
+      return text.replace(/([&<>])/g, function (c) {
          return "&" + {
              "&": "amp",
              "<": "lt",
@@ -18,6 +37,9 @@
       });
    }
 
+   /**
+    * Used to initialize the UI, call once a document load.
+    */
    playground.init = function()
    {
       $("#tabs").tabs();
@@ -25,26 +47,46 @@
       $("#tabs").bind("tabsselect", playground.tabSelected);
    };
 
+   /**
+    * Callback for when tabs are selected in the UI.
+    *
+    * @param event the event that fired when the tab was selected.
+    * @param ui the ui tab object that was selected
+    */
    playground.tabSelected = function(event, ui)
    {
+      playground.activeTab = ui.tab.id;
       if(ui.tab.id == "tab-framed")
       {
+         // if the 'frame' tab is selected, display the frame input textarea
          $("#markup").addClass("compressed");
          $("#frame").show();
       }
       else
       {
+         // if the 'frame' tab is not selected, hide the frame input area
          $("#frame").hide();
          $("#markup").removeClass("compressed");
       }
+      
+      // perform processing on the data provided in the input boxes
+      playground.process();
+      
+      // apply the syntax colorization
+      prettyPrint();
    };
 
+   /**
+    * Process the JSON-LD markup that has been input and display the output
+    * in the active tab.
+    */
    playground.process = function()
    {
       var input = null;
       var frame = null;
       var errors = false;
 
+      // check to see if the JSON-LD markup is valid JSON
       try
       {
          $("#markup-errors").text("");
@@ -56,6 +98,7 @@
          errors = true;
       }
 
+      // check to see if the JSON-LD frame is valid JSON
       try
       {
          $("#frame-errors").text("");
@@ -67,46 +110,108 @@
          errors = true;
       }
 
+      // if there are no errors, perform the action and display the output
       if(!errors)
       {
-         var normalized = forge.jsonld.normalize(input);
-         var expanded = forge.jsonld.removeContext(input);
-         var compacted = forge.jsonld.changeContext(
-            input["@context"] || {}, input);
-         var framed = forge.jsonld.frame(input, frame);
-         var turtle = forge.jsonld.turtle(input);
+         if(playground.activeTab == "tab-normalized")
+         {
+            var normalized = forge.jsonld.normalize(input);
+            $("#normalized").html(js_beautify(JSON.stringify(normalized)),
+               { "indent_size": 3, "brace_style": "expand" });
+         }
+         else if(playground.activeTab == "tab-expanded")
+         {
+            var expanded = forge.jsonld.removeContext(input);
+            $("#expanded").html(js_beautify(JSON.stringify(expanded)),
+               { "indent_size": 3, "brace_style": "expand" });
+         }
+         else if(playground.activeTab == "tab-compacted")
+         {
+            var compacted = forge.jsonld.changeContext(
+               input["@context"] || {}, input);
+            $("#compacted").html(js_beautify(JSON.stringify(compacted)),
+               { "indent_size": 3, "brace_style": "expand" });
+         }
+         else if(playground.activeTab == "tab-framed")
+         {
+            var framed = forge.jsonld.frame(input, frame);
+            $("#framed").html(js_beautify(JSON.stringify(framed)),
+               { "indent_size": 3, "brace_style": "expand" });
+         }
+         else if(playground.activeTab == "tab-turtle")
+         {
+            var turtle = forge.jsonld.turtle(input);
+            $("#turtle").html(playground.htmlEscape(turtle));
+         }
+      }
+      
+      // Start the colorization delay
+      playground.checkColorizeDelay(true);
+   }
 
-         $("#normalized").html(js_beautify(JSON.stringify(normalized)),
-            { "indent_size": 3, "brace_style": "expand" });
-         $("#compacted").html(js_beautify(JSON.stringify(compacted)),
-            { "indent_size": 3, "brace_style": "expand" });
-         $("#expanded").html(js_beautify(JSON.stringify(expanded)),
-            { "indent_size": 3, "brace_style": "expand" });
-         $("#framed").html(js_beautify(JSON.stringify(framed)),
-            { "indent_size": 3, "brace_style": "expand" });
-         $("#turtle").html(playground.htmlEscape(turtle));
-
+   /**
+    * Performs a check on the colorize delay. If the delay hits 0, the
+    * markup is colorized.
+    *
+    * @param reset true if the colorization timeout should be reset
+    */
+   playground.checkColorizeDelay = function(reset)
+   {
+      // if the counter reset flag is set, reset the counter
+      if(reset)
+      {
+         playground.colorizeDelay = 500;
+      }
+      else
+      {
+         playground.colorizeDelay -= 250;
+      }
+      
+      if(playground.colorizeDelay <= 0)
+      {
+         // if the delay has expired, perform colorization
          prettyPrint();
       }
-   }
-   
-   playground.populate = function(type)
+      else
+      {
+         // if the delay has not expired, continue counting down
+         if(playground.colorizeTimeout)
+         {
+            clearTimeout(playground.colorizeTimeout);
+         }
+         playground.colorizeTimeout = 
+            setTimeout(playground.checkColorizeDelay, 250);
+      }
+   };
+
+   /**
+    * Callback when an example button is clicked.
+    *
+    * @param name the name of the example to pre-populate the input boxes.
+    */
+   playground.populate = function(name)
    {
-      if(type in playground.examples)
+      if(name in playground.examples)
       {
-         $("#markup").val(js_beautify(JSON.stringify(playground.examples[type]),
+         // fill the markup box with the example
+         $("#markup").val(js_beautify(JSON.stringify(playground.examples[name]),
             { "indent_size": 3, "brace_style": "expand" }));
          $("#frame").val("{}");
 
-         if(type in playground.frames)
+         if(name in playground.frames)
          {
+            // fill the frame input box with the example frame
             $("#frame").val(js_beautify(
-               JSON.stringify(playground.frames[type]),
+               JSON.stringify(playground.frames[name]),
                { "indent_size": 3, "brace_style": "expand" }));
          }
       }
 
+      // perform processing on the data provided in the input boxes
       playground.process();
+
+      // apply the syntax colorization
+      prettyPrint();
    };
 
 })(jQuery);
--- a/playground/prettify.css	Sat Jul 09 00:06:21 2011 -0400
+++ b/playground/prettify.css	Sat Jul 09 10:16:23 2011 -0400
@@ -84,6 +84,7 @@
     font-size: 0.8em;
     font-weight: bold;
     background: #000;
+    color: #ddd;
     overflow: auto;
 }
 li.L0, li.L1, li.L2, li.L3, li.L4, li.L5, li.L6, li.L7, li.L8, li.L9