Configuration for auto-sheet selection when only one (#316)

rossjones · web-flow · commit f48a224d72db · 2025-09-16T09:41:48.000+01:00
* Add lib changes to support a new config parameter

Adds support to the core lib for a new config parameter which specifies
what do to when an upload has only one sheet.  'Manual' will, as now,
expect the user to select it (perhaps as a check that the correct file
was used), while 'automatic' will progress the user straight onto the
next page.

To support this behaviour, we have added support for an 'other' link
alongside the 'next' link when specifying form paths.

* Explain where the form action link has two paths

* Add auto-skip options to configuration screen

* Update tests with new default sheet mode
diff --git a/lib/importer/src/config.js b/lib/importer/src/config.js
@@ -31,6 +31,11 @@ exports.PluginConfig = class {
     this.uploadPath = config.uploadPath;
     this.uploadPathDefault = false;
 
+  // Should we auto-select a sheet when there is only one sheet?
+  //    manual - No, always select a sheet even if there is only one.
+  //    automatic - Yes, always use the single sheet when there is only one.
+    this.sheetSelection = config.sheetSelection || "manual";
+
     // If the config fields are in the old format (just names) then move them to
     // the new structure with default values of text for the type, and not required.
     if (this.fields.find(Boolean)) {
@@ -77,10 +82,18 @@ exports.PluginConfig = class {
     }
   };
 
+  setSheetSelection = (mode) => {
+      if (!["manual", "automatic"].includes(mode)) {
+        throw (`'${mode}' is not a valid sheet selection mode`)
+      }
+      this.sheetSelection = mode
+    }
+
   as_object = () => {
     return {
       uploadPath: this.uploadPathDefault ? TEMP_DIRECTORY_LABEL : this.uploadPath,
-      fields: this.fields
+      fields: this.fields,
+      sheetSelection: this.sheetSelection
     }
   }
 
@@ -95,6 +108,7 @@ exports.PluginConfig = class {
     let current = fse.readJsonSync(configFilePath);
 
     current.fields = this.fields;
+    current.sheetSelection = this.sheetSelection
 
     fse.writeJsonSync(configFilePath, current);
   };
diff --git a/lib/importer/src/config.test.js b/lib/importer/src/config.test.js
@@ -36,6 +36,8 @@ describe("Configuration tests", () => {
                 expect(original.uploadPath).not.toBeNull()
                 expect(updated.uploadPath).not.toBeNull()
                 expect(c.uploadPath).not.toBeNull()
+                expect(updated.sheetSelection).not.toBeNull()
+                expect(updated.sheetSelection).toStrictEqual("manual")
             }
         );
 
@@ -133,6 +135,69 @@ describe("Configuration tests", () => {
         mock_files.restore();
     });
 
+test('manual sheet selection', () => {
+        mock_files({
+            './fields/app/config.json': '{"fields": [{"name":"A"}, {"name": "B"}, {"name": "C"}]}',
+        })
+
+        withCurrent(
+            "./fields",
+            new cfg.PluginConfig(),
+            (c) => {
+                c.setSheetSelection("manual")
+                c.persistConfig()
+            },
+            (original, updated) => {
+                expect(updated.sheetSelection).toStrictEqual("manual")
+            }
+        );
+
+        mock_files.restore();
+    });
+
+    test('default sheet selection', () => {
+        mock_files({
+            './fields/app/config.json': '{"fields": [{"name":"A"}, {"name": "B"}, {"name": "C"}]}',
+        })
+
+        withCurrent(
+            "./fields",
+            new cfg.PluginConfig(),
+            (c) => {
+                c.persistConfig()
+            },
+            (original, updated) => {
+                expect(updated.sheetSelection).toStrictEqual("manual")
+            }
+        );
+
+        mock_files.restore();
+    });
+
+
+    test('invalid sheet selection', () => {
+        mock_files({
+            './fields/app/config.json': '{"fields": [{"name":"A"}, {"name": "B"}, {"name": "C"}]}',
+        })
+
+        withCurrent(
+            "./fields",
+            new cfg.PluginConfig(),
+            (c) => {
+                expect(() => {
+                    c.setSheetSelection("invalid")
+                }
+                ).toThrow("'invalid' is not a valid sheet selection mode")
+                c.persistConfig()
+            },
+            (original, updated) => {
+                expect(updated.sheetSelection).toStrictEqual("manual")
+            }
+        );
+
+        mock_files.restore();
+    });
+
 })
 
 
diff --git a/lib/importer/src/index.js b/lib/importer/src/index.js
@@ -100,7 +100,11 @@ exports.Initialise = (config, router, prototypeKit) => {
 
     prototypeKit.views.addFunction(
       k,
-      (next) => {
+      (next, other = null) => {
+        if (next && other) {
+          return `${v}?next=${encodeURIComponent(next)}&other=${encodeURIComponent(other)}`;
+        }
+
         return `${v}?next=${encodeURIComponent(next)}`;
       },
       {},
@@ -171,7 +175,16 @@ exports.Initialise = (config, router, prototypeKit) => {
 
       if (session.sheets.length == 1) {
         session.sheet = session.sheets[0];
+
+        // When there is only a single sheet, and if the prototype is configured to
+        // automatically progress, then this will do so if the 'other' url is
+        // specified.
+        if (plugin_config.sheetSelection.toLowerCase() == "automatic" && "other" in request.query) {
+          const otherPage = decodeURIComponent(request.query.other)
+          if (otherPage) { request.query.next = request.query.other }
+        }
       }
+
       // Ensure the session is persisted. Currently in session, eventually another way
       request.session.data[IMPORTER_SESSION_KEY] = session;
       redirectOnwards(request, response);
@@ -392,6 +405,7 @@ exports.Initialise = (config, router, prototypeKit) => {
           config: {
             fields: plugin_config.fields
           },
+          sheetMode: plugin_config.sheetSelection || "manual",
           collectUsageData: usageRecorder.enabled,
         }
 
@@ -432,6 +446,12 @@ exports.Initialise = (config, router, prototypeKit) => {
           usageRecorder.setPermission(false)
         }
 
+        const sheetMode = request.body.sheetMode || "manual"
+        if (["manual", "automatic"].includes(sheetMode.toLowerCase())) {
+          plugin_config.sheetSelection = sheetMode.toLowerCase()
+        } else {
+          plugin_config.sheetSelection = "manual"
+        }
 
         setTimeout(function () {
           plugin_config.persistConfig()
diff --git a/lib/importer/templates/upload.html b/lib/importer/templates/upload.html
@@ -12,7 +12,8 @@
     <div class="govuk-grid-column-two-thirds">
         <h1 class="govuk-heading-l">Upload your data</h1>
 
-        <form action="{{importerUploadPath('/select_sheet')}}" method="POST" enctype="multipart/form-data">
+        <!-- Upload to select sheet, but in automatic mode, will go to header selection instead -->
+        <form action="{{importerUploadPath('/select_sheet', '/select_header_row')}}" method="POST" enctype="multipart/form-data">
             <div>
                 {{ govukFileUpload({
                 id: "file-upload",
diff --git a/lib/importer/views/plugin_config.html b/lib/importer/views/plugin_config.html
@@ -97,6 +97,48 @@ <h2 class="govuk-heading-l">Column settings</h2>
 
     <div class="govuk-grid-column-full govuk-!-padding-top-6" >
         <h2 class="govuk-heading-l"></h2>
+ <div class="govuk-form-group">
+    <fieldset class="govuk-fieldset">
+    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
+      <h1 class="govuk-fieldset__heading">
+        Auto sheet selection
+      </h1>
+    </legend>
+
+    <div class="govuk-radios" data-module="govuk-radios">
+      <p class="govuk-body">
+      When a user uploads a spreadsheet and there is only a single sheet,
+      the plugin can either automatically select the first sheet
+      or allow the user to choose a specific sheet.
+
+      The default is to allow the user to choose the sheet,
+      but by selecting 'automatic' here the single sheet
+      will always be used without user intevention skipping the sheet
+      selection screen.
+      </p>
+
+      <div id="type-hint" class="govuk-hint">
+        Choose auto-sheet selection mode
+      </div>
+
+      <div class="govuk-radios__item">
+          <input class="govuk-radios__input" id="field-sheet-manual" name="sheetMode" type="radio" value="manual" {% if sheetMode == "manual" %}checked{% endif %}>
+          <label class="govuk-label govuk-radios__label" for="field-sheet-manual">
+            Manual
+          </label>
+        </div>
+        <div class="govuk-radios__item">
+          <input class="govuk-radios__input" id="field-sheet-automatic" name="sheetMode" type="radio" value="automatic" {% if sheetMode == "automatic" %}checked{% endif %}>
+          <label class="govuk-label govuk-radios__label" for="field-sheet-automatic">
+            Automatic
+          </label>
+        </div>
+      </div>
+    </div> <!-- fieldset -->
+</div> <!-- form-group -->
+
+<div class="govuk-grid-column-full govuk-!-padding-top-6" >
+<h2 class="govuk-heading-l"></h2>
 
 <div class="govuk-form-group">
   <fieldset class="govuk-fieldset">
diff --git a/prototypes/basic/app/views/upload.html b/prototypes/basic/app/views/upload.html
@@ -56,7 +56,8 @@ <h1 class="govuk-heading-s">Check your dates</h1>
           </ul>
         </p>
 
-        <form action="{{importerUploadPath('/select_sheet')}}" method="POST" enctype="multipart/form-data">
+        <!-- Upload to select sheet, but in automatic mode, will go to header selection instead -->
+        <form action="{{importerUploadPath('/select_sheet', '/select_header_row')}}" method="POST" enctype="multipart/form-data">
             <div>
                 {{ govukFileUpload({
                 id: "file-upload",
