From 1b11fba0a82ec893f44d642ddb0ec770081a2720 Mon Sep 17 00:00:00 2001
From: Damien De Paoli <ddp@depaoli.id.au>
Date: Mon, 6 Sep 2021 22:03:11 +1000
Subject: [PATCH] comments for files*js

---
 internal/js/files_support.js   | 21 +++++++++++++++++++++
 internal/js/files_transform.js |  9 +++++++++
 2 files changed, 30 insertions(+)

diff --git a/internal/js/files_support.js b/internal/js/files_support.js
index 8a97ecb..72e4574 100644
--- a/internal/js/files_support.js
+++ b/internal/js/files_support.js
@@ -1,3 +1,6 @@
+// grab all selected thumbnails and return a <div> containing the thumbnails
+// with extra yr and date attached as attributes so we can set the default
+// dir name for a move directory - not used in del, but no harm to include them
 function GetSelnAsDiv()
 {
     seln=''
@@ -10,6 +13,7 @@ function GetSelnAsDiv()
     return '<div class="row col-12">'+seln+'</div>'
 }
 
+// return a list of eid=<id> for each selected thumbnail
 function GetSelnAsData()
 {
     to_del=''
@@ -17,6 +21,7 @@ function GetSelnAsData()
     return to_del
 }
 
+// use an ajax POST to force an AI scan on the selected images
 function RunAIOnSeln(person)
 {
     post_data = GetSelnAsData()
@@ -24,6 +29,8 @@ function RunAIOnSeln(person)
     $.ajax({ type: 'POST', data: post_data, url: '/run_ai_on', success: function(data){ window.location='/'; return false; } })
 }
 
+// show the DBox for a move file, includes all thumbnails of selected files to move
+// and a pre-populated folder to move them into, with text field to add a suffix
 function MoveDBox(sps, db_url)
 {
     $('#dbox-title').html('Move Selected File(s) to new directory in Storage Path')  
@@ -72,6 +79,8 @@ function MoveDBox(sps, db_url)
     $('#dbox').modal('show')
 }
 
+// show the DBox for a delete/restore file, includes all thumbnails of selected files 
+// with appropriate coloured button to Delete or Restore files`
 function DelDBox(del_or_undel)
 {
     to_del = GetSelnAsData()
@@ -100,6 +109,7 @@ function DelDBox(del_or_undel)
     $('#dbox').modal('show')
 }
 
+// show the DBox for a lame quick version of file details 
 function DetailsDBox()
 {
     $('#dbox-title').html('Details of Selected File(s)')  
@@ -127,6 +137,8 @@ function DetailsDBox()
 }
 
 
+// function to change the size of thumbnails (and resets button bar to newly
+// selected size)
 function ChangeSize(clicked_button,sz)
 {
 	$('.sz-but.btn-info').removeClass('btn-info text-white').addClass('btn-outline-info')
@@ -139,6 +151,8 @@ function ChangeSize(clicked_button,sz)
     $('.svg_cap').width(sz);
 }
 
+// DoSel is called when a click event occurs, and sets the selection via adding
+// 'highlight' to the class of the appropriate thumbnails
 // e == event (can see if shift/ctrl held down while left-clicking
 // el == element the click is on
 // this allows single-click to select, ctrl-click to (de)select 1 item, and
@@ -178,6 +192,7 @@ function DoSel(e, el)
     $(el).addClass('highlight')
 }
 
+// if a selection exists, enable move & del/restore buttons otherwise disable them
 function SetButtonState() {
     var sel=false
     $('.highlight').each(function( index ) { sel=true } )
@@ -190,6 +205,8 @@ function SetButtonState() {
     }
 }
 
+// Check if the set of highlights are either only figures, dirs or both
+// used to work out what options are shown in the file context menu
 function FiguresOrDirsOrBoth() {
     var figure=false
     var dir=false
@@ -208,6 +225,9 @@ function FiguresOrDirsOrBoth() {
     return "both"
 }
 
+// Check if the set of highlights contain Bin and Not Bin...
+// if its both, then no del/restore is possible in context menu
+// otherwise can either set del or restore appropriately
 function SelContainsBinAndNotBin() {
     var bin=false
     var not_bin=false
@@ -224,6 +244,7 @@ function SelContainsBinAndNotBin() {
         return false
 }
 
+// checks to see if there is no selection active
 function NoSel() {
     var sel=false
     $('.highlight').each(function( index ) { sel=true } )
diff --git a/internal/js/files_transform.js b/internal/js/files_transform.js
index 496461a..273eb5c 100644
--- a/internal/js/files_transform.js
+++ b/internal/js/files_transform.js
@@ -1,3 +1,7 @@
+// POST to a check URL, that will tell us if the transformation has completed,
+// if not, try again in 1 second... If it has finished then reset the thumbnail
+// to full colour, put it back to being an entry and reset the thumbnail to the
+// newly created one that was sent back in the response to the POST
 function CheckTransformJob(id,job_id)
 {
     $.ajax(
@@ -19,6 +23,11 @@ function CheckTransformJob(id,job_id)
         } )
 }
 
+// for each highlighted image, POST the transform with amt (90, 180, 270,
+// fliph, flipv) which will let the job manager know what to do to this file.
+// we also grayscale the thumbnail out, remove the entry class for now, show
+// the spinning wheel, and finally kick of the checking for the transform job
+// to finish
 function Transform(amt)
 {
     $('.highlight').each(function( id, e ) {