npm package: @mediusinc/mng-commons
Description: Commons knjižnica za izgradnjo uporabniškega vmesnika na ogrodju Angular.
Latest version: 7.2.1

# 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

```bash
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:
```ts
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`):

```ts
provideTranslateService({
    loader: {
        provide: TranslateLoader,
        useFactory: i18nHttpLoaderFactory,
        deps: [HttpBackend]
    }
})
```

- Definicijo jezikov podamo preko konfiguracije `provideCommons()`:
```ts
provideCommons({
        app: {
            locales: ['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:
```json
{
  "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`:

```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:
```ts
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!**):

```scss
@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:
```bash
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:

```json
{
  "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.
```typescript
serviceChannelsTableviewDescriptor.addField('cost.code')
        .withValidator('codeValidator', control => control.value, (err, field) => 'error message');
```
- validator na skupine lahko dodamo preko
```typescript
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.
```typescript
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;
}
```