Merge branch 'base' into production

.gitignore

@@ -69,3 +69,7 @@ Thumbs.db
 
 # Dev config files
 /src/assets/config/config-*.ts
+
+# Static html files
+/src/static-html/collection-toc/*
+!/src/static-html/collection-toc/.gitkeep

CHANGELOG.md

@@ -18,11 +18,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 
 
+## [1.3.0] – 2024-02-16
+
+### Added
+
+- Config options to enable server-side rendering of the collection side menu and prebuild static versions of the menu: `config.app.ssr.collectionSideMenu` and `config.app.prebuild.staticCollectionMenus`. Both options are booleans. `config.app.ssr.collectionSideMenu` defaults to `false`, which means that rendering of the dynamic collection side menu is not performed on the server, but deferred to the browser. This increases performance on the server for projects that have very large collections (hundreds of texts/collection). `config.app.prebuild.staticCollectionMenus` defaults to `true`, which means that static HTML versions of each collection menu, in each project language, are generated when the Docker image of the app is built. The static collection menus are included in the server-side rendering of collection pages, and then replaced with the dynamic collection menus in the browser. This improves SEO of collection pages when server-side rendering of collection menus is disabled, without degrading the user experience. Setting both new options to `false` puts the least load on the server, but makes the web app less crawlable by robots. **Notice** that the static menus are generated during *build-time* – if the collection table of contents are updated in the backend, a new build has to be created for the changes to be reflected in the static menus. ([a25be18](https://github.com/slsfi/digital-edition-frontend-ng/commit/a25be1899f2e35e3cb8dec398907738bc573427b), [78108e3](https://github.com/slsfi/digital-edition-frontend-ng/commit/78108e32352caed9d111d11d7fefb9f5c8f8ef32), [2ec89c3](https://github.com/slsfi/digital-edition-frontend-ng/commit/2ec89c39b0fdd86447ce53a49b041fcdd41be2c4), [5848028](https://github.com/slsfi/digital-edition-frontend-ng/commit/5848028bc11c3ed0470c3d2735b9038f4c85bbde))
+- Config option to control the generation of a sitemap file in a prebuild step: `config.app.prebuild.sitemap`. Defaults to `true`. ([02d8b65](https://github.com/slsfi/digital-edition-frontend-ng/commit/02d8b6558ce5e80e7c56f896a24bf536d5001c61))
+- Config option to define the intrinsic dimensions of the default banner image on the home page: `config.page.home.bannerImage.intrinsicSize`. The option defaults to `null`, meaning that the `height` and `width` attributes are not set on the image. The option takes an object with `height` and `width` keys and their respective values as numbers (the implicit unit is pixels). Setting the intrinsic dimensions of the image file (defined by the `config.page.home.bannerImage.URL` option) is recommended since the browser can then calculate the aspect ratio of the image, which improves initial page rendering. ([4495d91](https://github.com/slsfi/digital-edition-frontend-ng/commit/4495d915fd9899a28745d7f2de9cd61482e4bf21))
+- Config option to define alternate image sources for the banner image on the home page: `config.page.home.bannerImage.alternateSources`. The option defaults to an empty array, which means that the banner image is rendered like before using the image URL provided in `config.page.home.bannerImage.URL`. The new `alternateSources` option takes an array of objects. If the array is non-empty, the banner image will be created as a [`<picture>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) element with each of the objects in the array specifying a [`<source>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source) HTML element. The object can contain key-value pairs where the keys are the allowed attributes of the `<source>` element (`media`, `srcset`, `sizes`, `type`, `height`, `width`) and the values are strings or numbers defining the values of the corresponding attributes. For examples, see the forthcoming documentation. Using the `alternateSources` option makes it possible to define responsive images for the banner image (serve different image files based on screen resolution) and serve modern image formats like AVIF for reduced bandwidth. The default image defined by the `URL` option is still needed – it is used as the fallback image defined by the `<img>` element in the `<picture>` element. ([49708b7](https://github.com/slsfi/digital-edition-frontend-ng/commit/49708b7a82290df89df6e8f22ccc4ec780d6fc2d))
+- The current text title in the text-changer component is appended with the value of the `text_two` property of the TOC item if the property exists. The previous/next text buttons have been changed into links and are thus crawlable. ([5848028](https://github.com/slsfi/digital-edition-frontend-ng/commit/5848028bc11c3ed0470c3d2735b9038f4c85bbde))
+- `Vary: User-Agent` HTTP response header to server-side rendered content. This enables more efficient caching and improves SEO by telling browsers etc. that the content varies by user agent (mobile vs desktop). ([1160490](https://github.com/slsfi/digital-edition-frontend-ng/commit/116049015209c7f0e8a124b90c513f1b1194d49a))
+
+### Changed
+
+- Defer loading of the facsimile component on the collection text page to the browser. This increases server-side rendering performance since the component isn’t rendered on the server. ([69fa89a](https://github.com/slsfi/digital-edition-frontend-ng/commit/69fa89ae585b486594f905e649cb46262e38a330), [5bbdaae](https://github.com/slsfi/digital-edition-frontend-ng/commit/5bbdaae6f93b9e7223ddcb122fe031aa896479b6))
+- Defer loading of the illustrations component on the collection text page to the browser. This increases server-side rendering performance since the component isn’t rendered on the server. ([eb60a82](https://github.com/slsfi/digital-edition-frontend-ng/commit/eb60a8292fa912bad9636c980dbafaa75121e081))
+- Defer loading of the epub viewer component to the browser, since it’s not SSR-compatible. The epub title is shown as a `<h1>` placeholder in the server response. Also show pdf title as `<h1>` in the pdf viewer component. ([7658b71](https://github.com/slsfi/digital-edition-frontend-ng/commit/7658b71b5eef956c5d012589dbaa08df6820872a))
+- Refactor requests for flattened collection table of contents to use function in the collection TOC service. ([a6b643b](https://github.com/slsfi/digital-edition-frontend-ng/commit/a6b643b490eccf9241eb221a7dae5d2c41162711))
+- Refactor the download texts modal to get the current text title from the document head service. ([baa0a44](https://github.com/slsfi/digital-edition-frontend-ng/commit/baa0a4437c7bfe0d1e14c04c896d52180f6f38ac))
+- Update the development notes with brief descriptions of dependencies. ([34a1a7c](https://github.com/slsfi/digital-edition-frontend-ng/commit/34a1a7cbdf9ed04dde97a0dc141b0daf8c8d9273))
+- Deps: update `@angular` to 17.2.1. ([e78ed03](https://github.com/slsfi/digital-edition-frontend-ng/commit/e78ed039c3097d6789500324ceb5262399e023c7), [0dffb42](https://github.com/slsfi/digital-edition-frontend-ng/commit/0dffb421f71dd199a8bfd456934168030dbaff5d), [073f167](https://github.com/slsfi/digital-edition-frontend-ng/commit/073f167d93edf3355b80c1ce2db8811e46c3d9b0))
+- Deps: update `@ionic` to 7.7.2. ([5b57491](https://github.com/slsfi/digital-edition-frontend-ng/commit/5b5749109f8ae9d7f468ccd8099782b7e336d531), [7bd4e41](https://github.com/slsfi/digital-edition-frontend-ng/commit/7bd4e414cb3ee0fad266fa83c5f72b8329817904), [ad8b502](https://github.com/slsfi/digital-edition-frontend-ng/commit/ad8b502ef6af7b46482da02a7c5188313ad98eb5))
+- Deps: update `marked` to 12.0.0. ([17dc71e](https://github.com/slsfi/digital-edition-frontend-ng/commit/17dc71e985203472b58a162ec843e9023b42c778), [dd6548b](https://github.com/slsfi/digital-edition-frontend-ng/commit/dd6548be1fb66f1ace074a1d292bd7f1f1ec7927))
+- Deps: update `zone.js` to 0.14.4. ([47d90dd](https://github.com/slsfi/digital-edition-frontend-ng/commit/47d90dddba786fbf00d65deac77ec008862fe072))
+- Deps: update `jasmine-core` to 5.1.2. ([3e2402b](https://github.com/slsfi/digital-edition-frontend-ng/commit/3e2402bd5cbbdbc7ec0914c96d3b85cc287ea06d))
+- Deps: update `ng-extract-i18n-merge` to 2.10.0. ([0387016](https://github.com/slsfi/digital-edition-frontend-ng/commit/03870166b32684955a908d9d771beefdafa6af43))
+- Deps: update `@types/node` to 20.11.19. ([75f2527](https://github.com/slsfi/digital-edition-frontend-ng/commit/75f252755cb0a7028145e9919a80366eec8df7b0), [90bc7f3](https://github.com/slsfi/digital-edition-frontend-ng/commit/90bc7f39c5725f1efe14ee9c5c428aba6f1f04aa), [67e4e80](https://github.com/slsfi/digital-edition-frontend-ng/commit/67e4e801fa6a6997a10e355c511a6f15a6104027))
+
+### Fixed
+
+- Set correct app mode (desktop or mobile) on the server. Prior to this fix the server app would always return the app rendered in desktop mode, regardless of the actual client device. Previously Ionic’s Platform service was used to determine the current device in the browser, but since it’s not SSR-compatible, the user agent string is now used instead. On the server, the user agent is read from the request headers, and in the browser from the `Window.navigator` object. The app mode is now correctly set for most devices and browsers. One notable exception is Safari on iPads with iOS 13+, which are recognized as desktop devices. Using only the user agent string, it is not possible to distinguish Safari on iPads with iOS 13+ from Safari on MacBooks with MacOS. This fix makes the app compatible with Angular hydration, and nullifies the unreleased changes in [a2f3ea2](https://github.com/slsfi/digital-edition-frontend-ng/commit/a2f3ea276497d410d744a3a88486d0fa57188f66). ([7a9efed](https://github.com/slsfi/digital-edition-frontend-ng/commit/7a9efed0680a2718d91055da9b9efe4be438fa99))
+
+### Removed
+
+- Deps: `xliff`. ([7475e83](https://github.com/slsfi/digital-edition-frontend-ng/commit/7475e832b944e6059a4f7b062ca3fe6af98dcd73))
+
+
+
 ## [1.2.3] – 2024-01-26
 
 ### Fixed
 
-- Broken server-side rendering for non-default locales. Before this commit pages in non-default locales that used the `UrlService` were not rendered on the server. This was a side effect of the `@jsonurl/jsonurl` library used by the service to convert primitive data types and complex data structures like arrays, arrays of objects and objects with nested arrays and objects into URL-safe strings and vice versa. This fix removes the dependency on the external library and replaces its functionality with a custom conversion implementation. The custom implementation is not a full implementation of the JSON→URL specification, but produces the same results for the parts that are relevant for this project. The code has been generated by ChatGPT-4 according to the JSON→URL specification, meticulously guided by a human mind. ([e4ff558](https://github.com/slsfi/digital-edition-frontend-ng/commit/e4ff5581b82efa2438a5eb3a03ce787bbfa0473b))
+- Broken server-side rendering for non-default locales. Before this commit pages in non-default locales that used the `UrlService` were not rendered on the server. This was a side effect of the [`@jsonurl/jsonurl`](https://github.com/jsonurl/jsonurl-js) library used by the service to convert primitive data types and complex data structures like arrays, arrays of objects and objects with nested arrays and objects into URL-safe strings and vice versa. This fix removes the dependency on the external library and replaces its functionality with a custom conversion implementation. The custom implementation is not a full implementation of the [JSON→URL specification](https://github.com/jsonurl/specification/), but produces the same results for the parts that are relevant for this project. The code has been generated by ChatGPT-4 according to the JSON→URL specification, meticulously guided by a human mind. ([e4ff558](https://github.com/slsfi/digital-edition-frontend-ng/commit/e4ff5581b82efa2438a5eb3a03ce787bbfa0473b))
 
 
 
@@ -253,7 +290,8 @@ siteLogoDimensions: {
 
 
 
-[unreleased]: https://github.com/slsfi/digital-edition-frontend-ng/compare/1.2.3...HEAD
+[unreleased]: https://github.com/slsfi/digital-edition-frontend-ng/compare/1.3.0...HEAD
+[1.3.0]: https://github.com/slsfi/digital-edition-frontend-ng/compare/1.2.3...1.3.0
 [1.2.3]: https://github.com/slsfi/digital-edition-frontend-ng/compare/1.2.2...1.2.3
 [1.2.2]: https://github.com/slsfi/digital-edition-frontend-ng/compare/1.2.1...1.2.2
 [1.2.1]: https://github.com/slsfi/digital-edition-frontend-ng/compare/1.2.0...1.2.1

Dockerfile

@@ -38,6 +38,8 @@ RUN npm install -g @angular/cli@${ANGULAR_MAJOR_VERSION}
 RUN npm install
 # Run script that generates sitemap.txt.
 RUN npm run generate-sitemap
+# Run script that generates static html files for collection menus.
+RUN npm run generate-static-collection-menus
 # Build the Angular SSR app.
 RUN npm run build:ssr
 # Create precompressed versions of static files (dist/app/browser/).

README.md

@@ -5,9 +5,9 @@ This branch contains the production frontend app of the digital edition Zacharia
 The app is built on [Angular][angular] and uses [Ionic][ionic] web components.
 
 <p>
-  <a href="https://github.com/angular/angular"><img alt="Angular version badge" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslsfi%2Fdigital-edition-frontend-ng%2Fmain%2Fpackage-lock.json&query=%24%5B'dependencies'%5D%5B'%40angular%2Fcore'%5D%5B'version'%5D&prefix=v&logo=angular&logoColor=%23fff&label=Angular&color=%23dd0031"></a>
+  <a href="https://github.com/angular/angular"><img alt="Angular version badge" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslsfi%2Fdigital-edition-frontend-ng%2Fmain%2Fpackage-lock.json&query=%24%5B'packages'%5D%5B'node_modules%2F%40angular%2Fcore'%5D%5B'version'%5D&prefix=v&logo=angular&logoColor=%23fff&label=Angular&color=%23dd0031"></a>
   &nbsp;
-  <a href="https://github.com/ionic-team/ionic-framework"><img alt="Ionic version badge" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslsfi%2Fdigital-edition-frontend-ng%2Fmain%2Fpackage-lock.json&query=%24%5B'dependencies'%5D%5B'%40ionic%2Fcore'%5D%5B'version'%5D&prefix=v&logo=ionic&logoColor=%23fff&label=Ionic&color=%23176bff"></a>
+  <a href="https://github.com/ionic-team/ionic-framework"><img alt="Ionic version badge" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslsfi%2Fdigital-edition-frontend-ng%2Fmain%2Fpackage-lock.json&query=%24%5B'packages'%5D%5B'node_modules%2F%40ionic%2Fcore'%5D%5B'version'%5D&prefix=v&logo=ionic&logoColor=%23fff&label=Ionic&color=%23176bff"></a>
 </p>
 
 <hr>

angular.json

@@ -41,6 +41,7 @@
               "src/assets/icon/favicon.ico",
               "src/robots.txt",
               "src/sitemap.txt",
+              "src/static-html/",
               "src/assets",
               {
                 "glob": "**/*",

docs/DEVELOPMENT.md

@@ -3,30 +3,111 @@
 This document contains notes and tips on the development of the app.
 
 
-## Angular
+## Dependencies
+
+The app is built on Angular and uses many web components from Ionic. It also has a few other essential dependencies, which are briefly described below.
+
+### `@angular`
 
 The Angular documentation is available on https://angular.dev/.
 
-### Updating Angular
+#### Updating Angular
+
+Run `ng update @angular/cli @angular/core`.
 
-See https://angular.dev/cli/update.
+For more detailed instructions see https://angular.dev/cli/update.
 
 When updating to a new major version of Angular:
 
 1. See the interactive [Angular update guide][angular_update_guide].
 2. Update the line in [`Dockerfile`][dockerfile] which indicates the Angular major version number: `ARG ANGULAR_MAJOR_VERSION=<major_version>`.
 
 
-
-## Ionic
+### `@ionic`
 
 The Ionic Framework documentation is available on https://ionicframework.com/docs/
 
-### Updating Ionic
+#### Updating Ionic
 
 Run `npm install @ionic/angular @ionic/angular-server`.
 
 
+### [`epubjs`][npm_epubjs]
+
+Library for rendering ePub documents in the browser, used by the `epub-viewer` component in the app. It is poorly documented and not actively maintained anymore. It works without problems only in Firefox.
+
+
+### [`express`][npm_express]
+
+Framework for running a web server in Node.js. This library is required by Angular to enable server-side rendering.
+
+
+### [`htmlparser2`][npm_htmlparser2]
+
+SSR-compatible HTML/XML parser, used in a few places in the app to parse HTML from the backend.
+
+
+### [`ionicons`][npm_ionicons]
+
+Iconset especially intended to be used with Ionic.
+
+
+### [`marked`][npm_marked]
+
+SSR-compatible markdown parser. Parses markdown to HTML. Any HTML in the markdown is passed through as it is.
+
+
+### [`rxjs`][npm_rxjs]
+
+Reactive extensions library. Used internally by Angular and heavily in the app for handling Observables.
+
+
+### [`tslib`][npm_tslib]
+
+Runtime library for TypeScript containing all of the TypeScript helper functions. Required by Angular.
+
+
+### [`zone.js`][npm_zone.js]
+
+Library for execution contexts (”zones”) that persist across async tasks. Required by Angular.
+
+
+### [`browser-sync`][npm_browser-sync] (devDependency)
+
+Required by the Angular builders.
+
+
+### [`copyfiles`][npm_copyfiles] (devDependency)
+
+Library for copying files. Used by the `build:ssr` script in `package.json` to copy the `proxy-server.js` file into the `dist/app` folder once the Angular app has been built.
+
+
+### [`gzipper`][npm_gzipper] (devDependency)
+
+Library for compressing files. Used in `Dockerfile` in a post-build step to create compressed (gzip) versions of static files. It’s configured in the `compress` script in `package.json`.
+
+
+### [`ng-extract-i18n-merge`][npm_ng-extract-i18n-merge] (devDependency)
+
+Library for extracting and merging i18n xliff translation files for Angular projects. This library extends the default Angular CLI, and is used to sort the keys in the xliff translation files. Used when running the `extract-i18n` script in `package.json` to create the xliff translation files for the app.
+
+
+### `jasmine` and `karma`
+
+Testing frameworks.
+
 
 [angular_update_guide]: https://update.angular.io/
 [dockerfile]: ../Dockerfile
+[npm_epubjs]: https://www.npmjs.com/package/epubjs
+[npm_express]: https://www.npmjs.com/package/express
+[npm_htmlparser2]: https://www.npmjs.com/package/htmlparser2
+[npm_ionicons]: https://www.npmjs.com/package/ionicons
+[npm_marked]: https://www.npmjs.com/package/marked
+[npm_rxjs]: https://www.npmjs.com/package/rxjs
+[npm_tslib]: https://www.npmjs.com/package/tslib
+[npm_zone.js]: https://www.npmjs.com/package/zone.js
+[npm_browser-sync]: https://www.npmjs.com/package/browser-sync
+[npm_copyfiles]: https://www.npmjs.com/package/copyfiles
+[npm_gzipper]: https://www.npmjs.com/package/gzipper
+[npm_ng-extract-i18n-merge]: https://www.npmjs.com/package/ng-extract-i18n-merge