Documents module compliance

ptrdo · ptrdo · commit d2d133dddfaa · 2018-02-09T15:38:25.000-08:00
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
-#### This is pre-release software. Use at your own risk. 
-# microdata-template
+###### This is released software. Please **[log issues](https://github.com/ptrdo/microdata-template/issues)** found. 
+# microdata-template `v2.0.0`
 An implementation of HTML template by way of the microdata mechanism.
 ### The Gist  
 This JavaScript module should simplify adding dynamic content to HTML documents while staying true to the recommendations of web standards. There are no dependencies here except the JavaScript [ECMA5 standard](http://www.ecma-international.org/ecma-262/5.1/) which enjoys [nearly universal support](http://kangax.github.io/compat-table/es5/) in modern browsers. Also, since the HTML recommendations for integral technologies such as [template](https://www.w3.org/TR/html52/semantics-scripting.html#the-template-element) and [microdata](https://www.w3.org/TR/microdata/) are variably implemented by modern browsers, this module serves as a [polyfill](https://en.wikipedia.org/wiki/Polyfill) to assure reliable results. Best of all, this methodology encourages the writing of low-dependency JavaScript and perfectly valid HTML &mdash; even within fully-functional templated markup.
@@ -11,7 +11,8 @@ This JavaScript module should simplify adding dynamic content to HTML documents
 <script src="./lib/microdata-template.js"></script>
 <script>
   document.addEventListener("DOMContentLoaded", function() {
-    var templater = new MicrodataTemplate();
+    var templater = window.MicrodataTemplate.init();
+    console.log("MicrodataTemplate!", templater.getVersion());
   });
 </script>
 ```
@@ -39,7 +40,7 @@ var data = [{
     "Url": "/about"
 }];
 
-var templater = new MicrodataTemplate();
+var templater = window.MicrodataTemplate.init();
     templater.render(document.getElementById("example"), data); 
 ```
 
@@ -77,51 +78,43 @@ var templater = new MicrodataTemplate();
 
 ***
 ### Advanced Usage
-Alternatively, the module can be assigned to a discrete namespace: 
-```html
-<script>
-  this.PTRDO = { utils: {} };
-  this.exports = PTRDO.utils;
-</script>
-<script src="./lib/microdata-template.js"></script>
-<script>
-  document.addEventListener("DOMContentLoaded", function() {
-    var templater = new PTRDO.utils.MicrodataTemplate();
-  });
-</script>
-```
-This module is organized to be attached to an HTML document as a simple external script, but also in a project governed by [Asynchronous Module Definition](https://en.wikipedia.org/wiki/Asynchronous_module_definition) (AMD) with a library such as [RequireJS](https://github.com/requirejs/requirejs), or a [CommonJS](https://en.wikipedia.org/wiki/CommonJS) project governed by a framework such as [NodeJS](https://en.wikipedia.org/wiki/Node.js). The expectations are the same, but the syntax used to load, instantiate, and then address the module will be as a local reference rather than a window namespace.
+This module is organized to be attached to an HTML document as a simple external script (see: [Simple Usage](https://github.com/ptrdo/microdata-template#simple-usage)), but also in a project governed by [Asynchronous Module Definition](https://en.wikipedia.org/wiki/Asynchronous_module_definition) (AMD) with a library such as [RequireJS](https://github.com/requirejs/requirejs), or an [ES6-compliant](http://es6-features.org/) project bundled by a library such as [Webpack](https://webpack.js.org/). The expectations are the same, but the syntax used to load, instantiate, and then address the module may be slightly different depending on circumstance.
 
-**AMD (RequireJS) Implementation:**
+**Old-fashioned AMD (RequireJS) Implementation:**
 ```javascript
 require.config({
-   paths: { auth: "/path/to/idmorg-auth"},
-   shim: { auth: { exports: "auth" }}
+  paths: {
+    text: "./node_modules/requirejs-text/text",
+    json: "./node_modules/requirejs-json/json",
+  }
 });
-
-define(["auth"], function(Auth) {
-    Auth.init({
-        applicationName: "SomeAppName",
-        endpoint: "https://comps-dev.idmod.org/api/",
-        parentElement: someDOMElement
-    });
-
-    Auth.signout();
+define(
+[
+  "./path/to/microdata-template.js",
+  "json!./path/to/collection.json"
+],
+function(templater, collection) {
+  
+  var render = function(rootElement) {
+    var templateElement = rootElement.querySelector("TR[itemscope]");
+    templater.render(templateElement, collection);
+  }
 });
 ```
-**CommonJS (NodeJS) Implementation:**
+**New-fangled ES6 Module Implementation:**
 ```javascript
-import Auth from "path/to/idmorg-auth.js";
-
-$(function() {
-    Auth.init({
-        applicationName: "SomeAppName",
-        endpoint: "https://comps-dev.idmod.org/api/",
-        parentElement: someDOMElement
-    });
-
-    Auth.signout();
-});
+import templater from "./path/to/microdata-template.js";
+import collection from "./path/to/data/collection.json";
+
+class Example {
+  
+  render(rootElement=document) {
+    let templateElement = rootElement.querySelector("TR[itemscope]");
+    templater.render(templateElement, collection);
+  };
+}
+
+export default Example;
 ```
 
 ***
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,45 @@
+###### This is released software. Please **[log issues](https://github.com/ptrdo/microdata-template/issues)** found. 
+# Examples of microdata-template
+These samples demonstrate implementations of the microdata-template utility for rendering a variety of data to an HTML page. Clone this project and then follow the instructions (below) which are most-appropriate for application.
+
+*** 
+### simple-javascript
+This example includes HTML documents which can be run directly in a web browser. A web server (or localhost) is recommended for demonstrating complete functionality in real-world circumstance, but is not required. All links are relative, including to the data sources and the microdata-template library.
+
+***
+### minimal-requirejs
+This example demonstrates integration into a minimal [Asynchronous Module Definition](https://en.wikipedia.org/wiki/Asynchronous_module_definition) (AMD) project governed by the [RequireJS](https://github.com/requirejs/requirejs) library. An enclosed `package.json` designates all dependencies required for running the demonstration. 
+
+[Yarn](https://yarnpkg.com/) is an excellent choice for managing packages for web clients and can be [installed a variety of ways](https://yarnpkg.com/en/docs/install). Alternatively, the Node Package Manager ([NPM](https://www.npmjs.com/get-npm)) can also be used.
+
+**1:** From a command prompt, navigate to the project path where the clone of this repository is installed, and then the path where the relevant `package.json` file exists.
+```sh
+> cd C:\path\to\microdata-template\example\minimal-requirejs
+```
+**2:** From a command prompt, run the Yarn `install` command to get the dependencies as prescribed in the `package.json` file. This will create a path local to this example `\node_modules` for deposit of the downloaded code. 
+```sh
+> yarn install
+```
+**3:** The file to run is `\minimal-requirejs\www\index.html`. A `localhost` or other webserver will be required for the page to import all runtime components and then render without error. One convenient means is use an Integrated Development Environment (IDE) such as JetBrain's [WebStorm](https://www.jetbrains.com/webstorm/) or [IntelliJ](https://www.jetbrains.com/idea/) which can open these files for review and edit and then run them in its internal webserver. 
+
+***
+### minimal-webpack
+This example demonstrates integration into a minimal [ES6-compliant](http://es6-features.org/) project bundled by the [Webpack](https://webpack.js.org/) library. An enclosed `package.json` designates all dependencies required for running the demonstration.
+
+[NodeJS](https://nodejs.org/en/download/) is a technology which can execute scripts on a computer. In this application, NodeJS fasciliates the Webpack framework in assembling the various ingredients of the Client code, preparing them for deployment to a browser. It will be necessary to install NodeJS to run these examples. 
+
+The Node Package Manager ([NPM](https://www.npmjs.com/get-npm)) is installed as a component of NodeJS and is a popular means for executing the `package.json` of a project.
+
+**1:** From a command prompt, navigate to the project path where the clone of this repository is installed, and then the path where the relevant `package.json` file exists.
+```sh
+> cd C:\path\to\microdata-template\example\minimal-webpack
+```
+**2:** From a command prompt, run the NPM `install` command to get the dependencies as prescribed in the `package.json` file. This will create a path local to this example `\node_modules` for deposit of the downloaded code. 
+```sh
+> npm install
+```
+**3:** From a command prompt, run the NPM `start` command which has been configured in the `webpack.config.js` to instruct Webpack to survey the dependencies prescribed in the project code and then compile the bundled JavaScript.  
+```sh
+> npm start
+```
+**4:** Open a browser and navigate to `http://localhost:8080` to view the deployed code. Note: If this does not work, there may be a conflict with other processes, so th `8080` port can be changed by [configuring the devServer](https://webpack.js.org/configuration/dev-server/).
diff --git a/example/simple-javascript/array.html b/example/simple-javascript/array.html
@@ -108,8 +108,8 @@
     // This code will use the data provided here to populate a form.
     // Run this in a browser, and be sure to view the rendered source!
 
-    var templater = window.MicrodataTemplate;
-    var templateElement = document.getElementsByTagName("DD")[0];
+    var templater = window.MicrodataTemplate.init();
+    var templateElement = document.querySelector("DD[hidden]");
 
     var months = [
       "janvier",
diff --git a/example/simple-javascript/collection.html b/example/simple-javascript/collection.html
@@ -55,7 +55,7 @@
     // This code will load an adjacent data file and use it to draw a table.
     // Run this in a browser, and be sure to view the rendered source!
 
-    var templater = window.MicrodataTemplate;
+    var templater = window.MicrodataTemplate.init();
     var templateBody = document.getElementsByTagName("TBODY")[0].getElementsByTagName("TR")[0];
 
     var ajax = function(endpoint, options, callback) {
@@ -88,7 +88,7 @@
       request.send();
     };
 
-    ajax("data/collection.json", null, function(data){
+    ajax("../data/collection.json", null, function(data){
 
       if ("StatePopulations" in data) {
         templater.render(templateBody, data["StatePopulations"]);
diff --git a/example/simple-javascript/form.html b/example/simple-javascript/form.html
@@ -44,7 +44,7 @@
     // This code will use the data provided here to populate a form.
     // Run this in a browser, and be sure to view the rendered source!
 
-    var templater = window.MicrodataTemplate;
+    var templater = window.MicrodataTemplate.init();
     var templateElement = document.getElementsByTagName("FORM")[0];
 
     var info = {
diff --git a/example/simple-javascript/multiple.html b/example/simple-javascript/multiple.html
@@ -3,7 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <title>Microdata Template: Example: Multiple Renders</title>
-  <script src="../lib/microdata-template.js" crossorigin="anonymous"></script>
+  <script src="../../lib/microdata-template.js" crossorigin="anonymous"></script>
   <style>
     body {
       font-family: monospace;
@@ -48,7 +48,7 @@
   // This code will use the sample data here to draw two aspects of a table.
   // Run this in a browser, and be sure to view the rendered source!
 
-  var templater = window.MicrodataTemplate;
+  var templater = window.MicrodataTemplate.init();
   var templateHead = document.getElementsByTagName("THEAD")[0].getElementsByTagName("TH")[0];
   var templateBody = document.getElementsByTagName("TBODY")[0].getElementsByTagName("TR")[0];
 
diff --git a/example/simple-javascript/object.html b/example/simple-javascript/object.html
@@ -49,7 +49,7 @@
     // This code will access the browser's navigator object and use it to draw a table.
     // Run this in a browser, and be sure to view the rendered source!
 
-    var templater = window.MicrodataTemplate;
+    var templater = window.MicrodataTemplate.init();
     var templateElement = document.getElementsByTagName("TBODY")[0].getElementsByTagName("TR")[0];
 
     templater.getSetShowHeritage(true);
diff --git a/example/simple-javascript/transformer.html b/example/simple-javascript/transformer.html
@@ -56,7 +56,7 @@ <h5 itemprop="screen_name">@{{ concat:user.screen_name }} tweeted:</h5>
     // Also, a custom transformer is employed for special formatting of date values.
     // Run this in a browser, and be sure to view the rendered source!
 
-    var templater = window.MicrodataTemplate;
+    var templater = window.MicrodataTemplate.init();
     var templateElement = document.getElementsByTagName("BLOCKQUOTE")[0];
 
     var ajax = function(endpoint, options, callback) {
@@ -89,7 +89,7 @@ <h5 itemprop="screen_name">@{{ concat:user.screen_name }} tweeted:</h5>
       request.send();
     };
 
-    ajax("data/transformer.json", null, function(data) {
+    ajax("../data/transformer.json", null, function(data) {
 
       templater.setTransformer("formatDate", function(value, index) {
         var time = Date.parse(value);
diff --git a/lib/microdata-template.js b/lib/microdata-template.js
@@ -8,31 +8,32 @@
    * @author Peter Sylwester
    * @copyright (c)2018 Peter Sylwester
    * @license MIT
-   * @version 1.02, 2018/01/02
+   * @version 2.00, 2018/02/09
    * @requires "HTML5", "ECMA-262 Edition 5.1"
    *
-   * AMD (RequireJS) IMPLEMENTATION:
    *
-   *   require.config({
-   *     paths: { templater: "/path/to/microdata-template"},
-   *     shim: { templater: { exports: "Templater" }}
-   *   });
+   * ES6-COMPLIANT IMPLEMENTATION:
+   *
+   *   import templater from "./path/to/microdata-template.js";
    *
-   *   define(["templater"], function(Templater) {
-   *     Templater.render(someHTMLElement, someData);
+   *   $(function() {
+   *     templater.render(someHTMLElement, someCorrespondingData);
    *   });
    *
    *
-   * CommonJS (NodeJS) IMPLEMENTATION
+   * AMD IMPLEMENTATION (RequireJS):
    *
-   *   import Templater from "path/to/microdata-template.js";
+   *   require.config({
+   *     paths: { templater: "./path/to/microdata-template"},
+   *     shim: { templater: { exports: "templater" }}
+   *   });
    *
-   *   $(function() {
-   *     Templater.render(someHTMLElement, someData);
+   *   define(["templater"], function(templater) {
+   *     templater.render(someHTMLElement, someCorrespondingData);
    *   });
    *
    *
-   * BROWSER IMPLEMENTATION
+   * ECMA-262 IMPLEMENTATION:
    *
    *   <script type="text/javascript" src="./path/to/microdata-template.js"></script>
    *
@@ -43,14 +44,16 @@
    */
 
   var namespace = "MicrodataTemplate";
-  typeof exports === "object" && typeof module !== "undefined" ? module.exports = factory() :
-      typeof define === "function" && define.amd ? define([], factory) :
-          (root[namespace] = factory());
+  typeof exports === "object" && typeof module !== "undefined"
+    ? module.exports = factory()
+    : typeof define === "function" && "amd" in define
+        ? define([], factory)
+        : ((root||window)[namespace] = factory());
 
 }(this, (function () {
   "use strict";
 
-  var element, source;
+  var element, source, version = "2.0.0";
 
   /**
    * Markers are the HTML node element attributes used to designate components of the templated markup.
@@ -656,12 +659,15 @@
     },
 
     getElement: function () {
-
       return element;
     },
 
     getTransformers: function () {
       return TRANSFORMER;
+    },
+
+    getVersion: function () {
+      return version;
     }
   };
 })));
