Skip to content
This repository has been archived by the owner on Sep 18, 2024. It is now read-only.

Latest commit

 

History

History
293 lines (208 loc) · 16.4 KB

README.md

File metadata and controls

293 lines (208 loc) · 16.4 KB
Raw

nav-dekoratoren nav.no logo

Appen er avviklet og erstattet av decorator-next

Denne appen serverte header og footer for nav.no i perioden 13. mai 2020 -> 2. juli 2024.

Bruk av dekoratøren

Dekoratøren serveres på følgende ingresser:

Prod (prod-gcp)

Implementasjon

Dekoratøren består av fire elementer med unike id'er som må settes inn i HTML'en til applikasjonen din:

Beskrivelse id
Header HTML header-withmenu
Footer HTML footer-withmenu
JavaScript og context data scripts
CSS styles

Med NPM-pakke

Ved bruk av Node.js kan @navikt/nav-dekoratoren-moduler benyttes.

Med egen implementasjon

Server-side rendering (anbefalt)

Hent dekoratøren server-side og send HTML til brukeren som inkluderer dekoratøren.

Eksempel:

fetch("{MILJO_URL}/?{DINE_PARAMETERE}").then(res => {
    const document = createDocFromRes(res);

    const styles = document.getElementById("styles")?.innerHTML;
    const scripts = document.getElementById("scripts")?.innerHTML;
    const header = document.getElementById("header-withmenu")?.innerHTML;
    const footer = document.getElementById("footer-withmenu")?.innerHTML;

    /*
    Inject fragmenter av dekoratøren i HTML,
    enten manuelt eller ved bruk av template engine.
    */
});

Client-side rendering

Obs! CSR vil gi en redusert brukeropplevelse pga layout-shifting/"pop-in" når headeren rendres, og bør unngås om mulig.

Sett inn noen linjer i HTML-templaten:

<html>
  <head>
      <link href="{MILJO_URL}/css/client.css" rel="stylesheet" />
  </head>
  <body>
    <div id="decorator-header"></div>
    {
      DIN_APP
    }
    <div id="decorator-footer"></div>
    <div id="decorator-env" data-src="{MILJO_URL}/env?{DINE_PARAMETERE}"></div>
    <script async="true" src="{MILJO_URL}/client.js"></script>
  </body>
</html>

Parametere

Dekoratøren kan tilpasses med følgende URL-parametere / query-string.

Parameter Type Default Forklaring
context privatperson / arbeidsgiver / samarbeidspartner privatperson Setter menyen til definert kontekst
simple boolean false Viser en forenklet header og footer
simpleHeader boolean false Viser en forenklet header
simpleFooter boolean false Viser en forenklet footer
enforceLogin boolean false Sørger for at brukeren er innlogget på definert sikkerhetsnivå (level) [1]
redirectToApp boolean false (ditt-nav) Sender brukeren tilbake til nåværende url etter innlogging via dekoratøren [2]
redirectToUrl string undefined Sender brukeren til denne url'en etter innlogging via dekoratøren [2]
redirectToUrlLogout string undefined Sender brukeren til denne url'en etter utlogging via dekoratøren
level Level3 / Level4 Level3 Gir brukeren innloggingsvalg basert på definert sikkerhetsnivå [2]
language nb / nn / en / se / pl / uk / ru nb Setter språket til dekoratøren ved server side rendering [3]
availableLanguages [{ locale: nb / nn / en / se / pl, url: string }] [ ] Setter alternativene til språkvelgeren ved server side rendering [4]
breadcrumbs [{ title: string, url: string, handleInApp?: string }] [ ] Setter brødsmulestien for server side rendering [5]
utilsBackground white / gray / transparent transparent Setter bakgrunnsfargen på containeren til brødsmulesti og språkvelger
feedback boolean false Skjuler eller viser tilbakemeldingskomponenten
chatbot boolean true Aktiverer eller deaktiverer Chatbot Frida [6]
chatbotVisible boolean false Skjuler eller viser Chatbot Frida [7]
urlLookupTable boolean false Aktiverer eller deaktiverer url-lookup-table [8]
shareScreen boolean true Aktiverer eller deaktiverer skjermdelingskomponent
logoutUrl string undefined Setter url for logg-ut knappen [9]
maskHotjar boolean true Maskerer hele HTML-dokumentet fra Hotjar [10]
logoutWarning boolean false Viser utloggingsvarsel [11]

[1] Kombineres med level, redirectToApp og EnforceLoginLoader ved behov.
[2] Gjelder både ved automatisk innlogging og ved klikk på innloggingsknappen.
[3] Språk settes automatisk client-side dersom nåværende url inneholder /no/, /nb/, /nn/, /en/, /se/, uavhengig av dette parameteret. Se også seksjon Språkstøtte lenger ned.
[4] Kan settes client-side med setAvailableLanguages og onLanguageSelect. Dersom du oppgir handleInApp, så må du selv håndtere feks route change i applikasjonen din ved klikk i dekoratørmenyen.
[5] Kan settes client-side med setBreadcrumbs og onBreadcrumbClick
[6] Aktiverer/deaktiverer Chatbot Frida. Dersom dette settes til false, vil chatbot aldri vises på siden, selv om bruker har en aktiv chat-sesjon.
[7] Viser/skjuler Chatbot Frida. Dersom dette settes til true, vil chatbot alltid vises. Ved false vises chatbot kun når bruker har en aktiv chat-sesjon (med mindre 'chatbot' er satt til false)
[8] Mapper prod-urler til dev-urler basert på url-lookup-table.
[9] Dersom denne er satt vil dekoratørens utloggingsfunksjonalitet forbigåes, og alt rundt utlogging må håndteres av appen.
[10] Setter data-hj-suppress på HTML-elementet, som hindrer Hotjar fra å fange noe innhold på siden. Default er true, dersom denne settes til false må appen selv sørge for at elementer med personinfo eller annen sensitiv data maskeres på tilsvarende måte. Se hotjar docs. Dekoratørens egne sensitive elementer maskeres uavhengig av dette parameteret. Denne kan ikke endres client-side. [11] Felles funksjonalitet for utloggingsvarsel hvor brukeren også har mulighet til å fornye innloggingen med én time av gangen. Les med om utloggingsvarsel i seksjonen lenger ned.

Dersom ikke noe annet er nevnt, kan samtlige parametre settes client-side

Bakgrunnsfarge på brødsmulesti og språkvelger kan overstyres:

.decorator-utils-container {
    background: #f1f1f1;
}

Eksempler

Eksempel 1 - Endre context:
https://www.nav.no/dekoratoren/?context=arbeidsgiver

Eksempel 2 - Håndhev innlogging:
https://www.nav.no/dekoratoren/?enforceLogin=true&level=Level4&redirectToApp=true

Eksempel 3 - Språkvelger:
https://www.nav.no/dekoratoren/?availableLanguages=[{"locale":"nb","url":"https://www.nav.no/person/kontakt-oss"},{"locale":"en","url":"https://www.nav.no/person/kontakt-oss/en/"}]

Eksempel 4 - Brødsmulesti:
https://www.nav.no/dekoratoren/?breadcrumbs=[{"url":"https://www.nav.no/person/dittnav","title":"Ditt NAV"},{"url":"https://www.nav.no/person/kontakt-oss","title":"Kontakt oss"}]

(Språkvelger og brødsmulesti vises ikke direkte på /dekoratoren i prod av sikkerhetsmessige årsaker)

Content Security Policy

Påkrevde CSP-direktiver for dekoratøren serveres på https://www.nav.no/dekoratoren/api/csp. Se også csp.ts.

nav-dekoratoren-moduler kan benyttes for å generere en CSP-header som er kompatibel med dekoratøren.

Amplitude-klient

Logging med dekoratørens Amplitude-klient eksponeres via funksjonen window.dekoratorenAmplitude. Se logEventFromApp for implementasjon.

nav-dekoratoren-moduler har en hjelpefunksjon for å benytte denne.

Oppsett av Task Analytics undersøkelser

Se nav-dekoratoren-config

Språkstøtte

Grensesnittet (header, meny etc) finnes i tre språkdrakter: norsk bokmål (nb), engelsk (en) og delvis samisk (se).

Du kan angi at språkvelgeren skal støtte flere språk enn dette, som beskrevet i seksjonen ovenfor, men det er kun disse tre språkene som kan vises i selve dekoratør-grensesnittet. For de resterende språkene som språkvelgeren støtter, så vil "nærmeste" relevante språk vises istedet, feks:

  • nn => nb
  • pl => en
  • ru => en

Hopplenke til hovedinnhold

Dekoratøren rendrer en hopplenke dersom et element med id'en maincontent finnes på siden. Klikk på hopplenken vil sette focus til dette elementet.

For at denne funksjonaliteten skal fungere konsistent, må maincontent-elementet inkluderes i HTML'en fra serveren, og elementet må være fokuserbart (f.eks. ved å sette tabindex="-1")

Eksempel:

<main id="maincontent" tabindex="-1">Appens hovedinnhold goes here!</main>

Utloggingsvarsel

Dekoratøren kan håndtere utloggingsvarsel og fornying av token for deg. Dette gjør den direkte mot sentral login-instans. Se seksjon "Slik fungerer utloggingsvarsel" for mer informsjon om når varselet slår inn og hvordan det fungerer.

Oppsett

Du slår på utloggingsvarsel ved sette parameteret logoutWarning. Dekoratøren kaller direkte mot sentral login-instans, enten login.nav.no eller login.ekstern.dev.nav.no. Det er derfor ikke behov for å sette opp Sidecar i din egen applikasjon hvis du ikke trenger den til noe annet. Mer informasjon om Wonderwall i NAIS-dokumentasjon.

Slik fungerer utloggingsvarsel

  • Et token er gyldig i 60 minutter. Hele session er gyldig i 6 timer. Token kan fornyes, men når session utløper etter 6 timer, må bruker uansett logge ut og inn igjen.
  • 5 minutter før utløp av token vil bruker se varsel i form av en popup-dialog.
  • I denne popup-dialogen vil brukeren måtte ta et aktivt valg om å enten fortsette å være innlogget, eller klikke "Logg ut" for å logge ut umiddelbart.
  • Dersom brukeren velger å fortsette å være innlogget, blir tokenet fornyet i nye 60 minutter, forutsatt at session fortsatt er innenfor 6 timer.
  • 10 minutter før session utløper vil bruker få beskjed om å avslutte og eventuelt logge inn på nytt.
  • Bruker vil få beskjed om hvor mange minutter som er igjen før hen blir logget ut.
  • I begge varslene (for token og session) vil bruker måtte ta et aktivt valg. Det er ikke mulig å krysse vekk eller trykke "Esc" for å lukke varselet.
  • Dersom bruker forlater maskinen eller ikke tar et aktivt valg vil hen bli sendt til utloggingssiden når token eller session har utløpt.

Verdt å merke seg

  • Det er først og fremst arbeidsgiver og andre parter som benytter nav.no over lang tid som vil se varselet for utløpt session etter 6 timer.
  • Vi har forsøkt å utforme varselet med mål om minst mulig kognitivt stress og har derfor valgt å droppe nedtelling i grensesnittet. Vi er åpne for tilbakemeldinger etterhvert som flere team begynner å ta ibruk utloggingsvarselet.

Utvikling - Kom i gang

Hent repoet fra github

git clone https://github.com/navikt/nav-dekoratoren.git

Installer nødvendige avhengigheter

npm install

Start eksterne tjenester som oidc-provider og mocks

docker-compose up -d

Kjør applikasjonen lokalt med hot-reloading

npm start

Starter en Node Express / dev - server på
http://localhost:8088/dekoratoren

Oppstart via docker-compose

Start navikt/nav-dekoratoren, navikt/pb-nav-mocked, navikt/stub-oidc-provider og navikt/pb-oidc-provider-gui. Oppsettet vil replikere innlogging og eksterne avhengigheter som varselinnboks.

dekoratoren:
    container_name: dekoratoren
    image: 'docker.pkg.github.com/navikt/nav-dekoratoren/nav-dekoratoren:latest'
    ports:
      - "8100:8088"
    environment:
      ENV: 'localhost' | 'dev' | "prod"
      XP_BASE_URL: 'https://www.nav.no'
      APP_BASE_URL: 'http://localhost:8100'
      APP_BASE_PATH: '/dekoratoren'
      API_XP_SERVICES_URL: 'https://www.nav.no/_/service'
      API_DEKORATOREN_URL=http://localhost:8095/nav-dekoratoren-api
      MINSIDE_ARBEIDSGIVER_URL: 'https://arbeidsgiver.nav.no/min-side-arbeidsgiver/'
      MIN_SIDE_URL: 'https:/www.nav.no/minside'
      LOGIN_URL: 'http://localhost:5000'
      LOGOUT_URL: 'http://localhost:5000/?logout'
    depends_on:
      - mocks

Eksempel i frontend for Enonic XP.
ℹ️   Krever GitHub Packages (ghcr.io) innlogging:

docker login ghcr.io -u GITHUB_USERNAME -p GITHUB_PERSONAL_ACCESS_TOKEN

Manuelt bygg

npm run build-dev (for testing lokalt)
npm run build-prod (for produksjon)

Deploy til dev-miljø

Start deploy workflow via Github web-UI: Actions -> Workflows -> Deploy-to-dev -> Run workflow

Prodsetting

  • Lag en PR til master, og merge inn etter godkjenning
  • Lag en release på master med versjon-bump, beskrivende tittel og oppsummering av endringene dine
  • Publiser release'en for å starte deploy til prod

Henvendelser

Spørsmål knyttet til koden eller prosjektet kan rettes mot https://github.com/orgs/navikt/teams/team-personbruker

For NAV-ansatte

Interne henvendelser kan sendes via Slack i kanalen #team-personbruker.