Move base layout into nunjucks options

Author: alexluckett

docs/GETTING_STARTED.md

@@ -92,16 +92,44 @@ await server.register({
   }
 })
 
+const viewPaths = [join(config.get('appDir'), 'views')]
+
 // Register the `forms-engine-plugin`
 await server.register({
-  plugin
+  plugin,
+  options: {
+    cacheName: 'session', // must match a session you've instantiated in your hapi server config
+    /**
+     * Options that DXT uses to render Nunjucks templates
+     */
+    nunjucks: {
+      basePageLayout: 'your-base-layout.html', // the base page layout. Usually based off https://design-system.service.gov.uk/styles/page-template/
+      viewPaths // list of directories DXT should use to render your views. Must contain basePageLayout.
+    },
+    /**
+     * Services is what DXT uses to interact with external APIs
+     */
+    services: {
+      formsService, // where your forms should be downloaded from.
+      formSubmissionService, // handles temporary storage of file uploads
+      outputService // where your form should be submitted to
+    },
+    /**
+     * View context attributes made available to your pages. Returns an object containing an arbitrary set of key-value pairs.
+     */
+    viewContext: (request) => {
+      "example": "hello world" // available to render on a nunjucks page as {{ example }}
+    }
+  }
 })
 
 await server.start()
 ```
 
 ## Step 3: Handling static assets
 
+TODO: CSS will be updated with a proper build process using SASS.
+
 1. [Update webpack to bundle the DXT application assets (CSS, JavaScript, etc)](https://github.com/DEFRA/forms-engine-plugin-example-ui/pull/1/files#diff-1fb26bc12ac780c7ad7325730ed09fc4c2c3d757c276c3dacc44bfe20faf166f)
 2. [Serve the newly bundled assets from your web server](https://github.com/DEFRA/forms-engine-plugin-example-ui/pull/1/files#diff-e5b183306056f90c7f606b526dbc0d0b7e17bccd703945703a0811b6e6bb3503)
 

src/server/plugins/engine/configureEnginePlugin.ts

@@ -41,6 +41,7 @@ export const configureEnginePlugin = async ({
       controllers,
       cacheName: 'session',
       nunjucks: {
+        baseLayoutPath: 'dxt-devtool-baselayout.html',
         paths: [join(findPackageRoot(), 'src/server/devserver')] // custom layout to make it really clear this is not the same as the runner
       },
       viewContext: devtoolContext

src/server/plugins/engine/plugin.ts

@@ -92,11 +92,12 @@ export interface PluginOptions {
   filters?: Record<string, FilterFunction>
   pluginPath?: string
   nunjucks: {
+    baseLayoutPath: string
     paths: string[]
   }
   viewContext: (
     request: FormRequest | FormRequestPayload | null
-  ) => Record<string, unknown> & { baseLayoutPath?: string }
+  ) => Record<string, unknown>
 }
 
 export const plugin = {
@@ -171,6 +172,7 @@ export const plugin = {
       }
     })
 
+    server.expose('baseLayoutPath', nunjucksOptions.baseLayoutPath)
     server.expose('viewContext', viewContext)
     server.expose('cacheService', cacheService)
 

src/server/plugins/nunjucks/context.js

@@ -34,14 +34,23 @@ export function context(request) {
   const pluginStorage = request?.server.plugins['forms-engine-plugin']
   let consumerViewContext = {}
 
-  if (pluginStorage && 'viewContext' in pluginStorage) {
+  if (!pluginStorage) {
+    throw Error('context called before plugin registered')
+  }
+
+  if (!pluginStorage.baseLayoutPath) {
+    throw Error('Missing baseLayoutPath in plugin.options.nunjucks')
+  }
+
+  if ('viewContext' in pluginStorage) {
     consumerViewContext = pluginStorage.viewContext(request)
   }
 
   /** @type {ViewContext} */
   const ctx = {
     // take consumers props first so we can override it
     ...consumerViewContext,
+    baseLayoutPath: pluginStorage.baseLayoutPath,
     appVersion: pkg.version,
     config: {
       cdpEnvironment: config.get('cdpEnvironment'),
@@ -52,7 +61,7 @@ export function context(request) {
       serviceVersion: config.get('serviceVersion')
     },
     crumb: safeGenerateCrumb(request),
-    currentPath: request ? `${request.path}${request.url.search}` : undefined,
+    currentPath: `${request.path}${request.url.search}`,
     previewMode: isPreviewMode ? params?.state : undefined,
     slug: isResponseOK ? params?.slug : undefined
   }
@@ -76,7 +85,6 @@ export function devtoolContext() {
   }
 
   return {
-    baseLayoutPath: 'dxt-devtool-baselayout.html', // from plugin.options.nunjucks.paths
     assetPath: '/assets',
     getDxtAssetPath: (asset = '') => {
       return `/${webpackManifest?.[asset] ?? asset}`

src/server/plugins/nunjucks/types.js

@@ -12,6 +12,7 @@
 /**
  * @typedef {object} ViewContext - Nunjucks view context
  * @property {string} appVersion - Application version
+ * @property {string} [baseLayoutPath] - Base layout path
  * @property {Partial<Config>} config - Application config properties
  * @property {string} [crumb] - Cross-Site Request Forgery (CSRF) token
  * @property {string} [cspNonce] - Content Security Policy (CSP) nonce

src/typings/hapi/index.d.ts

@@ -20,6 +20,7 @@ declare module '@hapi/hapi' {
       generate?: (request: Request | FormRequest | FormRequestPayload) => string
     }
     'forms-engine-plugin': {
+      baseLayoutPath: string
       cacheService: CacheService
       viewContext: context
     }