Práca so schematikmi

1 Úvod
2 Ako pridať NAE-lib do nového Angular projektu
3 Štruktúra nae.json súboru
- 3.1 views
  - 3.1.1 component
  - 3.1.2 layout
  - 3.1.3 case view
  - 3.1.4 task view
  - 3.1.5 tab view
  - 3.1.6 empty view
  - 3.1.7 login
  - 3.1.8 treeCaseView
  - 3.1.9 sidenavView
  - 3.1.10 toolbarView
  - 3.1.11 sidenavAndToolbarView
  - 3.1.12 dashboard
- 3.2 providers
4 services

Úvod

Pri používaní NAE-lib môžme používať Angular Schematics, ktoré nám dokážu generovať view, ktoré si navrhneme. Tento návrh môže prebiehať v nae.json, čo je vlastne konfiguračný súbor pre našu aplikáciu, alebo pri spustení schematiku sa nás na potrebné info schematik opýta, a pridá tieto informácie do nae.json sám. Na prácu s NAE-lib máme dve možnosti - buď si ju nainštalujeme, alebo si forkneme celý projekt.

(Ak niekto ešte nemá nainštalovaný Angular)

pre verzie do 5.0.0

npm install -g @angular/cli@9.1.2

pre verzie od 5.0.0

npm install -g @angular/cli@10.2.3

Ako pridať NAE-lib do nového Angular projektu

1. Vytvoriť si nový Angular projekt cez ng new

ng new <nazov_projektu>

2. Počas vytvárania nového projektu sa príkazový riadok spýta pár otázok:

Would you like to add Angular routing? No

Which stylesheet format would you like to use? SCSS

Po týchto dvoch otázkach sa vytvorí nový projekt.

3. Po vytvorení projektu ho otvoríme vo WebStorme, otvoríme v ľavom hornom rohu File → Settings a zapneme a nastavíme linter podľa nasledujúcich screenshotov. Tak isto aby nám pri auto-importoch vkladalo single quotes a nie double quotes (liter-u totiž double quotes vadia a pri každom importe by nám ukazoval chyby).

4. Do projektu pridáme súbor .npmrc, ktorý slúži ako konfiguračný súbor pre NPM, aby sme vedeli nainštalovať NAE-lib s našeho nexus repository.

5. Následne pridáme NAE-lib a NC-lib do nášho projektu pomocou príkazu

ng add @netgrif/application-engine

po úspešnom pridaní NAE knižnice pridáme NC knižnicu príkazom:

ng add @netgrif/components

6. Počas inštalácie sa nás Angular CLI opýta, či chceme odosielať Google anonymné informácie, my klikneme No.

7. Po nainštalovaní sa nám upraví projekt add schematikom, ktorý sme vyvolali inštaláciou NAE-lib. Vytvorí sa aj súbor nae.json, ktorý slúži ako konfiguračný súbor projektu, vďaka ktorému môžme vytvárať nové zobrazenia pomocou schematikov, alebo napríklad meniť paletu farieb projektu.

8. a) pre verzie do 5.0.0

Do projektu následne treba nainštalovať takzvané peerDependencies, ktoré NAE-lib potrebuje pre svoje fungovanie. (vzhľadom na updatovanie projektu si treba najnovšie versie pozriet najlepšie v DEV branchi nae-frontend repozitara)

npm install @angular/material@8.2.3 @angular/cdk@8.2.3 @angular/flex-layout@9.0.0-beta.29 @angular/material-moment-adapter@9.2.0 @covalent/core@3.0.0 @covalent/highlight@3.0.0 @covalent/markdown@3.0.0 @covalent/text-editor@3.0.1 @ngx-translate/core@12.1.2 @ngx-translate/http-loader@4.0.0 angular-resize-event@1.2.1 @angular-material-components/datetime-picker@2.0.4 @angular-material-components/moment-adapter@2.0.1 moment@2.24.0 natural-orderby@2.0.3 hammerjs@2.0.8

b) pre verzie od 5.0.0

Skopírujte nasledovné dependencie a devDependencie do package.json, nastavte požadovanú verziu NAE a NC knižnice a následne zadajte do konzoly príkaz npm install

"dependencies": {
    "@angular/animations": "~10.2.3",
    "@angular/cdk": "~10.2.7",
    "@angular/common": "~10.2.3",
    "@angular/compiler": "~10.2.3",
    "@angular/core": "~10.2.3",
    "@angular/forms": "~10.2.3",
    "@angular/platform-browser": "~10.2.3",
    "@angular/platform-browser-dynamic": "~10.2.3",
    "@angular/router": "~10.2.3",
    "@netgrif/application-engine": "X.X.X",
    "@netgrif/components": "X.X.X",
    "rxjs": "~6.5.3",
    "tslib": "^1.11.1",
    "zone.js": "~0.10.2",
    "@angular/material": "~10.2.7",
    "@angular/material-moment-adapter": "~10.2.7",
    "angular-resize-event": "~2.0.1",
    "@angular-material-components/datetime-picker": "~4.0.5",
    "@angular-material-components/moment-adapter": "~4.0.1",
    "@ngx-translate/core": "~13.0.0",
    "@ngx-translate/http-loader": "~6.0.0",
    "moment": "~2.24.0",
    "natural-orderby": "~2.0.3",
    "hammerjs": "~2.0.8",
    "angular-resizable-element": "~3.3.0",
    "@covalent/core": "~3.1.0",
    "@covalent/highlight": "~3.1.0",
    "@covalent/markdown": "~3.1.0",
    "@covalent/text-editor": "~3.1.0",
    "@angular/flex-layout": "~10.0.0-beta.32",
    "@types/mousetrap": "1.6.3",
    "ngx-quill": "~12.0.1",
    "@swimlane/ngx-charts": "~16.0.0",
    "quill": "~1.3.7"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "~0.1002.0",
    "@angular/cli": "~10.2.0",
    "@angular/compiler-cli": "~10.2.3",
    "@angular/language-service": "~10.2.3",
    "@types/node": "~12.12.29",
    "@types/jasmine": "~3.5.9",
    "@types/jasminewd2": "~2.0.3",
    "codelyzer": "~5.2.1",
    "jasmine-core": "~3.5.0",
    "jasmine-spec-reporter": "~4.2.1",
    "karma": "~4.3.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage-istanbul-reporter": "~2.1.0",
    "karma-jasmine": "~2.0.1",
    "karma-jasmine-html-reporter": "^1.5.2",
    "protractor": "~5.4.2",
    "ts-node": "~8.3.0",
    "tslint": "~5.18.0",
    "typescript": "~4.0.2"
  }

9. Odporúčame vypnúť Ivy kompilátor, to docielime pridaním nasledujúceho príkazu do tsconfig.json

{
  ...
  "angularCompilerOptions": {
    "enableIvy": false,
    ...
  }
}

Štruktúra nae.json súboru

nae.json súbor obsahuje konfiguráciu aplikácie a s pomocou schematikov je z tejto konfigurácie možné generovať rôzne súčasti aplikácie ako napríklad routing, alebo views. Obsah nae.json súboru je prístupný aj počast run time-u aplikácie cez ConfigurationService.

Jednotlivé views generujeme pomocou príkazu:

ng g @netgrif/components:create-view

Views sa generujú postupne po jednom, to znamená že príkaz vygeneruje prvý view, ktorý nájde.

views

V časti views sa definguje štruktúra navigácie v aplikácii a jednotlivé views v nej. Ukážku všeobecnej štruktúry tohoto súboru možete vidieť nižšie.

{
  "views": {
    "id_view": {
      "access": "private"
      "navigation": {
        "title": "nav title"
      },
      "routing": {
        "path": "example"
      }
      "children": {}
    }
  }
}

id_view určuje aké ID má dané view, pričom sa odvádza od IDčok rodičovských views (spája sa '/')
access rozhoduje o tom, či sa do daného view dá dostať aj bez prihlásenia (“public“), alebo len s prihlásením (“private“)
navigation rozhoduje o tom, či sa má view zobrazovať v navigačnom komponente z libky. Atribút “title” hovorí o tom, aký text sa má v nav zobrazovať, a ”icon” určuje zobrazovanú ikonu
routing rozhoduje o tom na akej adrese sa bude view zobrazovať, vždy relatívne ku rodičovskému view
children obsahuje detské views. Na to aby mohlo mať view detské views potrebuje vo svojom HTML-ku obsahovať <router-outlet> komponent

To o aké view ide sa určuje layout, resp. component atribútom.

Bez ohľadu na to, ktorý z atibútov sa používa je po pridaní nového view do nae.json súboru potrebné spustiť create-view schematik.

component

{
  "views": {
    "demo-login": {
        "component": {
            "class": "LoginFormComponent",
            "from": "./doc/forms/login-form/login-form.component"
        },
        "access": "public",
        "navigation": false,
        "routing": {
            "path": "login"
        }
    }
  }
}

Pomocou atribútu component je možné pridávať do štruktúry views akýkoľvek vlastný komponent.

class obsahuje názov triedy valastného komponentu
from obsahuje import cestu pre túto triedu. Cesta musí byť relatívne ku koreňovému priečinku projektu (priečinok obsahujúci app.component.ts)

layout

{
  "views": {
    "dashboard": {
      "layout": {
          "name": "dashboard",
          "params": {
              "columns": 4,
              "cards": [
                  {
                      "type": "count",
                      "title": "All tasks",
                      "resourceType": "Task",
                      "filter": {},
                      "layout": {
                          "x": 0,
                          "y": 0,
                          "rows": 1,
                          "cols": 1
                      }
                  }
              ]
          },
          "componentName": "MyDashboard"
      },
      "access": "private",
      "navigation": {
          "title": "Dashboard",
          "icon": "dashboard"
      },
      "routing": {
          "path": "comp-dashboard"
      }
    }
  }
}

pomocou layout atribútu je možné používať jednotlivé views, ktoré definuje naša frontend knižnica.

name určuje o ktoré z našich view ide (jednotlivo ich opíšeme ďalej)
params obsahuje konfiguráciu daného view. Štruktúra tohoto atribútu závisí od hodnoty layout-u
componentName je nepovinný atribút, ktorým je možné určiť vlastný názov triedy vygenerovaného komponentu. Pokiaľ sa tento argument nezadá je názov automaticky generovaný z IDčka view. V takomto prípade nepoužívajte v IDčkach pomlčky, lebo sa potom nesprávne generujú názvy tried.

case view

{
  "views": {
    "case": {
      "layout": {
          "name": "caseView",
          "params": {
              "allowedNets": [
                  "leukemia"
              ]
          },
          "componentName": "MyCaseView"
      },
      "access": "private",
      "routing": {
          "path": "comp-case"
      }
    }
  }
}

Pod pojdom case view sa v novom frontende myslý také view, kde sa zobrazujú cases, obsahuje konfiguráciu headerov, vyhľadávanie a tlačidlo na vytvorenie nového prípadu (tak ako na starom frontende). Na rozdiel od starého frontendu však case view neobsahuje žiadne karty ani pripojené task view.

Params obsahujú jeden atribút allowedNets ktorý obsahuje identifikátory procesov, ktoré sa môžu v tomto view zobrazovať. Zároveň to určuje siete, ktoré je možné vytvárať tlačidlom + v case view.

task view

{
  "views": {
    "task": {
      "layout": {
          "name": "taskView",
          "componentName": "MyTaskView",
          "params": {
              "allowedNets": [
                  "leukemia"
              ]
          }
      },
      "access": "private",
      "routing": {
          "path": "comp-task"
      }
    }
  }
}

S task view je to podobné ako s case view, taktiež neobsahuje žiadne taby. Inak je to rovnaké ako na starom frontende.

Task view potrebuje mat definované params.

tab view

{
  "views": {
    "tab": {
      "layout": {
          "name": "tabView",
          "componentName": "MyTabs",
          "params": {
              "tabs": [
                  {
                      "view": {
                          "name": "caseView",
                          "params": {
                            "allowedNets": [
                              "leukemia"
                            ]
                          }
                      },
                      "label": {
                        "icon": "home",
                        "text": "Leukémia"
                      },
                      "canBeClosed": false,
                      "order": -1
                  }
              ],
              "defaultTaskView": {
                "view": {
                  "name": "taskView"
                }
              }
          }
      },
      "access": "private",
      "routing": {
          "path": "comp-tab"
      }
    }
  }
}

Tab view je nový typ view, ktorý obsahuje čisto logiku tabov.

tabs obsahuje pole objektov, ktoré reprezentujú taby. Tieto taby budú defaultne otvorené, keď sa view načíta používateľovi. Každý tab objekt má vlastné atribúty, ktoré bližšie určujú o jeho vlastnosti.
view funguje rovnako ako v klasických views a určuje, aké view sa má v danom tabe zobraziť. Pri genrovaný tab view sa vygenerujú súčasne aj všetky view, ktoré sú v ňom referencované. Opäť je možné použiť miesto atribútu view atribút component, ktorým je možné vložiť vlastný komponent do tabu.
label definuje štítok tabu. Ikonu a názov je možné uviesť samostatne, alebo obe súčasne.
canBeClosed hovorí o tom, či je tab možné zavrieť. Pokiaľ je tab možné zatvárať v jeho štítku sa zobrazuje talčidlo X.
order určuje poradie tabov. Taby sa neozbrazujú v tom poradí v akom sú definované, ale v poradí určenom ich orderom. Najviac naľavo je tab s najnižsím orderom a najviac napravo tab s najvišším orderom. Pokiaľ majú dva taby rovnaký order, tak viac vľavo je ten, ktorý je v nae.jsone definovaný skôr resp. ten, ktorý bol vytvorený v aplikácii skôr. Nové taby sa defaulte otvárajú s order 0.

Case views a task views vygenerované v tab view majú trochu iné správanie, ako keď sú definované samostatne. Case view pri vytváraní nového case-u otovrí novú kartu (ale neprepne sa do nej), task view si z dát poslaných do jeho karty skúsi vytiahnuť case, pre ktorý má zobrazovať tasky.

Atribút defaultTaskView hovorí o tom, aký komponent sa má otvárať v novom tabe cez case view, keď sa vytvorí nový case. Štruktúra tohoto atribútu je rovnaká, ako štruktúra tabov. V našom prípade teda ide o task view, čím teda vytovríme klasickú kombináciu zo starého frontendu.

empty view

{
  "views": {
    "empty": {
      "layout": {
          "name": "emptyView"
      },
      "access": "private",
      "routing": {
          "path": "comp-empty"
      }
    }
  }
}

Toto view obsahuje úplne prázdny komponent, ktorého HTML pozostáva iba z <router-outlet> komponentu.

login

{
  "views": {
    "empty": {
      "layout": {
          "name": "login"
      },
      "access": "public",
      "navigation": {},
      "routing": {
          "path": "comp-login"
      }
    }
  }
}

View obsahujúce komponent na prihlásenie do aplikácie.

Pokiaľ sa používa toto view, tak Authentication Guard automaticky detekuje jeho existenciu v nae.json súbore a presmeruje naň používateľa, keď nie je prihlásený.

Treba si dať pozor aby access atribút tohoto view mal hodnotu public, inak sa naň neprihlásený používateľ nebude vedieť dostať.

treeCaseView

{
  "views": {
    "tree-view": {
        "layout": {
            "name": "treeCaseView",
            "params": {
                "filterId": "rootNodeFilterID"
            }
        },
        "access": "private",
        "navigation": false,
        "routing": {
            "path": "comp-tree-view"
        }
    }
  }
}

Ide o nové view, ktoré umožňuje zobrazovanie stromových štruktúr uložených v case ref fieldoch.

Parameter filterId určuje identifikátor filtra, z ktorého sa natiahne koreňový uzol zobrazovaného stromu.

Pre viac informácii ohľadom tohoto view pozrite Tree Case View page.

sidenavView

{
  "views": {
    "side-nav": {
        "layout": {
            "name": "sidenavView",
            "params": {
                "user": true,
                "quickPanel": true,
                "navigation": true
            }
        },
        "access": "private",
        "navigation": false,
        "routing": {
            "path": ""
        }
    }
  }
}

Komponent, ktorý pozostáva z bočného menu a <router-outlet> komponentu.

user určuje, či sa v bočnom menu má zobrazovať informácia o aktuálne prihlásenom používateľovi
quickPanel určuje, či sa v bočnom menu majú zobrazovať ovládacie prvky s voľbou jazyka, nastavenia, odhlásenia ďalšími konfiguráciami (paper view)
navigation určuje, či sa v bočnom menu má zobrazovať navigačný strom

toolbarView

{
  "views": {
    "toolbar": {
        "layout": {
            "name": "toolbarView"
        },
        "access": "private",
        "navigation": false,
        "routing": {
            "path": ""
        }
    }
  }
}

Komponent, ktorý pozostáva z hornej lišty v ktorej je zobrazené logo, nejaký nadpis/názov a prihlásený používateľ.

Pri použití tohoto komponentu si treba dať pozor, pretože neobsahuje <router-outlet>.

sidenavAndToolbarView

{
  "views": {
    "side-nav": {
        "layout": {
            "name": "sidenavAndToolbarView",
            "params": {
                "user": true,
                "quickPanel": true,
                "navigation": true
            }
        },
        "access": "private",
        "navigation": false,
        "routing": {
            "path": ""
        }
    }
  }
}

Komponent kombinujúci predchádzajúce dva. Obsahuje bočné menu, hornú lištu aj <router-outlet>.

Parametre má rovnaké, ako sidenavView.

dashboard

providers

Providery zabezpezpečujú nastavenie správnych odkazov na endpointy backendu aplikácie. Pre správny chod všetkých funkcionalít NAE a NC treba mať providery nastavené približne takto:

"providers": {
        "auth": {
            "address": "http://localhost:8080/api/",
            "authentication": "Basic",
            "endpoints": {
                "login": "auth/login",
                "logout": "auth/logout",
                "signup": "auth/signup",
                "verification": "auth/verify",
                "verify": "auth/token/verify",
                "invite": "auth/invite",
                "reset": "auth/reset",
                "recover": "/auth/recover"
            },
            "sessionBearer": "X-Auth-Token",
            "jwtBearer": "X-Jwt-Token"
        },
        "resources": [
            {
                "name": "case",
                "address": "http://localhost:8080/api/",
                "format": "hal",
                "openApi": "https://swagger.io"
            },
            {
                "name": "task",
                "address": "http://localhost:8080/api/",
                "format": "json"
            },
            {
                "name": "petrinet",
                "address": "http://localhost:8080/api/",
                "format": "json"
            },
            {
                "name": "user",
                "address": "http://localhost:8080/api/",
                "format": "json"
            },
            {
                "name": "dashboard",
                "address": "http://localhost:8080/api/",
                "format": "json"
            }
        ]
    },

V prvej časti sa nastavuje provider pre auth, ktorý zabezpečuje prihlasovanie, odhlasovanie, registráciu, verifikáciu tokenu v rámci aplikácie ale aj pri registrácii, pozývanie nových userov ako aj reset hesla a recover účtu.

V poli resources sa nachádzajú linky na endpointy určené pre Case-y, Tasky, Userov, Dashboardy ale a pre prácu so sieťami.

Od verzie 5.6.0 sa upravuje resolveovanie endpointov. Pokial URL endpointu zacina http protokolom (http alebo https) tak sa pouzije uvedena hodnota. Pokial nie, tak sa URL povazuje za relativnu k lokacii frontendu a vysledna URL sa vyskldava ako:

URL na ktorej bezi frontend + /api + hodnota z nae.json suboru

services

jeden z dôležitých prvkov NAE.jsonu, ktorý je potrebný pre niektoré nastavenia aplikácie. táto sekcia vyzerá nasledovne:

"services": {
        "log": {
            "level": "ALL",
            "logWithDate": true,
            "serializeExtraParams": true,
            "includeLogLevel": true,
            "publishers": [
                "console",
                "localStorage"
            ]
        },
        "auth": {
            "loginRedirect": "login",
            "logoutRedirect": "login"
        },
        "routing": {
            "defaultRedirect": "authentication",
            "wildcardRedirect": "authentication"
        },
        "dataFields": {
            "template": "material",
            "appearance": "outline"
        },
        "legal": {
            "termsOfService": "https://netgrif.com/",
            "privacyPolicy": "https://netgrif.com/"
        }
    }

prvá časť LOG riesi nastavenie logovania aplikácie. Prvý parameter hovorí o úrovni logovania, to môže byť nasledovné:

export enum LogLevel {
    ALL = 0,
    DEBUG = 1,
    INFO = 2,
    WARN = 3,
    ERROR = 4,
    OFF = 6
}

Dalej sú tam nastavenia logovania z dátumom, serializáciu parametrov, a tak isto či chceme do výpisu vkladať aj level logovania. V neposlednom rade môžme nastaviť kam všade sa má daný log propagovať.

Dalšie časti ako AUTH a ROUTING sa používajú pri dynamickom routingu. Pomocou auth položiek vieme nastavit kam nás ma routovat ked potrebujeme ist na login , alebo ked sa odhlásime. pomocou routing položiek vieme nastavit defaultny redirect a tak isto aj wildcard redirect, aby sem vedeli pokryť aj nežiadúce stavy routera.

V sekcií dataFields vieme nastavit základné nastavenie zobrazovania dátových polí v aplikácií. Dané nastavenie sa využíva vo všetkých poliach, ktoré nemajú definované vlastné správanie cez layout.

Netgrif Application Engine