@companieshouse/ch-node-utils
v1.3.14
Published
set of node utils which can be used across repos/projects
Downloads
2,199
Maintainers
Keywords
Readme
ch-node-utils
set of node utils which can be used across repos/projects. Available as a normal npm dependency(here on npmjs)
Areas for the different utilities stored in this repo:
i18n (Internationalisation)
Internationalisation has been added to CHS, after already being available (at least for Welsh) on legacy systems (EWF/SCRS/CHD/...)
The implementation is described in Confluence for both Java and Node.js services.
Some common utilities for Node.js are here provided. The chosen Node.js i18n library is i18next, which, at the time of writing, can be considered the standard:
i18nCh.ts
: wrapper to i18nextlanguageNames.ts
: to manage Language names and their associated ISO codes (iso-639). It mainly provides:- a function to get, from an array of submitted iso-codes, a structured array of iso-codes & native names.
Ex:
[... "en", "cy", ...] ==> [ ... {"IsoCode": "en", "Name": "English" }, {"IsoCode": "cy", "Name": "Cymraeg" } ...]
- a custom function to sort the supported locales (apart from leaving 'en' always at 1st position, it sorts alphabetically)
subDirs.ts
: to manage files and dirs, so that i18n locales' folders can be sourced automatically. This allows for example to have an array of iso-codes if the./locales
dir follows the normal convention. Ex, this array of iso-codes[ "ar", "bn", "cy", "de", "en", "gd", "ja", "uk"]
is retrieved from the following tree:│ ├── locales │ │ ├── ar │ │ │ ├── errors.json │ │ │ ├── global.json │ │ │ ├── landing.json │ │ │ ├── layout.json │ │ │ ├── search-company.json │ │ │ ├── view-company-information.json │ │ │ └── who-to-tell.json │ │ ├── bn │ │ │ └── *.json │ │ ├── cy │ │ │ └── *.json │ │ ├── de │ │ │ └── *.json │ │ ├── en │ │ │ └── *.json │ │ ├── gd │ │ │ └── *.json │ │ ├── ja │ │ │ └── *.json │ │ ├── uk │ │ │ └── *.json
manageLocales.middleware.ts
: middleware that can be reused to manage locales while dealing with http requests.add-lang-to-url.njk
: to add thelang=xx
query param to urls:
https://.....<self>....../?lang=cy
locales-banner.njk
: to add the locales banner
ENV VARS
: the following ENV vars are used:
| ENV VAR | Description |
| ------- | ----------- |
|CH_NODE_UTILS_DROP_LANG_QUERY_PARAM
| It could be set to drop the lang="xx" query param from the current URL (see Example) |
|CH_NODE_UTILS_LOG_LVL
| It could be set to "TRACE" or "DEBUG" (case insensitive) to dump internal info while inside ch-node-utils (see Example)|
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 currently contains links to the following services:
- Authorised agent (conditional)
- Your companies
- Your filings
- Companies you follow
- Basket
- Manage account
- Sign out
The "Authorised agent" menu item appears conditionally if the logged user has ACSP membership.
Usage
To use the predefined navbar, import the macro and call it with the required parameters:
{% from "navbar.njk" import addPredefinedNavbar %}
{{ addPredefinedNavbar(userEmailAddress, chsMonitorGuiUrl, lang, displayAuthorisedAgent) }}
The macro requires the following parameters:
userEmailAddress
: The email address of the logged-in userchsMonitorGuiUrl
: The URL for the "Companies you follow" linklang
: An object containing language-specific strings for localizationdisplayAuthorisedAgent
: A flag for displaying the "Authorised agent" menu item. If the logged user has ACSP membership, this flag should be set to'yes'
. If your service uses i18 middleware provided in the@companieshouse/ch-node-utils
package, then this flag will be set to the correct value automatically. If not, you can useisAuthorisedAgent
function from./utils/sessionUtils
.
Localization
The navbar uses translations from @companieshouse/ch-node-utils
(this) package. To set this up:
- Ensure the
@companieshouse/ch-node-utils
package is installed. i.enpm i @companieshouse/ch-node-utils
- Update your i18 middleware to load and merge translations from both sources. (
@companieshouse/ch-node-utils/locales
) - 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 stylesheet (you can either add the provided link to the head section or include specific styles in your own stylesheet)
<link href="{{ cdnHost }}/stylesheets/ch.gov.uk.css" rel="stylesheet"/>
It also requires the 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>