{"id":23819823,"url":"https://github.com/kth/kth-node-web-common","last_synced_at":"2025-09-07T02:30:52.318Z","repository":{"id":45639690,"uuid":"89585321","full_name":"KTH/kth-node-web-common","owner":"KTH","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-01T05:00:17.000Z","size":1225,"stargazers_count":0,"open_issues_count":8,"forks_count":1,"subscribers_count":19,"default_branch":"main","last_synced_at":"2024-12-21T08:20:22.482Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KTH.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-27T10:23:21.000Z","updated_at":"2024-11-21T06:22:39.000Z","dependencies_parsed_at":"2023-01-20T15:46:40.684Z","dependency_job_id":"c12d7a01-7a04-4988-9889-b40d68b1435d","html_url":"https://github.com/KTH/kth-node-web-common","commit_stats":{"total_commits":173,"total_committers":16,"mean_commits":10.8125,"dds":0.7861271676300579,"last_synced_commit":"853b1dcc4a50d799abd2cd0d9e4b4fc114ec333b"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-web-common","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-web-common/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-web-common/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-web-common/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KTH","download_url":"https://codeload.github.com/KTH/kth-node-web-common/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232163091,"owners_count":18481581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-02T07:16:02.733Z","updated_at":"2025-09-07T02:30:52.304Z","avatar_url":"https://github.com/KTH.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @kth/kth-node-web-common\n\n## Header Content Helpers\n\nThis is a set of standard helpers that are useful in most [KTH/node-web](https://github.com/KTH/node-web) projects.\n\n### Register Helpers\n\n```javascript\nconst registerHeaderContentHelper = require('@kth/kth-node-web-common/lib/handlebars/helpers/headerContent')\n\nregisterHeaderContentHelper({\n  proxyPrefixPath: '/app/mount/point',\n  version: 'x.x.x',\n})\n```\n\n### Use in Handlebars Templates\n\n- {{ extend name options }} -- calls the function options.fn with content of block **name** as param and adds it to named block\n- {{ prefixScript url name }} -- add a script tag with version set to script block **name**\n- {{ prefixModuleScript url name }} -- add a script tag with type module and with version set to script block **name**\n- {{ prefixStyle url name media }} -- add a style tag for named media type with version set to style block **name**\n- {{ render name }} -- used by a layout to render script and style blocks in appropriate places\n- {{ withVersion url }} -- appends `'?v=' + version` to the passed string\n\n## Conditional Logotype Src Helper\n\nA helper that dynamically renders the logotype's source path, avoiding the use of multiple image tags by setting the correct source path through server-side logic.\n\n```javascript\n// Import the helper\nconst { registerConditionalLogotypeSrcHelper } = require('@kth/kth-node-web-common/lib/handlebars/helpers/conditionalLogotypeSrc')\n\n// Register the helper\nregisterConditionalLogotypeSrcHelper()\n\n// Use the helper in a template\n{{conditionalLogotypeSrc theme proxyPrefix}}\n\n```\n\n## Breadcrumb Helper\n\nHelper to generate breadcrumb markup.\n\n```javascript\n// Import the helper\nconst { registerBreadcrumbHelper } = require('@kth/kth-node-web-common/lib/handlebars/helpers/breadcrumbs')\n\n// Register the helper\nregisterBreadcrumbHelper()\n\n// Use the helper in a template\n{{breadcrumbs breadcrumbsPath}}\n\n// Add breadcrumbs to res.render\nres.render(breadcrumbsPath: [{url: 'https://kth.se', label: 'KTH'}, ...], ...)\n\n// Import the needed css from @kth/style\n@use '@kth/style/scss/components/breadcrumbs.scss';\n```\n\n## Language Link Helper\n\nHandlebars helper to generate a language link in the header. If language can’t be toggled with query parameter `l`, then there is an option to display a dialog with a custom link.\n\n### Register helper\n\n```javascript\n// Typically server/views/helpers/index.js\n\nconst { registerLanguageLinkHelper } = require('@kth/kth-node-web-common/lib/handlebars/helpers/languageLink')\n\nregisterLanguageLinkHelper()\n```\n\n### Add language constants\n\nAll language constants are optional.\n\n- `language_link_lang_[en/sv]`: Default label for the anchor element's text, if a custom one isn’t provided. Remember that it should be displayed in the opposite language, e.g. if the page is in English the label should be _Svenska_\n- `language_link_button_close`: The label for the close button in the dialog element. Only used if there’s a dialog.\n- `language_link_not_translated`: The label for the dialog element's text. Only used if there’s a dialog.\n\n```javascript\n// Example in i18n/messages.se.js\n\nlanguage_link_lang_en: 'English',\nlanguage_link_not_translated: 'Den här sidan är ej översatt',\nlanguage_link_button_close: 'Stäng',\n```\n\n### Styling\n\nMake sure to include styling from KTH Style.\n\n```css\n/* Typically application’s main Sass-file */\n\n@use '~@kth/style/scss/components/translation-panel';\n```\n\n### Initialize menu panel\n\nMake sure to initialize the menu panel (dialog).\n\n```html\n// Typically in server/views/layouts/publicLayout.handlebars\n\n\u003cscript type=\"module\"\u003e\n  import { MenuPanel } from '{{proxyPrefix}}/assets/js/index.js'\n  MenuPanel.initTranslationModal(\n    document.querySelector('.kth-menu-item.language'),\n    document.querySelector('.kth-translation')\n  )\n\u003c/script\u003e\n```\n\n### Use handlebars helper in head\n\nInclude the handlebars helper in the template.\n\n```handlebars\n\u003c!-- Typically in server/views/partials/kthHeader.handlebars --\u003e\n\n{{{languageLink lang}}}\n```\n\nIf no translated page exists, a dialog should be shown on link clink. This can be achieved by passing additional arguments to the helper.\n\n1. The first argument is `lang`, the current language. It is required.\n2. The second argument is `anchorMessageKey`, the i18n key for the anchor element's text. Can be omitted (or pass `null`) for default label.\n3. The third argument is `link`, the URL to navigate to when the anchor is clicked. If provided, a dialog element is also generated.\n4. The fourth argument is `dialogMessageKey`, the i18n key for the dialog element's text. Required if `link` is provided.\n\n```handlebars\n\u003c!-- Typically in server/views/partials/kthHeader.handlebars --\u003e\n\n{{{languageLink lang anchorMessageKey link dialogMessageKey}}}\n```\n\nUse any variable names, only the argument order matters. Remember that they don’t have to have values. The full signature can be used in the handlebars template, with values only being set in the controller when non-default behavior is needed.\n\n### Common use case\n\nThe most common use case is probably that a translated page can be reached by simply adding the query parameter `l`, with a language key like `en`. To achieve this, follow these steps:\n\n1. Include the handlebars helper in the header partials template, `{{{languageLink lang}}}`\n2. Add `language_link_lang_sv: 'Svenska'` and `language_link_lang_en: 'English'` to `messages.en.js` and `messages.sv.js` respectively\n3. Verify that `lang` is passed to `render` in the controller.\n\nA link to the opposite language page will now appear in the head.\n\n## Crawler Redirect\n\nMiddleware to handle redirects for crawlers.\n\n```JavaScript\nconst excludePath = '/app/mount/point' + '(?!/static).*'\nconst excludeExpression = new RegExp(excludePath)\nserver.use(excludeExpression, require('@kth/kth-node-web-common/lib/web/crawlerRedirect')({\n  hostUrl: 'http://sertver_host:port',\n}))\n```\n\n## Language\n\nMiddleware and helper methods to set and get language for this request.\n\nRegister the middleware:\n\n```JavaScript\nconst { languageHandler } = require('@kth/kth-node-web-common/lib/language')\nsever.use('/app/mount/point', languageHandler)\n```\n\nIn a controller you can get the language using the helper method **getLanguage**:\n\n```JavaScript\nconst language = require('@kth/kth-node-web-common/lib/language')\nconst lang = language.getLanguage(res)\n\n```\n\n## Error Pages\n\nThere is a helper for rendering error pages with proper styling\n\nTo use it, the following must be configured:\n\n- [Register handlebar helpers](#handlebar-helpers)\n\n### Include common error messages from the package into your application\n\nIn your application, add the following into your `i18n/index.js`\n\n```JavaScript\n// Include error messages from kth-node-web-common package\nconst errorMessagesEnglish = require('kth-node-web-common/lib/i18n/errorMessages.en')\nconst errorMessagesSwedish = require('kth-node-web-common/lib/i18n/errorMessages.sv')\n\n// Include application messasges\nconst messagesEnglish = require('./messages.en')\nconst messagesSwedish = require('./messages.se')\n\n// Add the error messages to the application defined messages before pushing them.\nmessagesSwedish.messages = { ...messagesSwedish.messages, ...errorMessagesSwedish.messages }\nmessagesEnglish.messages = { ...messagesEnglish.messages, ...errorMessagesEnglish.messages }\n\n```\n\n### Import helpers\n\nImport the helper and use as a [final](#use-the-function-from-the-kth-node-web-common-package-in-the-apllication-systemctrljs) method to express\n\n```javascript\nconst errorHandler = require('kth-node-web-common/lib/error')\n\n// commonly found in systemCtrl.js\nfunction _final(err, req, res, next) {\n  errorHandler.renderErrorPage(res, req, statusCode, i18n, isProd, lang, err)\n}\n```\n\n## Migrate to Version 9\n\n### Handlebar Helpers\n\nThe import of the breadcrumb helper has changed. It is now imported as a named import.\n\n```javascript\n// Usually found in server/views/helpers/index.js\n\n// Old import\nconst registerBreadcrumbHelper = require('@kth/kth-node-web-common/lib/handlebars/helpers/breadcrumbs')\n\n// New import\nconst { registerBreadcrumbHelper } = require('@kth/kth-node-web-common/lib/handlebars/helpers/breadcrumbs')\n\n// Old register helper\nregisterBreadcrumbHelper({\n  proxyPrefixPath: '/app/mount/point',\n  version: 'x.x.x',\n})\n\n// New register helper\nregisterBreadcrumbHelper()\n```\n\nThe function `registerBreadcrumbHelper` no longer takes any config. All breadcrumbs now need to be manually sent to `res.render` on every request.\n\n```javascript\n// Generic example of how to use the breadcrumb helper in controllers\nconst breadcrumbList = [\n  { url: 'https://kth.se', label: 'KTH' },\n  { url: '/en', label: 'International website' },\n]\n\nfunction index(req, res, next) {\n  res.render('index', {\n    breadcrumbList,\n  })\n}\n```\n\n## Migrate to Version 8\n\nFirst, make sure your code is up to date with [Migrate to version 6](#migrate-to-version-6)\n\nThe error page can now be rendered directly from inside the package. No need to copy and register the Handlebars-file from the app.\n\nIf the app only renders the error page via the `renderErrorPage` helper, you can remove lines like below:\n\n```bash\nmkdir -p ./server/views/system ./server/views/layouts\n\ncp ./node_modules/@kth/kth-node-web-common/lib/handlebars/pages/views/ ...\n\ncp ./node_modules/@kth/kth-node-web-common/lib/handlebars/pages/layouts/ ...\n```\n\nThey are usually located in `build.sh`, or in the scripts section of `package.json`\n\n⚠️ **Warning** it will still be possible to copy the handlebar files to your applications, but they will no longer be updated, and will probalby be removed in the future. ⚠️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkth%2Fkth-node-web-common","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkth%2Fkth-node-web-common","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkth%2Fkth-node-web-common/lists"}