MyHealth - Web Component Integration for Angular

Collection of Angular goodies to help build MyHealth Web Components.

Based on Angular v19

This library is published to the NPM registry at: https://www.npmjs.com/package/@smals-belgium/myhealth-wc-integration-angular

Documentation

All of the below functionalities are provided as opt-in helpers for your project.
You can use them, you do no have to.

bootstrapModule (bootstrap function)

Simplifies bootstrapping of modules with multiple Angular web components that work together.

AngularWebComponent (component class)

A base class for an Angular-based web component that implements the myhealth WebComponent type, but with input/output signals instead of simple properties and events.

• All spec properties are present as input signals.
• All built-in events are present as output signals.
• Provides an easy-to-use interface for the refresh mechanism.
• Intercepts component navigation through a tags and sends corresponding open events to the host.

HostSettings (service class)

Listens to all settings-change events from the host app and exposes them as Observables, one for each setting.

Each Observable will immediately emit the initial value of the setting.

Note that this is just an alternative for watching changes on the web component inputs for host settings. It makes more sense when used in the context of a more complex module with multiple components, as having one centralized state is more convenient than dealing with multiple identical component inputs.
For very simple one-component modules, the component input approach is more advisable.

Component navigation (directive and service class)

A directive that allows component navigation through a tags.

The a tag is present in the DOM, and this directive will give it an appropriate href so that screen readers can do their jobs. But the href is not actually used for navigation, since that's the responsibility of the host application. The default behaviour is prevented and an open event is dispatched instead.

And a simple service that propagates open events from the component-anchor directive to other parts of the module.

REST interceptors

BearerTokenInterceptor

This interceptor will intercept all (by default) HttpRequests and attach an Authorization header to them in the form of an OAuth 2 Bearer Token.

The token is obtained from the host application since that is responsible for obtaining access tokens and exchanging user profiles for mandate profiles.

If you require a different authentication mechanism, do not use this interceptor.

If you just need to add other headers to the requests, you can still do so by adding your own interceptor next to this one.

If you don't want authentication for specific requests, you can exclude them using the filter parameter.

Example
Headers after interception

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Example
No authentication for file downloads of publicly available assets using filter param

provideHttpClient(
 withInterceptors([
   authInterceptor(req => !(req.url.includes('/public/documents') && req.responseType === 'blob'))
 ])
)

CacheInterceptor

This interceptor will intercept all GET requests that return json (by default) and store them in the host application's cacheDataStorage. Any subsequent identical request will return that response from the cache instead of making a call to the backend.

The HttpResponses are stored and retrieved as-is from the cache, which makes the substitution completely transparent down the line, i.e. any caller doesn't have to care where the response came from.

The responses are identified by the url that was used to make the request.

If you don't want to cache specific requests/responses, you can exclude them using the filter parameter. But remember that you'll be overriding the default filter, which allows only GET requests that respond with json data.

Any request that passes the filter will be cached, but if you want to force a backend call, for example when the user does a pull-to-refresh, you can do so by adding the UseCacheToken to the request's context (see examples).

If you need more precise control, like updating an existing cache when other http operations are performed, or being able to decide exactly what gets stored or what the cache key is, have a look at the resourceCacheInterceptor instead.

If you want to combine the cacheInterceptor with a storageInterceptor, put the cache interceptor first in the chain. This way the in-memory cache gets hit before the (slightly slower) storage is attempted.

Example
Skipping the cache with UseCacheToken

inject(HttpClient).get<Item[]>(`${host}/items`, { context: cacheContext(false) });

StorageInterceptor

This interceptor will intercept all GET requests that return json (by default) and store them in the host application's offlineDataStorage. Any subsequent identical request will return that response from the storage instead of making a call to the backend if the current HostSettings allow it.

Since the HttpResponses are class instances, they are serialized before storage and deserialized upon retrieval creating new but identical HttpResponse instances, which makes the substitution completely transparent down the line, i.e. any caller doesn't have to care where the response came from.

The responses are identified by the url that was used to make the request.

When the user disables offline storage, requests and responses just pass through; nothing happens. But when it's enabled it depends on whether the user is "soft" authenticated (he entered his PIN or biometrics to access the stored data). If he's "soft" authenticated, we'll try to read the stored data. But if he's "strong" authenticated (i.e. he's online), we let the call go through and store the results.

If you don't want to store specific requests/responses, you can exclude them using the filter parameter. But remember that you'll be overriding the default filter, which allows only GET requests that respond with json data.

If you need more precise control, like updating an existing store entry when other http operations are performed, or being able to decide exactly what gets stored or what the storage key is, have a look at the resourceStorageInterceptor instead.

If you want to combine the storageInterceptor with a cacheInterceptor, put the cache interceptor first in the chain. This way the in-memory cache gets hit before the (slightly slower) storage is attempted.

ResourceCacheInterceptor

Same a CacheInterceptor, but supporting full CRUD operations, at the cost of more complex configuration.
To be documented.

ResourceStorageInterceptor

Same a ResourceInterceptor, but supporting full CRUD operations, at the cost of more complex configuration.
To be documented.

LoggerInterceptor

Logs requests and responses for debugging purposes.
To be documented.

Error handler

A specific error handler for Angular applications packaged as web components.

Providers

There are separate providers for all of the above, allowing you to register only what you need.
Alternatively, there's the MyHealth provider that provides everything but the interceptors.

• error handler
• host settings
• host services