@ibm-wch-sdk/ng-format

Support package for @ibm-wch-sdk/ng to add ICU support for message translation.

Stats

StarsIssuesVersionUpdatedCreatedSize
@ibm-wch-sdk/ng-format
6.0.5242 years ago3 years agoMinified + gzip package size for @ibm-wch-sdk/ng-format in KB

Readme

ibm-wch-sdk-ng-format

NPM version

Implementation of the MsgFormatService for WCH based Angular applications that allows components to display text messages with replacements according to ICU. The service accepts a string that contains ICU replacement tokens and a context. It produces an Observable with the replaced text against the context. If the replacement tokens are themselves Observables, then the replaced text will be updated automatically.

Usage

Install the module via

npm install --save ibm-wch-sdk-ng-format

Add the module to your root application

@NgModule({
  ...
  imports: [
    ...
    WchNgMsgFormatModule.forRoot()
  ],
  ...
})
export class AppModule { }

Prereqs

MsgFormatService

The service offers the API:

  • formatMessage(value: string, ctx: any) => Observable<string>: that interprets the value as the ICU format string and replaces it against the given context.
    • value: the ICU format string
    • context: context object to resolve the variables in the template. The resolution will first convert each parameter to camel case. It then looks for an onXXX instance of type Observable on the context. If this does not exist, it looks for the camel case property XXX directly and falls back to the same sequence for the non-camel case version.

The locale of the translation is derived by the following process: first the service looks for an onLocale property of type Observable. If that does not exist, it falls back to onRenderingContext and extracts the locale property of the rendering context.

The fallback mechanism has been chosen such that it seamlessly works with layout components created by the ibm-wch-sdk-ng.

Example

Consider a content item with a text field myText and a number field myCount. In the text field you'd like to enter text that depends on the actual number in the number field such as Showing no items. or Showing 5 items. This can be realized as follows:

Text

The text in myText would look like Showing {myCount, plural, =0{no items}, =1{one item}, other{# items}}..

Components

The component defines accessors for the elements:

export class MyComponent {

  @RenderingContextBinding('elements.myText.value')
  onMyText: Observable<string>;

  @RenderingContextBinding('elements.myCount.value')
  onMyCount: Observable<number>;
}

In the constructor define a derived property representing the replaced text:

export class MyComponent extends AbstractRenderingComponent {

  @RenderingContextBinding('elements.myText.value')
  onMyText: Observable<string>;

  @RenderingContextBinding('elements.myCount.value')
  onMyCount: Observable<number>;

  onReplacedText: Observable<string>;

  constructor(aService: MsgFormatService) {
    super();

    this.onReplacedText = this.onMyText.switchMap(txt => aService.formatMessage(txt, this));
  }
}

In the HTML template use the replaced text attribute:

<div>{{ onReplacedText | async }}</div>

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.