Medius Commons

Commons knjižnica za izgradnjo uporabniškega vmesnika na ogrodju Angular.

Predhodne zahteve

• Node.js (preveri kompatibilne verzije v skeciji Kompatibilnost) in npm
• pnpm package manager (https://pnpm.io/), ki optimizira delovanje privzetega npm.
• Zahtevane skupne odvisnosti (peer dependencies)
  • Angular (moduli @angular/*)
  • PrimeNG (moduli primeng/*)
  • Ngx Formly (modul @ngx-formly/core)
  • Ngx Translate (modul @ngx-translate/core)

Za verzije odvisnosti glej poglavlje kompatibilnosti.

Namestitev

pnpm i @mediusinc/mng-commons

Kompatibilnost

V tabeli so navedene kompatibilne verzije za commons knjižnico in povezane odvisnosti.

| Commons | Angular | PrimeNG | Ngx-translate | Ngx-formly | Node | |---------|----------------|---------|---------------|------------|--------------------------------------| | 5.1.x | 17.3.x, 18.x.x | 17.18.x | 14.x.x | 6.x.x | ^18.13.0 || ^20.9.0 | | 5.x.x | 17.x.x | 17.x.x | 14.x.x | 6.x.x | ^18.13.0 || ^20.9.0 | | 4.x.x | 17.x.x | 17.x.x | 14.x.x | 6.x.x | ^18.13.0 || ^20.9.0 | | 3.x.x | 16.x.x | 16.x.x | 14.x.x | 6.x.x | ^16.14.0 || ^18.10.0 | | 2.x.x | 15.x.x | 15.x.x | 14.x.x | 6.x.x | ^14.20.0 || ^16.13.0 || ^18.10.0 |

Lokalizacija (i18n)

Modul ngx-translate se konfigurira na končnem projektu in je na končnem projektu potrebno določiti način za load prevodov. Primer konfiguracije za multi-module HTTP loader:

• HTTP loader factory:

export function i18nHttpLoaderFactory(http: HttpBackend ) {
  return new MultiTranslateHttpLoader(http, [
    {prefix: './assets/i18n/mng/', suffix: '.json'},
    {prefix: './assets/i18n/', suffix: '.json'}
  ]);
}

• Konfiguracija v main.ts (v primeru uporabe modulov: AppModule):

TranslateModule.forRoot({
    loader: {
        provide: TranslateLoader,
        useFactory: i18nHttpLoaderFactory,
        deps: [HttpBackend]
    }
})

• Definicijo jezikov podamo preko konfiguracije MngCommonsModule:

MngCommonsModule.forRoot({
  app: {
    languages: ['en', 'sl']
  }
})

Knjižnica pakira tudi osnovne prevode, ki so del modula. Za vključitev na zgornji način je potrebno dodati naslednjo konfiguracijo v angular.json med assets nastavitve:

{
  "glob": "**/*",
  "input": "./node_modules/@mediusinc/mng-commons/assets/i18n",
  "output": "/assets/i18n/mng"
}

Tema

Opcijsko se vključi tudi tema MNG Commons, ki ima dve svetlo in temno varianto. Za vključitev se v stile na končnem projektu doda import v style.scss:

# Za svetlo temo:
@import '~../node_modules/@mediusinc/mng-commons/scss/mng-commons-light';

# Za temno temo:
@import '~../node_modules/@mediusinc/mng-commons/scss/mng-commons-dark';

Primarno se uporablja svetla tema!

Pri uporabi temne teme je potrebno dodatno nastaviti tudi colorMode v modulu:

MngCommonsModule.forRoot({
  app: {
    colorScheme: 'dark'
  }
});

Tema za svoje delovanje uporablja primeNG stile (za posamezne komponente) in PrimeFlex kot pomožno CSS knjižnico. Dodatno se lahko na končnem projektu lahko uporabi še ikone PrimeIcons. Glede ne preference se opcijsko dodajo naslednji importi (pred importom MNG commons teme!):

@import '~../node_modules/primeng/resources/primeng.min.css';
@import '~../node_modules/primeflex/primeflex.scss';
@import '~../node_modules/primeicons/primeicons.css';

Pri prvem importu ni potrebno namestiti dodatnih odvisnosti (je že vključeno z primeng), za drugi dve pa je potrebno namestiti:

pnpm i primeflex
pnpm i primeicons

Dodajanje MNG Commons slik v assets na končnem projektu se uredi z konfiguracijo v assets segmentu znotraj angular.json, kjer se doda:

{
  "glob": "**/*",
  "input": "./node_modules/@mediusinc/mng-commons/assets/images",
  "output": "/assets/images/mng"
}

Custom Formly validatorji

Validatorje lahko dodajamo samostojno na polja, ali pa na skupine polj.

Dodajanje se v obeh primerih razlikuje.

• validator na polje lahko dodamo preko polja, kjer mu podamo ime, funkcijo in sporočilo za validacijo.

serviceChannelsTableviewDescriptor.addField('cost.code')
        .withValidator('codeValidator', control => control.value, (err, field) => 'error message');

• validator na skupine lahko dodamo preko

serviceChannelsTableviewDescriptor.createFieldGroup('Service cost', 'ServiceChannelDto.fieldGroups.serviceCost')
        .withValidator('serviceCostAllOrNoneFieldsRequired', this.serviceCostAllOrNoneFieldsRequired);

Ko dodajamo na grupe, moramo registrirati tudi globalno sporočilo za validacijo v formly-translate.extension.ts, kjer mora biti ime sporočila za validacijo enako kot napaka, ki jo nastavljamo v samem validatorju.

export function formlyConfigProvider(translate: TranslateService): ConfigOption {
  return {
    validationMessages: [
      { name: 'required', message: getRequiredValidationMessage(translate)},
      ...
              // naše sporočilo, ki se imenuje serviceCostAllOrNoneFieldsRequired
              { name: 'serviceCostAllOrNoneFieldsRequired', message: serviceCostAllOrNoneFieldsRequiredValidatorMessage(translate)}
    ],
    extras: { lazyRender: true },
    wrappers: formlyWrappersConfig,
    types: formlyTypesConfig
  };
}

export function serviceCostAllOrNoneFieldsRequired(control: AbstractControl): boolean {
  const { code, value, description } = control.value.cost;
  const costControl = control.get('cost');

  // tu vmes je še druga koda

  // nastavimo enako napako, kot je ime sporočila
  costControl.get('code').setErrors({serviceCostAllOrNoneFieldsRequired: true});
  costControl.get('value').setErrors({serviceCostAllOrNoneFieldsRequired: true});
  costControl.get('description').setErrors({serviceCostAllOrNoneFieldsRequired: true});

  return false;
}