Merge pull request #80 from FieldStudiesCouncil/rel-1.9

Release 1.9.0

CHANGELOG.md

@@ -4,7 +4,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/) 
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [Unreleased]
+<!-- ## [Unreleased] -->
+## [1.9.0] - 2019-09-15
+### Added
+ - Deals intelligently with missing data. The Identikit is now much more robust in how
+ it deals with missing data. In fact it will now operate with only a taxa.csv file. This
+ makes it much easier to learn how to use the Identikit 
+ [issue 61](https://github.com/FieldStudiesCouncil/tombiovis/issues/61).
+### Fixed
+The following bugs evident in version 1.9-alpha were fixed:
+
+ - [Issue 77](https://github.com/FieldStudiesCouncil/tombiovis/issues/77).
+ - [Issue 65](https://github.com/FieldStudiesCouncil/tombiovis/issues/65).
+
+The following bugs evident in version 1.8.1 were fixed:
+ - [Issue 66](https://github.com/FieldStudiesCouncil/tombiovis/issues/66).
+ - [Issue 61](https://github.com/FieldStudiesCouncil/tombiovis/issues/61).
+ - [Issue 60](https://github.com/FieldStudiesCouncil/tombiovis/issues/60).
+ - [Issue 57](https://github.com/FieldStudiesCouncil/tombiovis/issues/57).
+ - [Issue 53](https://github.com/FieldStudiesCouncil/tombiovis/issues/53).
+ - [Issue 52](https://github.com/FieldStudiesCouncil/tombiovis/issues/52).
+ - [Issue 49](https://github.com/FieldStudiesCouncil/tombiovis/issues/49).
+ - [Issue 48](https://github.com/FieldStudiesCouncil/tombiovis/issues/48).
+ - [Issue 47](https://github.com/FieldStudiesCouncil/tombiovis/issues/47).
+### Changed
  - Updated .gitignore and .gitattributes to prevent unecessary files from gulp minifying workflow being deployed to Git or included in the releases.
 ## [1.8.2] - 2018-11-14
 ### Changed

README.md

@@ -1,10 +1,12 @@
 # The FSC Identikit
 
-**We now have a forum: https://forum.fscbiodiversity.uk/c/identikit.
+**We now have a [forum](https://forum.fscbiodiversity.uk/c/identikit).
 Join us there to ask for help using Identikit, help with creating
 resources, discuss features, bugs, or anything else related to the
 software.**
 
+To get started quickly, follow our [Quickstart Guide](docs/quickstart.md).
+
 The FSC Identikit is a framework for creating online biological
 identification resources, including multi-access keys. The genesis of
 the project was the Field Studies Council's (FSC) Tomorrow's
@@ -19,6 +21,19 @@ collaborative venture.
 (Prior to March 2018, The FSC Identikit was referred to as 'The Tom.bio
 ID Visualisation Framework', or variations thereof.)
 
+## Try it out
+
+Try the software out:
+* With the [standard interface](https://fieldstudiescouncil.github.io/tombiovis/identikit/vis.html).
+* With the [mobile interface](https://fieldstudiescouncil.github.io/tombiovis/identikit/vism.html).
+
+## Developers
+The repostitory can be cloned thus: ```git clone https://github.com/FieldStudiesCouncil/tombiovis.git```.
+
+If the clone fails, try the following: ```git clone https://github.com/FieldStudiesCouncil/tombiovis.git --depth 1 --no-single-branch```.
+
+The second git command clones the repostiory with a truncated history. This should be fine for most purposes.
+
 ## Documentation
 
 All documentation for this project is found in the 'documentation'
@@ -35,5 +50,12 @@ sub-folder and includes the following:
 * Notes for coders (only for programmers who want to extend or
   contribute to the Identikit)
 
-An interactive guide to the Identikit is available here:
-https://www.fscbiodiversity.uk/identikit
+We are also working on moving the documentation online so that it will be available here. Currently the following is available:
+
+* [Quickstart Guide](docs/quickstart.md)
+
+## Other information
+
+* [Change log](CHANGELOG.md)
+* [Release notes](ReleaseNotes.md)
+* [Support](SUPPORT.md)

ReleaseNotes.md

@@ -1,6 +1,12 @@
 # Release notes for existing knoweldge-base developers
 These notes are intended to help existing knowledge-base developers move from one version of the FSC Identikit to another. These notes were first released with version 1.7.0 of the Identikit and will be updated on each succeeding release.
 
+## Release 1.9.0
+The main feature of this new release is that Identikit is much more resilient to missing data
+in knolwedge-bases; so much so that it will now work on a knowledge-base which consists
+solely of a taxa.csv file. This makes it easier to start learning how to use. It is also more resilient to differences in case, e.g. BodyColour in taxa worksheet will now match bodycolour
+in characters worksheet.
+
 ## Release 1.8.2
 Release 1.8.2 addresses some minor issues evident when people deploy resources, particularly to CMS and also set the pwaSupress flag to true so that, by default, service worker does not kick in during knowledge-base development (which causes confusing caching issues). No implications for knowledge-base deveopers.
 

_config.yml

@@ -0,0 +1,4 @@
+theme: jekyll-theme-slate
+title: The FSC Identikit
+description: Tools for building online interactive ID resources 
+  for biological identification, driven by spreadsheets of knowledge.

docs/quickstart.md

@@ -0,0 +1,24 @@
+## FSC Identikit Quickstart
+
+To get up and running with Identikit, follow these steps:
+
+>1. Install <https://nodejs.org> on your computer.
+>2. Download the [latest version of Identikit](https://github.com/FieldStudiesCouncil/tombiovis/releases). Follow the link and download the latest '**Source code (zip)**'.
+>3. Unzip the downloaded zip file ```tombiovis-n.n.n.zip``` to any convenient location on your computer.
+>4. Using your usual file explorer tools, open the folder ```tombiovis-n.n.n/tombiovis-n.n.n```.
+>5. Open a Windows 'command window' by double-clicking the ```start.bat``` file (non-Windows users see note below).
+>6. In the command window, type ```npm install``` and hit enter.
+>7. In the command window, type ```npm start``` and hit enter.
+
+Non-Windows users will probably not be able to run the  ```start.bat``` file in step 5. Instead open whatever the equivalent command or terminal window is on your operating system and then continue from step 6.
+
+Step 6 is a one-off step to configure NodeJS for the Identikit. Subsequently, all you have to do to start the Identikit is repeat steps 5 and 7. You must leave the 'command window' open whilst Identikit runs, but you can minimise it if you like.
+
+>If you have an existing a knowledge-base, just move or copy the entire folder into the ```tombiovis-n.n.n/tombiovis-n.n.n/identikit/kb``` folder. 
+
+That's all - no need to edit any HTML files. Links to use your knowledge-base - both with standard and mobile interfaces - will appear when you start Identikit. 
+
+>If you are starting from scratch, just copy and rename the entire ```biscuits``` knowledge-base folder in the aforementioned ```kb``` folder and start modifying the Excel spreadsheet within.
+
+## More help
+For a more detailed guide to getting started and other detailed documentation, consult the PDFs in the ```tombiovis-n.n.n/identikit/documentation``` folder.

identikit/kb/biscuits/config.csv

@@ -6,8 +6,9 @@ authors,metadata,yes,"Bell, C.",,
 publisher,metadata,no,Field Studies Council,,
 location,metadata,no,"Preston Montford, Shrewsbury",,
 contact,metadata,no,,,
-version,metadata,yes,1.8.0,,
+version,metadata,yes,1.9.0,,
 #Releases - keep track of the release history below this line. Most recent releases at the top. The version code in the 'value' column below this line should match that of the current release above it.,,,,,
+release,history,no,1.9.0,9/15/2019,Minor changes.
 release,history,no,1.8.0,10/24/2018,Minor changes.
 release,history,no,1.7.1,6/1/2018,Minor fix to add new media fields.
 release,history,no,1.7,6/1/2018,Modified by RB to complement version 1.7.0 release of Identikit.

identikit/sw.js

@@ -1,6 +1,6 @@
 //See comments at the end of description of caching strategy
 
-var cacheno = 8;
+var cacheno = 9;
 var kbCacheName = "tombio-kb-cache-" + cacheno;
 var kbImgStdCacheName = "tombio-kb-img-std-cache-" + cacheno;
 var kbImgSmlCacheName = "tombio-kb-img-sml-cache-" + cacheno;

identikit/tombio/guiLarge.js

@@ -125,7 +125,7 @@
         //The option *values* mediaFilesCheck & tvkCheck have software-wide meaning, not just this gui
         if (tbv.opts.checkKB) {
             toolOptions.push($('<option value="mediaFilesCheck" class="html" data-class="wrench">Check media files</option>'));
-            if (tbv.d.oCharacters.TVK) {
+            if (tbv.d.oCharacters.tvk) {
                 toolOptions.push($('<option value="tvkCheck" class="html" data-class="wrench">Check TVKs</option>'));
             }
         }
@@ -261,9 +261,9 @@
         tbv.f.addTaxonImagesToContainer({ taxon: taxon, container: $divImages, height: 300 });
 
         //NBN maps
-        if (tbv.d.oCharacters.TVK && tbv.d.oTaxa[taxon].TVK) {
+        if (tbv.d.oCharacters.tvk && tbv.d.oTaxa[taxon].tvk) {
             var $divNbn = $("<div>").css("position", "relative");
-            tbv.f.addNBNMapToContainer(tbv.d.oTaxa[taxon].TVK, $divNbn);
+            tbv.f.addNBNMapToContainer(tbv.d.oTaxa[taxon].tvk, $divNbn);
         }
 
         //HTML files

identikit/tombio/guiLargeJqueryUi.js

@@ -234,7 +234,7 @@
         //The option *values* mediaFilesCheck & tvkCheck have software-wide meaning, not just this gui
         if (tbv.opts.checkKB) {
             toolOptions.push($('<option value="mediaFilesCheck" class="html" data-class="wrench">Check media files</option>'));
-            if (tbv.d.oCharacters.TVK) {
+            if (tbv.d.oCharacters.tvk) {
                 toolOptions.push($('<option value="tvkCheck" class="html" data-class="wrench">Check TVKs</option>'));
             }
         }
@@ -514,13 +514,13 @@
         var ul = $("<ul>").appendTo(tabs);
         ul.append("<li><a href='#tabs-1'>Knowledge-base</a></li>");
         ul.append("<li><a href='#tabs-2'>Images</a></li>");
-        if (tbv.d.oCharacters.TVK) {
+        if (tbv.d.oCharacters.tvk) {
             ul.append("<li><a href='#tabs-4'>NBN map</a></li>");
         }
         ul.append("<li><a href='#tabs-3'>Details</a></li>");
         var tab1 = $("<div>").attr("id", "tabs-1").appendTo(tabs);
         var tab2 = $("<div>").attr("id", "tabs-2").appendTo(tabs);
-        if (tbv.d.oCharacters.TVK) {
+        if (tbv.d.oCharacters.tvk) {
             //If the TVK character is in the kb, add a tab for NBN maps
             var tab4 = $("<div>").attr("id", "tabs-4").appendTo(tabs);
         }
@@ -568,9 +568,9 @@
         var img = tbv.f.addTaxonImagesToContainer({ taxon: taxon, container: tab2, height: tab2.height() });
 
         //NBN maps
-        if (tbv.d.oCharacters.TVK && tbv.d.oTaxa[taxon].TVK) {
+        if (tbv.d.oCharacters.tvk && tbv.d.oTaxa[taxon].tvk) {
             var $div = $("<div>").css("position", "relative").appendTo(tab4);
-            tbv.f.addNBNMapToContainer(tbv.d.oTaxa[taxon].TVK, $div);
+            tbv.f.addNBNMapToContainer(tbv.d.oTaxa[taxon].tvk, $div);
         }
 
         //HTML files

identikit/tombio/guiOnsenUi.js

@@ -306,7 +306,7 @@
         if (tbv.opts.checkKB) {
             toolOptions.push($('<ons-list-item value="reloadkb" class="html" data-class="wrench">' + icon + 'Reload KB</ons-list-item>'));
             toolOptions.push($('<ons-list-item value="mediaFilesCheck" class="html" data-class="wrench">' + icon + 'Check media files</ons-list-item>'));
-            if (tbv.d.oCharacters.TVK) {
+            if (tbv.d.oCharacters.tvk) {
                 toolOptions.push($('<ons-list-item value="tvkCheck" class="html" data-class="wrench">' + icon + 'Check TVKs</ons-list-item>'));
             }
         }
@@ -599,7 +599,7 @@
             html += '</ons-tab>';
             html += '<ons-tab page="tombioOnsFullDetailsTab2Template" label="Images" icon="md-image">';
             html += '</ons-tab>';
-            if (tbv.d.oCharacters.TVK) {
+            if (tbv.d.oCharacters.tvk) {
                 html += '<ons-tab page="tombioOnsFullDetailsTab3Template" label="NBN Atlas" icon="md-map">';
                 html += '</ons-tab>';
             }
@@ -652,7 +652,7 @@
                 }
                 if (event.target.matches('#tombioOnsFullDetailsTab3')) {
                     $('#tombioOnsFullDetailsTab3Content').html("");
-                    tbv.f.addNBNMapToContainer(tbv.d.oTaxa[taxon].TVK, $('#tombioOnsFullDetailsTab3Content'));
+                    tbv.f.addNBNMapToContainer(tbv.d.oTaxa[taxon].tvk, $('#tombioOnsFullDetailsTab3Content'));
                     $("#tombioNbnMapImage").css("height", $('#tombioOnsFullDetailsTab3').height() - 10);
                 }
                 if (event.target.matches('#tombioOnsFullDetailsTab4')) {

identikit/tombio/kbchecks.js

@@ -603,19 +603,22 @@
         //Taxonomy checks
         errors = $('<ul>');
         //Sort characters so that taxonomy types (Group == Taxonomy) always appear before 
-        //other Taxonomy types and before the taxon character.
+        //other Taxonomy types and before the taxon character. Otherwise keep the existing
+        //order - specified by temporary atttribute sortIndex.
+        tbv.d.characters.forEach((c,i)=>c.sortIndex = i);
         tbv.d.characters.sort(function(a, b){
             let score = c => {
                 if (c.Character == "taxon") {
-                    return 2;
+                    return 2000 + c.sortIndex;
                 } else if (c.Group.toLowerCase() == "taxonomy") {
-                    return 1;
+                    return 1000 + c.sortIndex;
                 } else {
-                    return 3;
+                    return 3000 + c.sortIndex;
                 }
             }
-            return score(a) - score(b)
+            return score(a) - score(b);
         })
+        tbv.d.characters.forEach((c,i)=>delete c.sortIndex);
 
         var taxonomyCharacters = tbv.d.characters.filter(function (c) { return (c.Group.toLowerCase() == "taxonomy") });
         var lastTaxonomyCol = taxonomyCharacters.length > 1 ? taxonomyCharacters[taxonomyCharacters.length - 1].Character : null;
@@ -624,7 +627,7 @@
             errors.append($('<li class="tombioValid3">').html("The last Taxonomy row representing '" + lastTaxonomyCol + "' on the characters worksheet appears below the row representing 'Taxon' - it must come above."));
             taxonomy = false; //Previous sorting should now make this redundant.
         }
-        
+
         //Check that we have a strict hierarchical taxonomy
         //console.log(lastTaxonomyCol, taxonomyCharacters.length)
         if (lastTaxonomyCol == "Taxon" && taxonomyCharacters.length > 2) {
@@ -731,17 +734,17 @@
         //Using Promises
         var pAll = [];
 
-        if (!tbv.d.oCharacters.TVK) {
+        if (!tbv.d.oCharacters.tvk) {
             fComplete();
             return;
         }
 
         tbv.d.taxa.forEach(function (t) {
-            if (t.TVK.kbValue) {
+            if (t.tvk.kbValue) {
                 var p = new Promise(function (resolve, reject) {
 
                     $.ajax({
-                        url: "https://species-ws.nbnatlas.org/species/" + t.TVK.kbValue,
+                        url: "https://species-ws.nbnatlas.org/species/" + t.tvk.kbValue,
                         dataType: "json",
                         success: function () {
                             resolve(t);

identikit/tombio/load.js

@@ -104,8 +104,8 @@
             authors: "Burkmar, R.",
             publisher: "Field Studies Council",
             location: "Shrewsbury, England",
-            contact: "r.burkmar@field-studies-council.org",
-            version: "1.8.1"
+            contact: "rburkmar@ceh.ac.uk",
+            version: "1.9.0"
         }
 
         //Variables for the tools to be included