@companieshouse/ch-node-utils 1.3.7 → 1.3.8

package/README.md

@@ -77,10 +77,11 @@ Available as a normal npm dependency([here on npmjs](https://www.npmjs.com/packa
 |`CH_NODE_UTILS_DROP_LANG_QUERY_PARAM`| It could be set to [drop the lang="xx" query param](https://github.com/companieshouse/ch-node-utils/blob/f9e5c47a86206f0b12e4e536c4c459db16747631/src/middleware/manageLocales.middleware.ts#L25) from the current URL ([see Example](https://github.com/companieshouse/docker-chs-development/blob/842c61245adcbba02a6316847fc4f9d94c52410d/services/modules/dissolution/dissolution-web.docker-compose.yaml#L50)) |
 |`CH_NODE_UTILS_LOG_LVL`| It could be set to ["TRACE" or "DEBUG" (case insensitive)](https://github.com/companieshouse/ch-node-utils/blob/24bc717477d21082439d1b460108cb0d60465f0f/src/utils/log.ts#L2) to dump internal info while inside ch-node-utils ([see Example](https://github.com/companieshouse/docker-chs-development/blob/842c61245adcbba02a6316847fc4f9d94c52410d/services/modules/dissolution/dissolution-web.docker-compose.yaml#L49))|
 
-### Menu navigation bar
-A menu navigation bar component has been added to make it easier to add links pointing to new services when needed. There are two Nunjucks macros: one that adds a menu navigation bar with the provided items and another that adds a menu navigation bar with predefined items. The latter internally uses the former and at the moment contains links to the following service:
+### Menu Navigation Bar
 
-- Authorised agent
+A menu navigation bar component has been added to make it easier to add links pointing to new services when needed. There are two Nunjucks macros: one that adds a menu navigation bar with the provided items and another that adds a menu navigation bar with predefined items. The latter internally uses the former and currently contains links to the following services:
+
+- Authorised agent (conditional)
 - Your companies
 - Your filings
 - Companies you follow
@@ -90,7 +91,30 @@ A menu navigation bar component has been added to make it easier to add links po
 
 The "Authorised agent" menu item appears conditionally if the logged user has ACSP membership.
 
-The navbar requires importing language files from the `locales` folder in ch-node-utils and making them available to all Nunjuck templates using the [`addGlobal()` function](https://mozilla.github.io/nunjucks/api.html#addglobal) in `app.ts`. At the moment only English and Welsh language versions are supported. It also requires a flag `displayAuthorisedAgent` set the same way for displaying the "Authorised agent" menu item. If the logged user has ACSP membership, this flag should be set to `'yes'`.
+#### Usage
+
+To use the predefined navbar, import the macro and call it with the required parameters:
+
+```nunjucks
+{% from "navbar.njk" import addPredefinedNavbar %}
+
+{{ addPredefinedNavbar(userEmailAddress, chsMonitorGuiUrl, lang, displayAuthorisedAgent) }}
+```
+
+The macro requires the following parameters:
+
+- `userEmailAddress`: The email address of the logged-in user
+- `chsMonitorGuiUrl`: The URL for the "Companies you follow" link
+- `lang`: An object containing language-specific strings for localization
+- `displayAuthorisedAgent`: A flag for displaying the "Authorised agent" menu item. If the logged user has ACSP membership, this flag should be set to `'yes'`
+
+#### Localization
+
+The navbar uses translations from `@companieshouse/ch-node-utils` (this) package. To set this up:
+
+1. Ensure the `@companieshouse/ch-node-utils` package is installed. i.e `npm i @companieshouse/ch-node-utils`
+2. Update your i18 middleware to load and merge translations from both sources. (`@companieshouse/ch-node-utils/locales`)
+3. Add the `@companieshouse/ch-node-utils/templates` directory to the Nunjucks loader paths.
 
 The navbar also requires the use of styles provided in the [ch.gov.uk.css](https://github.com/companieshouse/cdn.ch.gov.uk/blob/master/app/assets/stylesheets/ch.gov.uk.css) stylesheet (you can either add the provided link to the head section or include specific styles in your own stylesheet)
 
@@ -99,4 +123,3 @@ The navbar also requires the use of styles provided in the [ch.gov.uk.css](https
 It also requires the [navbar.js](https://github.com/companieshouse/cdn.ch.gov.uk/blob/master/app/assets/javascripts/lib/navbar.js) script to be added to the footer to make the navbar work in mobile mode
 
 `<script src="{{ cdnHost }}/javascripts/lib/navbar.js"></script>`
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companieshouse/ch-node-utils",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "author": "companieshouse",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

package/templates/navbar.njk

@@ -26,8 +26,9 @@ It receives:
     - href: the URL of the page the menu item will point to
     - displayText: the text to display in the anchor
 - userDisplayText: a text identifying the logged user, e.g. email address or name
+- lang: an object containing language-specific strings for localization
 #}
-{% macro addNavbar(signInHref, menuItems, userDisplayText) %}
+{% macro addNavbar(signInHref, menuItems, userDisplayText, lang) %}
     <div class="js-toggle-nav" id="global-nav">
         <nav role="navigation" class="content" aria-label="{{ lang.mainNavbar or 'The main navigation bar' }}">
             {% if userDisplayText %}
@@ -57,8 +58,10 @@ A macro that adds a menu navigation bar with predefined items.
 It receives:
 - userDisplayText: a text identifying the logged user, e.g. email address or name
 - chsMonitorGuiUrl: the URL for the 'Companies you follow' link
+- lang: an object containing language-specific strings for localization
+- displayAuthorisedAgent: a flag indicating whether to display the 'Authorised agent' menu item
 #}
-{% macro addPredefinedNavbar(userDisplayText, chsMonitorGuiUrl) %}
+{% macro addPredefinedNavbar(userDisplayText, chsMonitorGuiUrl, lang, displayAuthorisedAgent) %}
     {% set menuItems = [
         { id: "authorised-agent", href: "/authorised-agent", displayText: lang.authorisedAgent or "Authorised agent" } if displayAuthorisedAgent === "yes",
         { id: "your-companies", href: "/your-companies", displayText: lang.yourCompanies or "Your companies" },
@@ -69,6 +72,6 @@ It receives:
         { id: "user-signout", href: "/signout", displayText: lang.signOut or "Sign out" }
     ] | reject("falsy") %}
 
-    {{ addNavbar("/signin", menuItems, userDisplayText) }}
+    {{ addNavbar("/signin", menuItems, userDisplayText, lang) }}
 
-{% endmacro %}
+{% endmacro %}