From a508f993cba28a028abb86861d38862d03188f97 Mon Sep 17 00:00:00 2001
From: isisadmin <isislab.unisa@gmail.com>
Date: Fri, 2 Oct 2015 02:15:12 +0200
Subject: [PATCH] added datalet documentation

---
 datalets/barchart-datalet/barchart-datalet.html           |  56 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 datalets/column3Dchart-datalet/column3Dchart-datalet.html |  57 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
 datalets/columnchart-datalet/columnchart-datalet.html     |  51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 datalets/leafletjs-datalet/leafletjs-datalet.html         | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------------
 datalets/linechart-datalet/linechart-datalet.html         |  52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 datalets/treemap-datalet/treemap-datalet.html             |  24 ++++++++++++++++++++++++
 6 files changed, 306 insertions(+), 49 deletions(-)

diff --git a/datalets/barchart-datalet/barchart-datalet.html b/datalets/barchart-datalet/barchart-datalet.html
index b11e095..4495f4d 100755
--- a/datalets/barchart-datalet/barchart-datalet.html
+++ b/datalets/barchart-datalet/barchart-datalet.html
@@ -1,14 +1,57 @@
+<!--
+The MIT License (MIT)
+
+Copyright (c) 2015 ROUTE-TO-PA CONSORTIUM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
 <link rel="import" href="../../bower_components/polymer/polymer.html">
 <link rel="import" href="../highcharts-datalet/highcharts-datalet.html">
 
+<!--
+
+`barchart-datalet` is a barchart datalet based on highcharts project <http://www.highcharts.com/>
+
+Example:
+
+<barchart-datalet data-url="http://ckan.routetopa.eu/api/action/datastore_search?resource_id=73e02092-85a1-434e-85fe-0c9a43aa9a52&amp;limit=10000"
+                  query="$['result']['records'][*]['Lat']###$['result']['records'][*]['Lng']">
+
+
+-->
+
 <dom-module name="barchart-datalet">
     <template>
         <highcharts-datalet id="charts" data-url="{{dataUrl}}" query="{{query}}" fields-order="{{fieldsOrder}}"></highcharts-datalet>
     </template>
     <script>
         var BarchartBehavior = {
+
+
+            /**
+             * Bluid Highchart object
+             *
+             * @method transformData
+             */
             transformData: function(){
-                //Bluid Highchart element
+
                 $(this._component.$.charts.$.container).highcharts({
                     chart: {
                         type: 'bar',
@@ -18,7 +61,7 @@
                         text: 'Bar chart'
                     },
                     xAxis: {
-                        categories: this.properties.categories.value,//this._component.categories,
+                        categories: this.properties.categories.value,
                         title: {
                             text: null
                         }
@@ -57,13 +100,20 @@
                     credits: {
                         enabled: false
                     },
-                    series: this.properties.series.value//this._component.series
+                    series: this.properties.series.value
                 });
             }
         };
 
         BarchartDatalet = Polymer({
             is: 'barchart-datalet',
+
+            /**
+             * 'ready' callback extend the BarchartComponentBehavior with HighchartsComponentBehavior and BarchartBehavior
+             * and run the Datalet workcycle.
+             *
+             * @method ready
+             */
             ready: function(){
 
                 var BarchartComponentBehavior = $.extend(true, {}, HighchartsComponentBehavior, BarchartBehavior);
diff --git a/datalets/column3Dchart-datalet/column3Dchart-datalet.html b/datalets/column3Dchart-datalet/column3Dchart-datalet.html
index e0efbbe..d6ef961 100755
--- a/datalets/column3Dchart-datalet/column3Dchart-datalet.html
+++ b/datalets/column3Dchart-datalet/column3Dchart-datalet.html
@@ -1,10 +1,45 @@
+<!--
+The MIT License (MIT)
+
+Copyright (c) 2015 ROUTE-TO-PA CONSORTIUM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
+
 <link rel="import" href="../../bower_components/polymer/polymer.html">
 <link rel="import" href="../highcharts-datalet/highcharts-datalet.html">
-
-<link rel="import" href="../../bower_components/iron-ajax/iron-ajax.html">
 <script src="http://code.highcharts.com/highcharts-3d.js"></script>
 
 
+<!--
+
+`column3Dchart-datalet` is a column3Dchart datalet based on highcharts project <http://www.highcharts.com/>
+
+Example:
+
+<column3dchart-datalet data-url="http://ckan.routetopa.eu/api/action/datastore_search?resource_id=73e02092-85a1-434e-85fe-0c9a43aa9a52&amp;limit=10000"
+                       query="$['result']['records'][*]['Lat']###$['result']['records'][*]['Lng']">
+
+
+-->
+
 
 <dom-module name="column3Dchart-datalet">
 
@@ -22,12 +57,14 @@
 
         var column3DchartBehavior = {
 
-
+            /**
+             * Bluid Highchart object
+             *
+             * @method transformData
+             */
             transformData: function(){
-                         //Bluid Highchart element
                          chart = new Highcharts.Chart({
                              chart: {
-                                 //To Modify renderTo: 'container',
                                  renderTo: this._component.$.charts.$.container,
                                  borderColor: '#EBBA95',
                                  borderWidth: 2,
@@ -44,7 +81,7 @@
                                  }
                              },
                              xAxis: {
-                                 categories: this.properties.categories.value,//this._component.categories,
+                                 categories: this.properties.categories.value,
                                  title: {
                                      text: null
                                  }
@@ -62,7 +99,7 @@
                              },
 
                      series: this.properties.series.value
-                });//highcharts
+                });
 
                 // Activate the sliders
                 $('#R0').on('change', function () {
@@ -81,6 +118,12 @@
         column3DchartDatalet = Polymer({
             is: 'column3Dchart-datalet',
 
+            /**
+             * 'ready' callback extend the column3DchartComponentBehavior with HighchartsComponentBehavior and column3DchartBehavior
+             * and run the Datalet workcycle.
+             *
+             * @method ready
+             */
             ready: function(){
                 var column3DchartComponentBehavior = $.extend({}, HighchartsComponentBehavior, column3DchartBehavior);
                 column3DchartComponentBehavior.properties = $.extend({}, HighchartsComponentBehavior.properties, column3DchartBehavior.properties);
diff --git a/datalets/columnchart-datalet/columnchart-datalet.html b/datalets/columnchart-datalet/columnchart-datalet.html
index 7a17220..1d2c17d 100755
--- a/datalets/columnchart-datalet/columnchart-datalet.html
+++ b/datalets/columnchart-datalet/columnchart-datalet.html
@@ -1,14 +1,56 @@
+<!--
+The MIT License (MIT)
+
+Copyright (c) 2015 ROUTE-TO-PA CONSORTIUM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
 <link rel="import" href="../../bower_components/polymer/polymer.html">
 <link rel="import" href="../highcharts-datalet/highcharts-datalet.html">
 
+<!--
+
+`columnchart-datalet` is a columnchart datalet based on highcharts project <http://www.highcharts.com/>
+
+Example:
+
+<columnchart-datalet data-url="http://ckan.routetopa.eu/api/action/datastore_search?resource_id=73e02092-85a1-434e-85fe-0c9a43aa9a52&amp;limit=10000"
+                     query="$['result']['records'][*]['Lat']###$['result']['records'][*]['Lng']">
+
+
+-->
+
 <dom-module id="columnchart-datalet">
     <template>
         <highcharts-datalet id="charts" data-url="{{dataUrl}}" query="{{query}}" fields-order="{{fieldsOrder}}"></highcharts-datalet>
     </template>
     <script>
         var ColumnchartBehavior = {
+
+
+            /**
+             * Bluid Highchart object
+             *
+             * @method transformData
+             */
             transformData: function(){
-                //Bluid Highchart element
                 $(this._component.$.charts.$.container).highcharts({
                     chart: {
                         type: 'column',
@@ -64,6 +106,13 @@
 
         LinechartDatalet = Polymer({
             is: 'columnchart-datalet',
+
+            /**
+             * 'ready' callback extend the ColumnchartComponentBehavior with HighchartsComponentBehavior and ColumnchartBehavior
+             * and run the Datalet workcycle.
+             *
+             * @method ready
+             */
             ready: function(){
                 var ColumnchartComponentBehavior = $.extend(true, {}, HighchartsComponentBehavior, ColumnchartBehavior);
                 ColumnchartComponentBehavior.init(this);
diff --git a/datalets/leafletjs-datalet/leafletjs-datalet.html b/datalets/leafletjs-datalet/leafletjs-datalet.html
index ab74fb1..158da81 100755
--- a/datalets/leafletjs-datalet/leafletjs-datalet.html
+++ b/datalets/leafletjs-datalet/leafletjs-datalet.html
@@ -1,5 +1,41 @@
+<!--
+The MIT License (MIT)
+
+Copyright (c) 2015 ROUTE-TO-PA CONSORTIUM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
 <link rel="import" href="../base-datalet/base-datalet.html">
 
+<!--
+
+`leafletjs-datalet` is a map datalet based on open source project leafletjs <http://leafletjs.com/>
+
+Example:
+
+<leafletjs-datalet data-url="http://ckan.routetopa.eu/api/action/datastore_search?resource_id=73e02092-85a1-434e-85fe-0c9a43aa9a52&amp;limit=10000"
+                   query="$['result']['records'][*]['Lat']###$['result']['records'][*]['Lng']###$['result']['records'][*]['Link']">
+
+
+-->
+
 <dom-module name="leafletjs-datalet">
     <template>
         <link rel="stylesheet" href="leafletsjs/leaflet.css" />
@@ -16,25 +52,18 @@
 
     <script>
 
-        $(document).ready(function(){
-/*            var map = L.map("leafletjs").setView([51.505, -0.09], 13);
-
-            L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
-                maxZoom: 18,
-                attribution: 'Map data © <a href="http://openstreetmap.org">OpenStreetMap</a> contributors'
-            }).addTo(map);*/
-        });
-
-
         var leafletjsBehavior = {
 
+            /**
+             * Extract all the data from the dataset according to the queries.
+             *
+             * @method selectData
+             */
             selectData: function(){
 
                 var queries =  this._component.query.split("###");
 
-                for (i = 0; i < queries.length; i++) {
-                        /*propsName = queries[i].split(".");
-                        var propName = "" + propsName[propsName.length - 1];*/
+                for (var i = 0; i < queries.length; i++) {
                         var propName = this.getPropertyName(queries[i]);
 
                         temp = jsonPath(this.properties.json_results.value, queries[i]);
@@ -47,6 +76,12 @@
                }
             },
 
+            /**
+             * Read markers coordinates from the data object and add the marker to the map.
+             * Call a method for the map redraw and set the viewport in order to fit all the markers in the viewport.
+             *
+             * @method transformData
+             */
             transformData: function(){
             	            	             
 				var coordinates = [];
@@ -70,36 +105,25 @@
         Polymer({
 
             is : 'leafletjs-datalet',
-            ready: function(){
-
-				this.map = L.map(this.$.leafletjs).setView([0, 0], 13);
-                //this.map = L.map("leafletjs").setView([0, 0], 13);
-
-                L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
-                    maxZoom: 18,
-                    attribution: 'Map data © <a href="http://openstreetmap.org">OpenStreetMap</a> contributors'
-                }).addTo(this.map);
-
-                L.Icon.Default.imagePath = 'http://services.routetopa.eu/DEEalerProvider/COMPONENTS/datalets/leafletjs-datalet/leafletsjs/images';
-
-                var leafletjsComponentBehavior =  $.extend(true, {}, BaseDataletBehavior, WorkcycleBehavior, AjaxJsonDataRequestBehavior, leafletjsBehavior);
-                leafletjsComponentBehavior.init(this);
-            },
-
-            attached : function(){
-
-
-
-            },
 
             properties : {
 
+                /**
+                 * Store a reference to the leafletjs map object created in 'ready' callback
+                 * @attribute map
+                 * @type Object
+                 */
                 map :
                 {
                     type: Object,
                     value:null
                 },
 
+                /**
+                 * An Array with all the markers extracted from the dataset
+                 * @attribute markers
+                 * @type Array
+                 */
                 markers :
                 {
                     type : Array,
@@ -107,10 +131,27 @@
                 }
             },
 
-            log : function(item){
-                console.log(item);
-            }
+            /**
+             * 'ready' callback create the map object, set the tileLayer to openstreetmap and the default icon image path.
+             * Moreover extend the leafletjsComponentBehavior with BaseDataletBehavior, WorkcycleBehavior and leafletjsBehavior
+             * and run the Datalet workcycle.
+             *
+             * @method ready
+             */
+            ready: function(){
+
+				this.map = L.map(this.$.leafletjs).setView([0, 0], 13);
+
+                L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
+                    maxZoom: 18,
+                    attribution: 'Map data © <a href="http://openstreetmap.org">OpenStreetMap</a> contributors'
+                }).addTo(this.map);
 
+                L.Icon.Default.imagePath = 'http://services.routetopa.eu/DEEalerProvider/COMPONENTS/datalets/leafletjs-datalet/leafletsjs/images';
+
+                var leafletjsComponentBehavior =  $.extend(true, {}, BaseDataletBehavior, WorkcycleBehavior, AjaxJsonDataRequestBehavior, leafletjsBehavior);
+                leafletjsComponentBehavior.init(this);
+            }
         });
     </script>
 </dom-module>
diff --git a/datalets/linechart-datalet/linechart-datalet.html b/datalets/linechart-datalet/linechart-datalet.html
index c203aea..202136c 100755
--- a/datalets/linechart-datalet/linechart-datalet.html
+++ b/datalets/linechart-datalet/linechart-datalet.html
@@ -1,14 +1,57 @@
+<!--
+The MIT License (MIT)
+
+Copyright (c) 2015 ROUTE-TO-PA CONSORTIUM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
 <link rel="import" href="../../bower_components/polymer/polymer.html">
 <link rel="import" href="../highcharts-datalet/highcharts-datalet.html">
 
+<!--
+
+`linechart-datalet` is a linechart datalet based on highcharts project <http://www.highcharts.com/>
+
+Example:
+
+<linechart-datalet data-url="http://ckan.routetopa.eu/api/action/datastore_search?resource_id=73e02092-85a1-434e-85fe-0c9a43aa9a52&amp;limit=10000"
+                   query="$['result']['records'][*]['Lat']###$['result']['records'][*]['Lng']">
+
+
+-->
+
 <dom-module id="linechart-datalet">
     <template>
         <highcharts-datalet id="charts" data-url="{{dataUrl}}" query="{{query}}" fields-order="{{fieldsOrder}}"></highcharts-datalet>
     </template>
     <script>
         var LinechartBehavior = {
+
+
+            /**
+             * Bluid Highchart object
+             *
+             * @method transformData
+             */
             transformData: function(){
-                //Bluid Highchart element
+
                 $(this._component.$.charts.$.container).highcharts({
                     title: {
                         text: 'Line chart'
@@ -56,6 +99,13 @@
 
         LinechartDatalet = Polymer({
             is: 'linechart-datalet',
+
+            /**
+             * 'ready' callback extend the LinechartComponentBehavior with HighchartsComponentBehavior and LinechartBehavior
+             * and run the Datalet workcycle.
+             *
+             * @method ready
+             */
             ready: function(){
                 var LinechartComponentBehavior = $.extend(true, {}, HighchartsComponentBehavior, LinechartBehavior);
                 LinechartComponentBehavior.init(this);
diff --git a/datalets/treemap-datalet/treemap-datalet.html b/datalets/treemap-datalet/treemap-datalet.html
index 6cd3cf7..0120059 100755
--- a/datalets/treemap-datalet/treemap-datalet.html
+++ b/datalets/treemap-datalet/treemap-datalet.html
@@ -1,3 +1,27 @@
+<!--
+The MIT License (MIT)
+
+Copyright (c) 2015 ROUTE-TO-PA CONSORTIUM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+-->
+
 <link rel="import" href="../../bower_components/polymer/polymer.html">
 <link rel="import" href="../base-datalet/base-datalet.html">
 
--
libgit2 0.21.4