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/*)
  • Optimus UI (moduli @openng/optimus-ui/*)
  • 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~~ | Optimus UI | Ngx-translate | Ngx-formly | Node | |---------|----------------|-------------|------------|---------------|------------|--------------------------------------| | 8.x.x | 22.x.x | / | 2.x.x | 18.x.x | 6.3.x | ^22.22.3 || ^24.15.0 || ^26.0.0 | | 7.x.x | 21.x.x | 21.x.x | / | 17.x.x | 6.3.x | ^20.19.0 || ^22.12.0 || ^24.0.0 | | 6.x.x | 19.x.x | 20.x.x | / | 16.x.x | 6.3.x | ^18.19.1 || ^20.11.1 || ^22.0.0 | | 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):

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

• Definicijo jezikov podamo preko konfiguracije provideCommons():

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:

{
    "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 Optimus UI stile (za posamezne komponente) in PrimeFlex kot pomožno CSS knjižnico. Dodatno se lahko na končnem projektu uporabljajo ikone OpenNG. Glede ne preference se opcijsko dodajo naslednji importi (pred importom MNG commons teme!):

@import '~../node_modules/primeflex/primeflex.scss';
@import '~../node_modules/@openng/icons/openng-icons.css';

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

pnpm i primeflex
pnpm i @openng/icons

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;
}