Annotate topic.html
authorJason Skomorowski <jason@indexdata.com>
Tue, 4 Nov 2014 20:29:47 +0000 (15:29 -0500)
committerJason Skomorowski <jason@indexdata.com>
Tue, 4 Nov 2014 20:29:47 +0000 (15:29 -0500)
examples/htdocs/topic.html

index 34bf452..0c727e1 100644 (file)
@@ -4,6 +4,8 @@
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>MKWS demo</title>
+
+  <!-- Include Bootstrap. It needs jQuery. -->
   <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> 
   <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
   <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
   <!-- <link href="//maxcdn.bootstrapcdn.com/bootswatch/3.1.1/amelia/bootstrap.min.css" rel="stylesheet"> -->
   <!-- <link href="//maxcdn.bootstrapcdn.com/bootswatch/3.1.1/united/bootstrap.min.css" rel="stylesheet"> -->
   <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
+
+  <!-- Before including MKWS we can define a configuration object. -->
   <script type="text/javascript">
     var mkws_config = { sp_auth_credentials: "credo/emu" };
   </script>
+
+  <!-- mkws-complete.js includes jQuery and Handlebars. It will co-exist with
+       another copy of jQuery as we have here but you can also use mkws.js
+       if you have included both separately -->
   <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
   <link rel="stylesheet" type="text/css" href="topic.css">
+
+  <!-- Handlebars templates can make calls to Javascript functions you
+       define this way. -->
   <script>
     Handlebars.registerHelper('mkws-topicurl', function(topic) {
       /* Creates a link back to this page with the topic as a parameter */
       return window.location.pathname + "?q=" + encodeURIComponent(topic);
     });
   </script>
+
+  <!-- Here we create replacement templates that incorporate bootstrap. 
+       The prefix "mkws-template-" makes them available to MKWS -->
   <script class="mkws-template-topic-image" type="text/x-handlebars-template">
     {{#each hits}}
       <div class="col-lg-3 col-md-4 col-sm-6 col-xs-12">
     {{/each}}
   </script>
 </head>
+
 <body>
-  <div class='page-header container' autosearch='!param!q'>
+  <div class='page-header container'>
     <div class="row">
-      <!-- reference entry -->
+      <!-- mkws-reference - A widget that fetches a Wikipedia entry -->
       <div class="jumbotron panel col-md-8 col-sm-7">
+        <!-- Note the "autosearch" attribute. It indicates where to get
+             the search term from, in this case a URL parameter.  A URL
+             path component or Javascript variable are also possible. --> 
         <div class="panel-body mkws-reference mkws-team-ref" autosearch="!param!q"
              data-mkws-config='{"paragraphs":1}'></div>
       </div>
-      <!-- related topics -->
+      <!-- Related topics -->
       <div class="col-md-offset-1 col-md-3 col-sm-5"><div class="panel panel-default">
         <div class="panel-heading title">
           <h3 class="panel-title">Related Topics</h3>
         </div>
+        <!-- This mkws-facet widget is particularly illustrative: 
+             * the data-mkws-facet attribute specifies a particular facet
+             * data-mkws-config allows configuration override; in this case
+               we employ one of the templates we defined above.
+             * having the class mkws-team-main groups this widget with others
+               on the same team. The mkws-records widget at the bottom of
+               the page shares the same team and is thus working from the same
+               result set. -->
         <ul class="panel-body list-group mkws-facet mkws-team-main"
             autosearch="!param!q"
             data-mkws-facet="subject"
@@ -70,6 +96,7 @@
         <div class="panel-heading title">
           <h3 class="panel-title">Images</h3>
         </div>
+        <!-- The "target" config key narrows the search to a list of targets -->
         <div class="panel-body mkws-google-image" autosearch="!param!q"
              data-mkws-config='{ "maxrecs": 4, "template": "topic-image", "target": "google_images_js" }'></div>
       </div></div>
           <div class="panel-heading title">
             <h3 class="panel-title">News</h3>
           </div>
+          <!-- The "targetfilter" narrows the search to targets matching some criteria -->
           <div class="panel-body mkws-records mkws-team-news" autosearch="!param!q"
                data-mkws-config='{"targetfilter":"categories=news",
                                   "perpage":7}'></div>