@gov-cy/govcy-express-services 1.3.1 → 1.4.0

package/README.md

@@ -43,6 +43,7 @@ The APIs used for submission, temporary save and file uploads are not part of th
   - [🔀 Conditional logic](#-conditional-logic)
   - [💾 Temporary save feature](#-temporary-save-feature)
   - [🗃️ Files uploads feature](#%EF%B8%8F-files-uploads-feature)
+  - [✨ Custom pages feature](#-custom-pages-feature)
 - [🛣️ Routes](#%EF%B8%8F-routes)
 - [👨‍💻 Environment variables](#-environment-variables)
 - [🔒 Security note](#-security-note)
@@ -2603,6 +2604,228 @@ 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();
+
+```
+
+
 ### 🛣️ 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.3.1",
+  "version": "1.4.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",
@@ -8,7 +8,12 @@
   "main": "./src/index.mjs",
   "module": "./src/index.mjs",
   "exports": {
-    "import": "./src/index.mjs"
+    ".": {
+      "import": "./src/index.mjs"
+    },
+    "./customPages": {
+      "import": "./src/utils/govcyCustomPages.mjs"
+    }
   },
   "files": [
     "src"

package/src/index.mjs

@@ -35,7 +35,7 @@ import { logger } from "./utils/govcyLogger.mjs";
 
 import fs from 'fs';
 
-export default function initializeGovCyExpressService() {
+export default function initializeGovCyExpressService(opts = {}) {
   const app = express();
 
   // Add this line before session middleware
@@ -152,6 +152,46 @@ export default function initializeGovCyExpressService() {
     govcyFileUpload
   );
 
+  // ==========================================================
+  //  Custom pages
+  // ==========================================================
+  /**
+   * siteRoute helper:
+   * Registers a route NOT under /:siteId, but injects req.params.siteId manually.
+   */
+  const siteRoute = (siteId, method, path, ...handlers) => {
+    if (typeof app[method] !== "function") {
+      throw new Error(`Unsupported HTTP method: ${method}`);
+    }
+
+    // Middleware to manually inject the siteId param
+    const injectSiteId = (req, res, next) => {
+      req.params = req.params || {};
+      req.params.siteId = siteId;
+      next();
+    };
+
+    // Chain your standard middlewares AFTER injection
+    const wrappedHandlers = [
+      injectSiteId,
+      serviceConfigDataMiddleware,
+      requireAuth,
+      naturalPersonPolicy,
+      govcyServiceEligibilityHandler(),
+      ...handlers,
+    ];
+
+    // ✅ Register under a plain path (no /:siteId/)
+    // e.g. path = "/custom" → registers "/custom" only
+    app[method](path, ...wrappedHandlers);
+  };
+
+  // Allow custom routes
+  if (typeof opts.beforeMount === "function") {
+    opts.beforeMount({ siteRoute, app });
+  }
+  // ==========================================================
+
   // 🗃️ -- ROUTE: Handle POST requests for file uploads inside multipleThings (edit)
   app.post('/apis/:siteId/:pageUrl/multiple/edit/:index/upload',
     serviceConfigDataMiddleware,
@@ -299,13 +339,13 @@ export default function initializeGovCyExpressService() {
   );
 
   // ----- `updateMyDetails` handling
-  
+
   // 🔀➡️ -- ROUTE coming from incoming update my details /:siteId/:pageUrl/update-my-details-response
-  app.post('/:siteId/:pageUrl/update-my-details-response', 
-    serviceConfigDataMiddleware, 
-    requireAuth, 
-    naturalPersonPolicy, 
-    govcyServiceEligibilityHandler(true), 
+  app.post('/:siteId/:pageUrl/update-my-details-response',
+    serviceConfigDataMiddleware,
+    requireAuth,
+    naturalPersonPolicy,
+    govcyServiceEligibilityHandler(true),
     govcyUpdateMyDetailsPostHandler());
   // ----- `updateMyDetails` handling
 

package/src/middleware/govcyReviewPageHandler.mjs

@@ -89,7 +89,10 @@ export function govcyReviewPageHandler() {
                             if (fieldKey === "type") continue;
                             // Push each field error to summary items
                             summaryItems.push({
-                                link: govcyResources.constructPageUrl(siteId, fieldErr.pageUrl, "review"),
+                                link: (err.type === "custom" ? // Custom pages 
+                                    `/${fieldErr.pageUrl}?route=review` :
+                                    govcyResources.constructPageUrl(siteId, fieldErr.pageUrl, "review")
+                                ),
                                 text: fieldErr.message
                             });
                         }

package/src/middleware/govcyReviewPostHandler.mjs

@@ -10,6 +10,7 @@ import { sendEmail } from "../utils/govcyNotification.mjs"
 import { evaluatePageConditions } from "../utils/govcyExpressions.mjs";
 import { createUmdManualPageTemplate } from "./govcyUpdateMyDetails.mjs"
 import { validateMultipleThings } from "../utils/govcyMultipleThingsValidation.mjs";
+import { resetCustomPages } from "../utils/govcyCustomPages.mjs";
 
 /**
  * Middleware to handle review page form submission
@@ -25,12 +26,12 @@ export function govcyReviewPostHandler() {
             let validationErrors = {};
             // to be used for sending email
             let updateMyDetailsData = null;
-            
+
             // Loop through all pages in the service
             for (const page of service.pages) {
                 //get page url
                 const pageUrl = page.pageData.url;
-                
+
                 // to be used for sending email 
                 // get updateMyDetails data if not found before
                 if (!updateMyDetailsData) {
@@ -52,13 +53,13 @@ export function govcyReviewPostHandler() {
                 if (page.updateMyDetails) {
                     logger.debug("Validating UpdateMyDetails page during review POST", { siteId, pageUrl });
                     // Build the manual UMD page template
-                    const umdTemplate  = createUmdManualPageTemplate(siteId, service.site.lang, page, req);
-                    
+                    const umdTemplate = createUmdManualPageTemplate(siteId, service.site.lang, page, req);
+
                     // Extract the form element
-                    formElement = umdTemplate .sections
+                    formElement = umdTemplate.sections
                         .flatMap(section => section.elements)
                         .find(el => el.element === "form");
-                    
+
                     if (!formElement) {
                         logger.error("🚨 UMD form element not found during review validation", { siteId, pageUrl });
                         return handleMiddlewareError("🚨 UMD form element not found during review validation", 500, next);
@@ -107,6 +108,53 @@ export function govcyReviewPostHandler() {
                 validationErrors = { ...validationErrors, ...errors };
             }
 
+            // ==========================================================
+            //  Custom pages
+            // ==========================================================
+            //  Handle custom summary validation blocks from session
+            const customPages = dataLayer.getSiteCustomPages(req.session, siteId);
+
+            //  Convert existing validationErrors object to ordered array of [pageUrl, errorObj]
+            //    so we can splice into it in the correct order.
+            let orderedErrors = Object.entries(validationErrors);
+
+            for (const [key, block] of Object.entries(customPages)) {
+                if (Array.isArray(block.errors) && block.errors.length > 0) {
+                    const customErrObj = {};
+                    for (const err of block.errors) {
+                        customErrObj[err.id] = {
+                            id: err.id,
+                            message: err.text,       // ⚙️ uses your structure
+                            pageUrl: err.pageUrl || key
+                        };
+                    }
+
+                    const newErrorEntry = [
+                        key,
+                        {
+                            type: "custom",           // mark it as custom for debug clarity
+                            ...customErrObj
+                        }
+                    ];
+
+                    //  If block.insertAfter exists, insert after that page’s index
+                    if (block.insertAfterPageUrl) {
+                        const idx = orderedErrors.findIndex(([pageUrl]) => pageUrl === block.insertAfterPageUrl);
+                        if (idx >= 0) {
+                            orderedErrors.splice(idx + 1, 0, newErrorEntry); // insert after
+                            continue; // move to next custom block
+                        }
+                    }
+
+                    //  Fallback: append to top if insertAfter not found or not defined
+                    orderedErrors.unshift(newErrorEntry);
+                }
+            }
+
+            //  Convert back into a normal object
+            validationErrors = Object.fromEntries(orderedErrors);
+            // ==========================================================
+
             // ❌ Return validation errors if any exist
             if (Object.keys(validationErrors).length > 0) {
                 logger.debug("🚨 Validation errors:", validationErrors, req);
@@ -163,7 +211,7 @@ export function govcyReviewPostHandler() {
                     // Add the reference number to the submission data
                     submissionData.referenceNumber = referenceNo;
                     logger.info("✅ Data submitted", siteId, referenceNo);
-                    
+
                     // Get the user email address
                     let emailAddress = "";
                     // if Update my details not provided the use user email
@@ -174,25 +222,33 @@ export function govcyReviewPostHandler() {
                     }
                     // add contact email to submission data
                     submissionData.contactEmailAddress = emailAddress;
-                    
+
                     // handle data layer submission
                     dataLayer.storeSiteSubmissionData(
                         req.session,
                         siteId,
                         submissionData);
-
+                        
                     //-- Send email to user
                     // Generate the email body
                     let emailBody = generateSubmitEmail(service, submissionData.printFriendlyData, referenceNo, req);
-                   
+                    
+                    // ==========================================================
+                    //  Custom pages
+                    // =========================================================
+                    // 🆕 Reset per-session custom pages from the global app definition
+                    const app = req.app;  // ✅ Express automatically provides this
+                    resetCustomPages(app, req.session, siteId);
+                    // ==========================================================
+
                     // Send the email
                     sendEmail(
-                        service.site.title[service.site.lang], 
-                        emailBody, 
-                        [emailAddress], 
+                        service.site.title[service.site.lang],
+                        emailBody,
+                        [emailAddress],
                         "eMail").catch(err => {
                             logger.error("Email sending failed (async):", err);
-                    });
+                        });
                     // --- End of email sending
 
                     logger.debug("🔄 Redirecting to success page:", req);

package/src/utils/govcyCustomPages.mjs

@@ -0,0 +1,260 @@
+import * as govcyResources from "../resources/govcyResources.mjs";
+
+/**
+ * Defines custom pages for a given siteId and pageUrl.
+ * This function initializes the custom pages in the store and sets up the necessary data structure.
+ * @param {object} store The session store (usually req.app)
+ * @param {string} siteId The site identifier (e.g., `"cso"`)
+ * @param {string} pageUrl The URL of the custom page (e.g., `"/cso/custom"`)
+ * @param {string} pageTitle The title of the custom page (e.g., `{ en: "My custom section", el: "Προσαρμοσμένη ενότητα" }`)
+ * @param {string} insertAfterPageUrl The page URL to insert the custom page after (e.g., `"qualifications"`)
+ * @param {array} errors An array of error objects (e.g., `[{ id: "error1", text: { en: "Error 1", el: "Error 1"} }, { id: "error2", text: { en: "Error 2", el: "Error 2"} }]`)
+ * @param {array} summaryElements An array of summary element objects (e.g., `{ key: { en: "Extra value", el: "Πρόσθετη τιμή" }, value: [] }` )
+ * @param {boolean} summaryHtml Optional HTML content for the summary (e.g., `{ en: "<strong>Summary HTML</strong>", el: "<strong>Περίληψη HTML</strong>" }`)
+ * @param {object} [extraProps={}] Optional extra metadata (e.g., `{ nextPage: "confirmation", requiresOTP: true }`)
+ */
+export function defineCustomPages(
+    store,
+    siteId,
+    pageUrl,
+    pageTitle,
+    insertAfterPageUrl,
+    errors,
+    summaryElements,
+    summaryHtml = false,
+    extraProps = {}
+) {
+    // Initialize custom pages in session if not already set
+    store.siteData ??= {};
+    store.siteData[siteId] ??= {};
+    store.siteData[siteId].customPagesDefinition ??= {}; // Initialize custom pages definition
+    store.siteData[siteId].customPagesDefinition[pageUrl] ??= {}; // Initialize specific page definition
+
+    // ✅ Normalize error objects: add pageUrl if missing
+    let normalizedErrors = [];
+    if (Array.isArray(errors)) {
+        normalizedErrors = errors.map(err => ({
+            ...err,
+            // pageUrl replace first `/` with empty string to ensure it is relative
+            pageUrl: err.pageUrl || pageUrl.replace(/^\//, "") // ← ensure pageUrl is set
+        }));
+    }
+
+    // Initialize the custom summary actions
+    let summaryActions = [];
+
+    // Base definition
+    const definition = {
+        pageTitle,
+        insertAfterPageUrl,
+        summaryElements: summaryElements || [],
+        errors: normalizedErrors,
+        summaryActions: summaryActions,
+        ...(summaryHtml ? { summaryHtml } : {}),
+        ...extraProps // ✅ Merge any additional developer-defined properties
+    };
+
+    // Construct default summaryActions
+    if (pageTitle && pageUrl) {
+        definition.summaryActions = [
+            {
+                text: govcyResources.staticResources.text.change,
+                classes: "govcy-d-print-none",
+                href: `${pageUrl}?route=review`,
+                visuallyHiddenText: pageTitle
+            }
+        ];
+    }
+
+    // Save definition
+    store.siteData[siteId].customPagesDefinition[pageUrl] = definition;
+
+}
+
+/**
+ * Retrieves the custom page definition for a given siteId and pageUrl.
+ * 
+ * @param {object} store The custom pages configuration store. Should be req.app
+ * @param {string} siteId The site id
+ * @param {string} pageUrl The URL of the custom page
+ * @returns {object} The custom page definition or an empty object if not found.
+ */
+export function getCustomPageDefinition(store, siteId, pageUrl) {
+    return store.siteData?.[siteId]?.customPagesDefinition?.[pageUrl] || {};
+}
+
+/**
+ * Resets the custom pages for a given siteId.
+ * This will deep copy the customPagesDefinition to customPages.
+ * This is useful for initializing or resetting the custom pages. 
+ * 
+ * @param {object} configStore The custom pages configuration store. Should be req.app
+ * @param {object} store The data layer store. Should be the req.session
+ * @param {string} siteId The site id
+ */
+export function resetCustomPages(configStore, store, siteId) {
+    if (!configStore?.siteData?.[siteId]?.customPagesDefinition) return;
+    // Reset custom pages for the given siteId based on the customPagesDefinition
+    store.siteData[siteId].customPages = JSON.parse(JSON.stringify(configStore.siteData[siteId].customPagesDefinition))
+}
+
+// ==========================================================
+// 🧰 Custom Page Error Helpers
+// ==========================================================
+
+/**
+ * Sets a custom property on a given custom page definition or instance.
+ * 
+ * @param {object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The custom page URL.
+ * @param {string} property - The property name to set.
+ * @param {*} value - The value to assign.
+ * @param {boolean} [isDefinition=false] - Whether to modify the global definition instead of session data.
+ */
+export function setCustomPageProperty(store, siteId, pageUrl, property, value, isDefinition = false) {
+    const container = isDefinition
+        ? store.siteData?.[siteId]?.customPagesDefinition
+        : store.siteData?.[siteId]?.customPages;
+
+    if (!container || !container[pageUrl]) {
+        console.warn(`⚠️ setCustomPageProperty: page '${pageUrl}' not found for site '${siteId}'`);
+        return;
+    }
+
+    container[pageUrl][property] = value;
+}
+
+/**
+ * Gets a custom property from a given custom page definition or instance.
+ * 
+ * @param {object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The custom page URL.
+ * @param {string} property - The property name to get.
+ * @param {boolean} [isDefinition=false] - Whether to read from the global definition instead of session data.
+ * @returns {*} The value of the property, or undefined if not found.
+ */
+export function getCustomPageProperty(store, siteId, pageUrl, property, isDefinition = false) {
+    const container = isDefinition
+        ? store.siteData?.[siteId]?.customPagesDefinition
+        : store.siteData?.[siteId]?.customPages;
+
+    return container?.[pageUrl]?.[property];
+}
+
+
+/**
+ * Sets the data object for a given custom page.
+ * Overwrites the existing data (does not merge).
+ * 
+ * @param {Object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The URL of the custom page.
+ * @param {Object} data - The data to store.
+ */
+export function setCustomPageData(store, siteId, pageUrl, data) {
+
+    const target = store.siteData?.[siteId]?.customPages?.[pageUrl];
+    if (!target) {
+        console.warn(`⚠️ setCustomPageData: page '${pageUrl}' not found for site '${siteId}'`);
+        return;
+    }
+
+    target.data = data; // overwrite existing data
+}
+
+/**
+ * Sets the email array with dsf-email-templates objects for a given custom page.
+ * Overwrites the existing data (does not merge).
+ * 
+ * @param {Object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The URL of the custom page.
+ * @param {Array<Object>} arrayOfEmailObjects - Array of dsf-email-templates objects.
+ */
+export function setCustomPageEmail(store, siteId, pageUrl, arrayOfEmailObjects) {
+
+    const target = store.siteData?.[siteId]?.customPages?.[pageUrl];
+    if (!target) {
+        console.warn(`⚠️ setCustomPageData: page '${pageUrl}' not found for site '${siteId}'`);
+        return;
+    }
+
+    if (!Array.isArray(arrayOfEmailObjects)) {
+        console.warn(`⚠️ setCustomPageEmail: expected array for custom page '${normalizedPageUrl}', got`, typeof arrayOfEmailObjects);
+        return;
+    }
+
+    target.email = arrayOfEmailObjects; // overwrite existing data
+}
+
+/**
+ * Sets the summaryElements array for a given custom page.
+ * Replaces the existing summaryElements array.
+ * 
+ * @param {Object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The URL of the custom page.
+ * @param {Array} summaryElements - Array of summary element definitions.
+ */
+export function setCustomPageSummaryElements(store, siteId, pageUrl, summaryElements) {
+
+    const target = store.siteData?.[siteId]?.customPages?.[pageUrl];
+    if (!target) {
+        console.warn(`⚠️ setCustomPageSummaryElements: page '${pageUrl}' not found for site '${siteId}'`);
+        return;
+    }
+
+    target.summaryElements = Array.isArray(summaryElements) ? summaryElements : [];
+}
+
+/**
+ * Clears all errors for a given custom page.
+ * Works on either customPages or customPagesDefinition.
+ * 
+ * @param {Object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The URL of the custom page.
+ */
+export function clearCustomPageErrors(store, siteId, pageUrl) {
+
+    const data = store.siteData?.[siteId]?.customPages?.[pageUrl];
+
+    if (data) data.errors = [];
+}
+
+/**
+ * Adds an error to a given custom page (definition or data).
+ * Auto-fills pageUrl and ensures array exists.
+ * 
+ * @param {Object} store - The store containing siteData.
+ * @param {string} siteId - The site identifier.
+ * @param {string} pageUrl - The URL of the custom page.
+ * @param {string} errorId - Unique identifier for the error.
+ * @param {Object} errorTextObject - Multilingual Object containing localized error texts.
+ */
+export function addCustomPageError(store, siteId, pageUrl, errorId, errorTextObject) {
+    const normalizedPageUrl = pageUrl.replace(/^\/+/, "");
+
+    const target =
+        store.siteData?.[siteId]?.customPages?.[pageUrl]
+
+    if (!target) {
+        console.warn(`⚠️ addCustomPageError: page '${pageUrl}' not found for site '${siteId}'`);
+        return;
+    }
+
+    target.errors ??= [];
+    
+    // ✅ Prevent duplicate errors by ID
+    if (target.errors.some(err => err.id === errorId)) return;
+
+    // Normalize and push error
+    target.errors.push({
+        id: errorId,
+        text: errorTextObject,
+        pageUrl: normalizedPageUrl,
+    });
+
+}

package/src/utils/govcyDataLayer.mjs

@@ -378,6 +378,23 @@ export function getSiteLoadData(store, siteId) {
     return null;
 }
 
+/**
+ * Get the site's custom pages from the store for custom pages
+ * 
+ * @param {object} store The session store
+ * @param {string} siteId |The site id
+ * @returns The site custom pages or null if none exist.
+ */
+export function getSiteCustomPages(store, siteId) {
+    const customPages  = store?.siteData?.[siteId]?.customPages  || {};
+
+    if (customPages ) {
+        return customPages ;
+    }
+
+    return null;
+}
+
 /**
  * Get the site's reference number from load data from the store 
  * 

package/src/utils/govcySubmitData.mjs

@@ -50,13 +50,13 @@ export function prepareSubmissionData(req, siteId, service) {
         if (page.updateMyDetails) {
             logger.debug("Preparing submission data for UpdateMyDetails page", { siteId, pageUrl });
             // Build the manual UMD page template
-            const umdTemplate  = createUmdManualPageTemplate(siteId, service.site.lang, page, req);
-            
+            const umdTemplate = createUmdManualPageTemplate(siteId, service.site.lang, page, req);
+
             // Extract the form element
-            formElement = umdTemplate .sections
+            formElement = umdTemplate.sections
                 .flatMap(section => section.elements)
                 .find(el => el.element === "form");
-            
+
             if (!formElement) {
                 logger.error("🚨 UMD form element not found during prepareSubmissionData", { siteId, pageUrl });
                 return handleMiddlewareError("🚨 UMD form element not found during prepareSubmissionData", 500, next);
@@ -190,11 +190,51 @@ export function prepareSubmissionData(req, siteId, service) {
 
     // Get the renderer data from the session store
     const reviewSummaryList = generateReviewSummary(printFriendlyData, req, siteId, false);
+
+    // ==========================================================
+    //  Custom pages
+    // ==========================================================
+    const customPages = dataLayer.getSiteCustomPages(req.session, siteId) || {};
+
+    // Convert submissionData keys into ordered array for splicing
+    const orderedEntries = Object.entries(submissionData);
+
+    // Loop through each custom page
+    for (const [customKey, customPage] of Object.entries(customPages)) {
+        const pageData = customPage?.data || "";
+        const insertAfter = customPage?.insertAfterPageUrl; // normalize
+
+        // Build a new entry for this custom page
+        const customEntry = [customKey, pageData];
+
+        if (insertAfter) {
+            // Find the index of the page to insert after
+            const idx = orderedEntries.findIndex(([pageUrl]) => pageUrl === insertAfter);
+            if (idx >= 0) {
+                // Insert right after the matched page
+                orderedEntries.splice(idx + 1, 0, customEntry);
+                continue;
+            }
+        }
+
+        // Fallback: append to the top
+        orderedEntries.unshift(customEntry);
+    }
+
+    // Convert back to an object in the new order
+    const orderedSubmissionData = Object.fromEntries(orderedEntries);
+
+    logger.info("Submission Data with custom pages merged");
+
+    // ==========================================================
+    //  END custom page merge
+    // ==========================================================
+
     // Prepare the submission data object
     return {
         submissionUsername: dataLayer.getUser(req.session).name,
         submissionEmail: dataLayer.getUser(req.session).email,
-        submissionData: submissionData, // Raw data as submitted by the user in each page
+        submissionData: orderedSubmissionData, // Raw data as submitted by the user in each page
         submissionDataVersion: service.site?.submissionDataVersion || service.site?.submission_data_version || "", // The submission data version
         printFriendlyData: printFriendlyData, // Print-friendly data
         rendererData: reviewSummaryList, // Renderer data of the summary list
@@ -259,12 +299,12 @@ export function preparePrintFriendlyData(req, siteId, service) {
 
         let pageTemplate = page.pageTemplate;
         let pageTitle = page.pageData.title || {};
-        
+
 
         // ----- MultipleThings hub handling
         if (page.updateMyDetails) {
             // create the page template
-            pageTemplate = createUmdManualPageTemplate(siteId, service.site.lang, page, req );
+            pageTemplate = createUmdManualPageTemplate(siteId, service.site.lang, page, req);
             // set the page title
             pageTitle = govcyResources.staticResources.text.updateMyDetailsTitle;
         }
@@ -642,6 +682,7 @@ export function generateReviewSummary(submissionData, req, siteId, showChangeLin
 
         // Add inner summary list to the main summary list
         let outerSummaryList = {
+            "pageUrl": pageUrl, // add pageUrl for change link
             "key": pageTitle,
             "value": [summaryListInner],
             "actions": [ //add change link
@@ -664,6 +705,76 @@ export function generateReviewSummary(submissionData, req, siteId, showChangeLin
 
     }
 
+    // ==========================================================
+    //  CustomPages
+    // ==========================================================
+    // Custom summaries are stored under:
+    //   session.siteData[siteId].customPages
+    // Each entry may include:
+    //   insertAfter: "pageUrl"
+    //   summary: array of summaryList items (same shape as generateReviewSummary output)
+    // OR
+    //   html: pre-rendered multilingual HTML block
+    // ==========================================================
+
+    const customPages = dataLayer.getSiteCustomPages(req.session, siteId);
+
+    for (const [key, block] of Object.entries(customPages)) { // 
+        // Build the structure the same way as a normal section
+        let customEntry;
+
+        let customValue = [];
+
+        if (block.summaryHtml) {
+            //  Direct HTML block
+            customValue = [
+                {
+                    element: "htmlElement",
+                    params: { text: block.summaryHtml }
+                }
+            ];
+        } else if (block.summaryElements) {
+            //  Already a ready-made summaryList object
+            customValue = [
+                {
+                    element: "summaryList",
+                    params: { items: block.summaryElements }
+                }
+            ];
+        } else {
+            //  Fallback empty block
+            continue; // skip this block if no valid content
+        }
+
+        customEntry = {
+            key: block.pageTitle || { en: key, el: key },
+            value: customValue,
+            actions: block.summaryActions || [] // Optional actions, e.g. change links
+        };
+
+        //  If showChangeLinks, remove the actions key
+        if (!showChangeLinks) {
+            delete customEntry.actions;
+        }
+
+        //  Insert custom summary section after given page
+        if (block.insertAfterPageUrl) {
+            const idx = summaryList.params.items.findIndex(
+                (p) => p.pageUrl === block.insertAfterPageUrl);
+            if (idx >= 0) {
+                summaryList.params.items.splice(idx + 1, 0, customEntry);
+            } else {
+                summaryList.params.items.push(customEntry); // fallback append
+            }
+        } else {
+            summaryList.params.items.unshift(customEntry); // fallback append
+        }
+    }
+
+    // ==========================================================
+    //  END customPages merge
+    // ==========================================================
+
     return summaryList;
 }
 
@@ -680,6 +791,14 @@ export function generateReviewSummary(submissionData, req, siteId, showChangeLin
  */
 export function generateSubmitEmail(service, submissionData, submissionId, req) {
     let body = [];
+    // ==========================================================
+    //  Custom page
+    // ==========================================================
+    const customPages = dataLayer.getSiteCustomPages(req.session, service.site.id) || {};
+    // Build a lookup for custom pages by insertAfterPageUrl
+    const customPageEntries = Object.entries(customPages);
+    let pagesInBody = [];
+    // ===========================================================
 
     //check if there is submission Id
     if (submissionId) {
@@ -772,8 +891,57 @@ export function generateSubmitEmail(service, submissionData, submissionId, req)
                 });
         }
 
+        // ==========================================================
+        //  Custom page
+        // ==========================================================
+        // 🆕 Check for custom pages that should appear after this one
+        for (const [customKey, customPage] of   customPageEntries) {
+            const insertAfter = customPage.insertAfterPageUrl;
+            if (insertAfter && insertAfter === pageUrl && Array.isArray(customPage.email)) {
+                pagesInBody.push(customPage.pageUrl); // Track custom page key for later
+                // Add data title to the body
+                body.push(
+                    {
+                        component: "bodyHeading",
+                        params: { "headingLevel": 2 },
+                        body: govcyResources.getLocalizeContent(customPage.pageTitle, req.globalLang)
+                    }
+                )
+                logger.debug(`📧 Inserting custom page email '${customKey}' after '${pageUrl}'`);
+                body.push(...customPage.email);
+            }
+        }
+        
+        // ==========================================================
+    }
+
+    // ==========================================================
+    //  Custom pages - Handle leftover custom pages not yet inserted
+    // ==========================================================
+    for (const [customKey, customPage] of customPageEntries) {
+        // check if this custom page was already inserted
+        const wasInserted = pagesInBody.includes(customKey);
+        // check if it has email content
+        const hasEmail = Array.isArray(customPage.email);
+        // get its title
+        const pageTitle = customPage.pageTitle;
+
+        // If not inserted and has email content, prepend it to the body
+        if (!wasInserted && hasEmail) {
+            // Prepend its email content
+            body.unshift(...customPage.email);
+            // Add a heading for visibility
+            body.unshift({
+                component: "bodyHeading",
+                params: { headingLevel: 2 },
+                body: govcyResources.getLocalizeContent(pageTitle, req.globalLang)
+            });
 
+            logger.debug(`📧 Adding leftover custom page '${customKey}' (no insertAfter match)`);
+        }
     }
+    // ==========================================================
+
 
     let emailObject = govcyResources.getEmailObject(
         service.site.title,
@@ -790,86 +958,3 @@ export function generateSubmitEmail(service, submissionData, submissionId, req)
     return emailRenderer.renderFromJson(emailObject);
 }
 
-
-
-/*
-{
- "bank-details": {
-   "formData": {
-     "AccountName": "asd",
-     "Iban": "CY12 0020 0123 0000 0001 2345 6789",
-     "Swift": "BANKCY2NXXX",
-     "_csrf": "sjknv79rxjgv0uggo0d5312vzgz37jsh"
-   }
- },
- "answer-bank-boc": {
-   "formData": {
-     "Objection": "Object",
-     "country": "Azerbaijan",
-     "ObjectionReason": "ObjectionReasonCode1",
-     "ObjectionExplanation": "asdsa",
-     "DepositsBOCAttachment": "",
-     "_csrf": "sjknv79rxjgv0uggo0d5312vzgz37jsh"
-   }
- },
- "bank-settlement": {
-   "formData": {
-     "ReceiveSettlementExplanation": "",
-     "ReceiveSettlementDate_day": "",
-     "ReceiveSettlementDate_month": "",
-     "ReceiveSettlementDate_year": "",
-     "ReceiveSettlement": "no",
-     "_csrf": "sjknv79rxjgv0uggo0d5312vzgz37jsh"
-   }
- }
-}
-
-
-
-[
- {
-   pageUrl: "personal-details",
-   pageTitle: { en: "Personal data", el: "Προσωπικά στοιχεία" }, // from pageData.title in correct language
-   fields: [
-     [
-       {
-           id: "firstName",
-           label: { en: "First Name", el: "Όνομα" },
-           value: "John",  // The actual user input value
-           valueLabel: { en: "John", el: "John" }  // Same label as the value for text inputs
-       },
-       {
-           id: "lastName",
-           label: { en: "Last Name", el: "Επίθετο" },
-           value: "Doe",  // The actual user input value
-           valueLabel: { en: "Doe", el: "Doe" }  // Same label as the value for text inputs
-       },
-       {
-           id: "gender",
-           label: { en: "Gender", el: "Φύλο" },
-           value: "m",  // The actual value ("male")
-           valueLabel: { en: "Male", el: "Άντρας" }  // The corresponding label for "male"
-       },
-       {
-           id: "languages",
-           label: { en: "Languages", el: "Γλώσσες" },
-           value: ["en", "el"],  // The selected values ["en", "el"]
-           valueLabel: [
-               { en: "English", el: "Αγγλικά" },  // Labels corresponding to "en" and "el"
-               { en: "Greek", el: "Ελληνικά" }
-           ]
-       },
-       {
-           id: "birthDate",
-           label: { en: "Birth Date", el: "Ημερομηνία Γέννησης" },
-           value: "1990-01-13",  // The actual value based on user input
-           valueLabel: "13/1/1990"  // Date inputs label will be conveted to D/M/YYYY
-       }
-   ]
- },
- ...
-]
-
-
-
-   */