@gov-cy/govcy-express-services 1.5.0 → 1.6.0

package/README.md

@@ -31,7 +31,7 @@ The APIs used for submission, temporary save and file uploads are not part of th
 - [📦 Full installation guide](#-full-installation-guide)
 - [🛠️ Usage](#%EF%B8%8F-usage)
   - [🔑 Authentication Middleware](#-authentication-middleware)
-    -[CY Login Access Policies](#cy-login-access-policies)
+    - [cyLogin Access Policies](#cylogin-access-policies)
   - [🧩 Dynamic services](#-dynamic-services)
     - [Pages](#pages)
     - [Form vs static pages](#form-vs-static-pages)
@@ -773,6 +773,8 @@ Here is an example JSON config:
 Here are some details explaining the JSON structure:
 
 - `site` object: Contains information about the site, including the site ID, language, and footer links. See [govcy-frontend-renderer](https://github.com/gov-cy/govcy-frontend-renderer/tree/main#site-and-page-meta-data-explained) for more details. Some fields that are only specific to the govcy-express-forms project are the following:
+  - `usesDSFSubmissionPlatform`: A boolean that indicates whether the service uses the DSF submission platform (transforms submission data as needed)
+  - `cyLoginPolicies`: which types of authenticated CY Login profiles are allowed to access the service
   - `submissionDataVersion` : The submission data version,
   - `rendererVersion` : The govcy-frontend-renderer version,
   - `designSystemsVersion` : The govcy-design-system version,
@@ -2661,227 +2663,8 @@ To help back-end systems recognize the field as a file, the field's element name
 If these endpoints are not defined in the service JSON, the file upload logic is skipped entirely.
 Existing services will continue to work without modification.
 
- ### ✨ Custom pages feature
-The **Custom pages** feature allows developers to add service-specific custom pages that exist outside the standard Express Services JSON configuration.  
-
-These pages can collect data, display conditional content, and inject custom sections into the **review** and **email** stages of the service flow.
-
-#### What do custom pages get out of the framework
-With the custom pages feature, developers can define **pages** and **routes** on an express **service**. On these pages the following apply out of the box: 
-- Login requirement
-- User policy requirement
-- Any service eligibility checks
-- Csrf protection on POST
-- Generic error page on errors
-
-The developers can also choose to:
-- store values in the session to be submitted via the submission API
-- define where and what the users sees in the `review` page
-- define errors regarding the custom page in the `review` page 
-- define what the user receives the `email`
-
-#### What the framework expects from custom pages
-
-- Every custom page **must be defined** at startup using `defineCustomPages(app, siteId, pageUrl, ...)`.
-- Custom pages are **not** automatically discovered, they must be registered explicitly.
-- Each page must specify on **start up**:
-    - `pageTitle`: multilingual object for display in review and email
-    - `insertAfterPageUrl`: the page **after which** this custom page will appear
-    - `summaryElements`, `errors`, and `email` are managed dynamically in session
-	    - **NOTE**: Usually a default `required` error must be defined on start up. This will ensure that the when the users try to submit in the “Check your answers” review page, they get an error message to complete an action.
-    - `extraProps` extra property stored in the session to be used by the developers as they wish
-- During **runtime**, developers are responsible for setting:
-    - `data`: data to include in submission, using the `setCustomPageData` function
-    - `summaryElements`: what appears in the “Check your answers” review page, using the `setCustomPageSummaryElements` function
-    - `email`: array of [`dsf-email-templates`](https://github.com/gov-cy/dsf-email-templates) components for the submission confirmation email, using the `setCustomPageEmail`
-    - `errors`: errors that appear in the  “Check your answers” review page. Developers can use the `addCustomPageError` function to add an error, or the `clearCustomPageErrors` to clear the errors
-#### Available methods
-
-| Method                                                                                                                                           | Purpose                                                                                   |
-| ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `defineCustomPages(store, siteId, pageUrl, pageTitle, insertAfterSummary, insertAfterPageUrl, errors, summaryElements, summaryHtml, extraProps)` | Registers a custom page definition in `app`. Must be called once at startup.              |
-| `getCustomPageDefinition(store, siteId, pageUrl)`                                                                                                | Retrieves the custom page definition for a given siteId and pageUrl                       |
-| `resetCustomPages(configStore, store, siteId)`                                                                                                   | Resets per-session data from the global definitions.                                      |
-| `setCustomPageData(store, siteId, pageUrl, dataObject)`                                                                                          | Sets or replaces the data object used during submission.                                  |
-| `setCustomPageSummaryElements(store, siteId, pageUrl, summaryElements)`                                                                          | Sets what appears in the review page summary.                                             |
-| `clearCustomPageErrors(store, siteId, pageUrl)`                                                                                                  | Clears validation errors.                                                                 |
-| `addCustomPageError(store, siteId, pageUrl, errorId, errorTextObject)`                                                                           | Adds a validation error.                                                                  |
-| `setCustomPageEmail(store, siteId, pageUrl, arrayOfEmailObjects)`                                                                                | Defines email sections for the confirmation email using `dsf-email-templates` components. |
-| `setCustomPageProperty(store, siteId, pageUrl, property, value, isDefinition = false)`                                                           | Sets a custom property on a given custom page definition or instance                      |
-| `getCustomPageProperty(store, siteId, pageUrl, property, isDefinition = false)`                                                                  | Gets a custom property from a given custom page definition or instance.                   |
-
----
-##### Example
-
-Below is a practical example of a custom **Declarations** page added to an existing service.
-
-```js
-import initializeGovCyExpressService from '@gov-cy/govcy-express-services';
-import {
-    defineCustomPages, resetCustomPages,
-    clearCustomPageErrors, addCustomPageError,
-    setCustomPageData, setCustomPageSummaryElements,
-    setCustomPageEmail, getCustomPageProperty, setCustomPageProperty
-} from '@gov-cy/govcy-express-services/customPages';
-
-// Initialize the service
-const service = initializeGovCyExpressService({
-    beforeMount({ siteRoute, app }) {
-
-        // ==========================================================
-        // 1️⃣ DEFINE GLOBAL CUSTOM PAGE CONFIGS (once per app)
-        // ==========================================================
-        defineCustomPages(
-            app, // <-- using app as store (global config)
-            "cso", // siteId
-            "/cso/custom", // pageUrl
-            { en: "My custom section", el: "Προσαρμοσμένη ενότητα" }, // pageTitle
-            "qualifications",     // insertAfterPageUrl
-            [                         // errors
-                {
-                    id: "custom-error",
-                    text: {
-                        en: "This is a custom error custom",
-                        el: "Αυτή ειναι ενα προσαρμοσμένη σφαλμα custom",
-                    }
-                }
-            ],
-            [     // summaryElements  
-                {
-                    key:
-                    {
-                        en: "Extra value",
-                        el: "Πρόσθετη τιμή"
-                    },
-                    value: []
-                }
-            ],
-            false,
-            { // other custom properties if needed like nextPage or initial data
-                nextPage: "/cso/memberships", // custom property nextPage. Not needed by Express but useful for the custom logic
-                data : // custom initial data. Useful when you need the data model to be standard or pre-populated
-                { 
-                    something: "",
-                }  
-             }
-        );
-
-        // ==========================================================
-        // 2️⃣ MIDDLEWARE: SET UP SESSION DATA FROM GLOBAL DEFINITIONS
-        // ==========================================================
-        app.use((req, res, next) => {
-            // Initialize session data for custom pages
-            req.session.siteData ??= {};
-            req.session.siteData["cso"] ??= {};
-
-            // Reset session copies if missing (first visit)
-            if (!req.session.siteData["cso"].customPages) {
-                resetCustomPages(app, req.session, "cso"); // 🔁 deep copy from app to session
-                req.session.save((err) => {
-                    if (err) console.error("⚠️ Error initializing customPages:", err);
-                });
-            }
-
-            next();
-        });
-
-        // ==========================================================
-        // 3️⃣ CUSTOM ROUTES (still per-user)
-        // ==========================================================
-
-        // GET `/cso/custom`
-        siteRoute("cso", "get", "/cso/custom", (req, res) => {
-
-            // Render the custom page using the session data
-            // It is important for POST to add the csrfToken and to pass on the route query parameter
-            res.send(`<form action="/cso/custom${(req.query.route === "review")?"?route=review":""}" method="post">
-                 custom for ${req.params.siteId}
-                 <input type="hidden" name="_csrf" value="${req.csrfToken()}">
-                <button type="submit">Submit custom page</button>
-            </form>`);
-
-        });
-
-        // POST `/cso/custom`
-        siteRoute("cso", "post", "/cso/custom", (req, res) => {
-
-            // Update custom page `data` dynamically`
-            setCustomPageData(req.session, "cso", "/cso/custom", {
-                something: "123",
-            });
-
-            // Update `summary elements` dynamically (example)
-            setCustomPageSummaryElements(req.session, "cso", "/cso/custom",
-                [
-                    {
-                        key: {
-                            en: "Extra value",
-                            el: "Πρόσθετη τιμή"
-                        },
-                        value: [
-                            {
-                                element: "textElement",
-                                params: {
-                                    text: {
-                                        en: "123 Changed",
-                                        el: "123 Αλλάχθηκε"
-                                    },
-                                    type: "span",
-                                    showNewLine: true,
-                                }
-                            }
-                        ]
-                    }
-                ]);
-
-            // Update the custom page `email` 
-            setCustomPageEmail(req.session, "cso", "/cso/custom", [
-                {
-                    component: "bodyKeyValue",
-                    params: {
-                        type: "ul",
-                        items: [
-                            { key: "Extra value", value: "123" },
-                            { key: "Priority level", value: "High" },
-                        ],
-                    },
-                }
-            ]);
-
-            // clear any previous errors
-            clearCustomPageErrors(req.session, "cso", "/cso/custom");
-
-            // Add a custom error
-            // addCustomPageError(req.session, "cso", "/cso/custom", {
-            //     id: "custom-error",
-            //     text: {
-            //         en: "This is a custom error custom",
-            //         el: "Αυτή ειναι ενα προσαρμοσμένη σφαλμα custom",
-            //     }
-            // });
-
-            //if route is review, redirect to review page else go to nextPage property
-            if (req.query.route === "review") {
-                res.redirect("/cso/review");
-                return;
-            } else {
-                //example of using custom property nextPage
-                res.redirect(getCustomPageProperty(req.session, "cso", "/cso/custom", "nextPage", false));
-                return;
-            }
-        });
-
-
-        // ==========================================================
-    },
-});
-
-
-// Start the server
-service.startServer();
-
-```
-
+### ✨ Custom pages feature
+The **Custom pages** feature allows developers to code service-specific custom pages that exist outside the standard Express Services JSON configuration. More details at [Custom-pages.md](docs/Custom-pages.md)
 
 ### 🛣️ Routes
 The project uses express.js to serve the following routes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gov-cy/govcy-express-services",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "An Express-based system that dynamically renders services using @gov-cy/govcy-frontend-renderer and posts data to a submission API.",
   "author": "DMRID - DSF Team",
   "license": "MIT",
@@ -56,7 +56,7 @@
     "coverage:badge": "coverage-badges --output ./coverage-badges.svg && npm run coverage:copy"
   },
   "dependencies": {
-    "@gov-cy/dsf-email-templates": "^2.1.1",
+    "@gov-cy/dsf-email-templates": "^2.1.11",
     "@gov-cy/govcy-frontend-renderer": "^1.26.0",
     "axios": "^1.9.0",
     "cookie-parser": "^1.4.7",

package/src/middleware/govcyReviewPostHandler.mjs

@@ -184,7 +184,7 @@ export function govcyReviewPostHandler() {
                 const submissionData = prepareSubmissionData(req, siteId, service);
 
                 // Prepare submission data for API
-                const submissionDataAPI = prepareSubmissionDataAPI(submissionData);
+                const submissionDataAPI = prepareSubmissionDataAPI(submissionData, service);
 
                 logger.debug("Prepared submission data for API:", submissionDataAPI);
 

package/src/utils/govcyFormHandling.mjs

@@ -133,7 +133,7 @@ export function populateFormData(
                     // Delete link (preserve ?route=review if present)
                     element.params.deleteHref = `${basePath}/delete-file/${fieldName}${(routeParam) ? `?route=${routeParam}` : ''}`
 
-                   
+
                 } else {
                     // TODO: Ask Andreas how to handle empty file inputs
                     element.params.value = "";
@@ -295,3 +295,74 @@ export function getFormData(elements, formData, store = {}, siteId = "", pageUrl
 
     return filteredData;
 }
+
+/**
+ * Get empty form data for multipleThings elements.
+ * Used to fill in empty multipleThings pages with the correct structure
+ * 
+ * @param {object|Array} pageOrElements The page or elements of a conditional radio
+ * @param {object} emptyObject The object to populate with empty values
+ * @returns {object} An object with empty values for each form element 
+ */
+export function getMultipleThingsEmptyFormData(pageOrElements, emptyObject = {}) {
+    // Determine if we're given a full page or just an array of elements
+    let elements = [];
+    if (Array.isArray(pageOrElements)) {
+        elements = pageOrElements; // recursion case
+    } else if (pageOrElements?.pageTemplate?.sections) {
+        // Deep copy to avoid modifying the original
+        const pageTemplateCopy = JSON.parse(JSON.stringify(pageOrElements.pageTemplate));
+        // Find the first form element in sections
+        for (const section of pageTemplateCopy.sections) {
+            const form = section.elements?.find(el => el.element === "form");
+            if (form) {
+                elements = form?.params?.elements || [];
+                break;
+            }
+        }
+    } else {
+        // No valid elements
+        return emptyObject;
+    }
+
+    // Iterate through elements in order (like getFormData)
+    elements.forEach(element => {
+        const { name } = element.params || {};
+
+        if (ALLOWED_FORM_ELEMENTS.includes(element.element) && name) {
+            // Handle different element types
+            if (["checkboxes", "radios", "select"].includes(element.element)) {
+                emptyObject[name] = "";
+
+                // Handle conditional radios (same recursion pattern as getFormData)
+                if (element.element === "radios" && Array.isArray(element.params?.items)) {
+                    element.params.items.forEach(item => {
+                        if (item.conditionalElements) {
+                            Object.assign(
+                                emptyObject,
+                                getMultipleThingsEmptyFormData(item.conditionalElements, {})
+                            );
+                        }
+                    });
+                }
+            }
+
+            // Handle dateInput (single name, per your clarification)
+            else if (element.element === "dateInput") {
+                emptyObject[name] = "";
+            }
+
+            // Handle fileInput (suffix Attachment, per submission schema)
+            else if (element.element === "fileInput") {
+                emptyObject[`${name}Attachment`] = "";
+            }
+
+            // Handle all other elements (textInput, textArea, datePicker, etc.)
+            else {
+                emptyObject[name] = "";
+            }
+        }
+    });
+
+    return emptyObject;
+}

package/src/utils/govcySubmitData.mjs

@@ -4,7 +4,8 @@ import * as dataLayer from "./govcyDataLayer.mjs";
 import { DSFEmailRenderer } from '@gov-cy/dsf-email-templates';
 import { ALLOWED_FORM_ELEMENTS } from "./govcyConstants.mjs";
 import { evaluatePageConditions } from "./govcyExpressions.mjs";
-import { getPageConfigData } from "./govcyLoadConfigData.mjs";
+import { getServiceConfigData, getPageConfigData } from "./govcyLoadConfigData.mjs";
+import { getMultipleThingsEmptyFormData } from "./govcyFormHandling.mjs";
 import { logger } from "./govcyLogger.mjs";
 import { createUmdManualPageTemplate } from "../middleware/govcyUpdateMyDetails.mjs"
 import nunjucks from "nunjucks";
@@ -252,21 +253,48 @@ export function prepareSubmissionData(req, siteId, service) {
 /**
  * Prepares the submission data for the API, stringifying all relevant fields.
  * 
- * @param {object} data data prepared by `prepareSubmissionData`
+ * @param {object} data data prepared by `prepareSubmissionData`\
+ * @param {object} service service config data
  * @returns {object} The API-ready submission data object with all fields as strings
  */
-export function prepareSubmissionDataAPI(data) {
+export function prepareSubmissionDataAPI(data, service) {
+
+    //deep copy data to avoid mutating the original
+    let dataObj = JSON.parse(JSON.stringify(data));
+    // get site?.submissionAPIEndpoint.isDSFSubmissionPlatform
+    const isDSFSubmissionPlatform = service?.site?.usesDSFSubmissionPlatform || false;
+
+    // If DSF Submission Platform, ensure submissionData is an array
+    // this is intended for multipleThings pages only
+    if (isDSFSubmissionPlatform) {
+        // loop through submissionData 
+        for (const [key, value] of Object.entries(dataObj.submissionData || {})) {
+            // check if the value is an empty array
+            if (Array.isArray(value) && value.length === 0) {
+                // get the pageConfigData for the page
+                try {
+                    const page = getPageConfigData(service, key);
+                    let pageEmptyData = getMultipleThingsEmptyFormData(page);
+                    //replace the dataObj.submissionData[key] with the empty data
+                    dataObj.submissionData[key] = [pageEmptyData];
+    
+                } catch (error) {
+                    logger.error('Error getting pageConfigData:', key);
+                }
+            }
+        }
+    }
 
     return {
-        submissionUsername: String(data.submissionUsername ?? ""),
-        submissionEmail: String(data.submissionEmail ?? ""),
-        submissionData: JSON.stringify(data.submissionData ?? {}),
-        submissionDataVersion: String(data.submissionDataVersion ?? ""),
-        printFriendlyData: JSON.stringify(data.printFriendlyData ?? []),
-        rendererData: JSON.stringify(data.rendererData ?? {}),
-        rendererVersion: String(data.rendererVersion ?? ""),
-        designSystemsVersion: String(data.designSystemsVersion ?? ""),
-        service: JSON.stringify(data.service ?? {})
+        submissionUsername: String(dataObj.submissionUsername ?? ""),
+        submissionEmail: String(dataObj.submissionEmail ?? ""),
+        submissionData: JSON.stringify(dataObj.submissionData ?? {}),
+        submissionDataVersion: String(dataObj.submissionDataVersion ?? ""),
+        printFriendlyData: JSON.stringify(dataObj.printFriendlyData ?? []),
+        rendererData: JSON.stringify(dataObj.rendererData ?? {}),
+        rendererVersion: String(dataObj.rendererVersion ?? ""),
+        designSystemsVersion: String(dataObj.designSystemsVersion ?? ""),
+        service: JSON.stringify(dataObj.service ?? {})
     };
 }
 

package/src/utils/govcyValidator.mjs

@@ -28,6 +28,7 @@ function validateValue(value, rules) {
     alpha: (val) => /^[A-Za-zΑ-Ωα-ω\u0370-\u03ff\u1f00-\u1fff\s]+$/.test(val),
     alphaNum: (val) => /^[A-Za-zΑ-Ωα-ω\u0370-\u03ff\u1f00-\u1fff0-9\s]+$/.test(val),
     noSpecialChars: (val) => /^([0-9]|[A-Z]|[a-z]|[α-ω]|[Α-Ω]|[,]|[.]|[-]|[(]|[)]|[?]|[!]|[;]|[:]|[\n]|[\r]|[ _]|[\u0370-\u03ff\u1f00-\u1fff])+$/.test(val),
+    noSpecialCharsEl: (val) => /^([0-9]|[α-ω]|[Α-Ω]|[,]|[.]|[-]|[(]|[)]|[?]|[!]|[;]|[:]|[\n]|[\r]|[ _]|[\u0370-\u03ff\u1f00-\u1fff])+$/.test(val),
     name: (val) => /^[A-Za-zΑ-Ωα-ω\u0370-\u03ff\u1f00-\u1fff\s'-]+$/.test(val),
     tel: (val) => /^(?:\+|00)?[\d\s\-()]{8,20}$/.test(val.replace(/[\s\-()]/g, '')),
     mobile: (val) => /^(?:\+|00)?[\d\s\-()]{8,20}$/.test(val.replace(/[\s\-()]/g, '')),