Sist endret: 2. okt. 2024

Modul 1

Opprette app og lage enkelt skjema

I denne modulen skal du opprette selve applikasjonen, legge til datamodell og sette opp et enkelt skjema basert på kravene fra Sogndal kommune.

Du må utføre de to første oppgavene, opprette applikasjon og legge til datamodell, i Altinn Studios grafiske brukergrensesnitt, Altinn Studio Designer (Designer). Dersom du skal utvikle appen lokalt kan du følge instruksjonene for klargjøre for lokal utvikling og testing etter at du har gjort disse oppgavene.

MERK
Du kan utføre alle stegene i denne modulen i Designer. Det krever imidlertid lokal utvikling å gjennomføre de øvrige modulene og for å få en fullt fungerende applikasjon.

Temaer som dekkes i denne modulen:

  • Opprette ny applikasjon
  • Legge til datamodell
  • Legge til skjemakomponenter og koble dem til datamodell
  • Redigering av tekst

Oppgaver

Applikasjoner opprettes fra Altinn Studio Dashboard.

Krav fra kommunen

Applikasjonen må ha et beskrivende navn (ID) som gjør det enkelt å finne den igjen blant det store antallet applikasjoner Sogndal kommune har i Altinn Studio.

Dersom du skal teste appen i et testmiljø (beskrevet i Modul 3) må du velge en organisasjon som eier. Du må ha tilgang til organisasjonen og organisasjonen må ha tilgang til et testmiljø.

Oppgaver

  1. Opprett applikasjon i Altinn Studio

Nyttig dokumentasjon

Datamodellen definerer type og format for data som kan sendes inn via en app.

Med Altinn Studios verktøy for datamodellering kan du legge til en datamodell ved å laste opp en xsd-fil eller lage en ny datamodell fra bunnen av. Du kan også ta utgangspunkt i en eksisterende datamodell og redigere den i et tekstredigeringsprogram eller direkte i Altinn Studio. I denne oppgaven skal du kun laste opp en ferdig datamodell.

Krav fra kommunen

Sogndal kommune har opprettet en datamodell som representerer type data de ønsker å samle inn fra fremtidige innbyggere.

Oppgaver

  1. Last ned xsd-filen. Hvis filen åpnes i nettleseren kan du opprette en ny tekstfil og kopiere over innholdet. Lagre filen som datamodel.xsd. Alternativt kan du kopiere URLen til filen og kjøre kommandoen curl <fil-URL> > datamodel.xsd fra kommandolinjen. Åpne filen i et tekstredigeringsprogram og ta en nærmere titt på innholdet.
  2. Last opp datamodellen i Altinn Studio
  3. Klikk “Last opp dine endringer” og følg instruksjonene for å lagre endringene.
  4. Åpne repository til appen fra Altinn Studio Dashboard og ta en nærmere titt på filene i mappen App/models.
Hvis du skal gjøre hele eller deler av utviklingen lokalt kan du nå klargjøre for lokal utvikling og testing.

Nyttig dokumentasjon

Forståelsessjekk

Datamodellen består av ett hovedelement: innflytter. Dette elementet består igjen av en del underobjekter som Fornavn, Etternavn, og Mellomnavn. I tillegg er det noen sammensatte elementer som Adresse, Kontaktinformasjon og Arbeidsinformasjon.

minOccurs sier noe om hvor mange ganger objektet minst må være nevnt.

  • minOccurs=0 vil si at feltet ikke er påkrevd.
  • minOccurs=1 vil si at man forventer at det dukker opp minimum én gang i modellen.
nillable=true er definert på mellomnavn-feltet. Det vil si at det er tillatt med en nullverdi på mellomnavn.

De nevnte filene er alle generert ut ifra xsd-beskrivelsen av datamodellen. De beskriver all dataen og datafeltenes egenskaper. Alle egenskaper er ikke nødvendigvis overført i alle filene, men summen av dem skal opprettholde det som er beskrevet i xsd-filen.

  • C#-modellen benyttes av app backend til å deserialisere data og gjøre den tilgjengelig for prosessering og validering.
  • .metadata.json benyttes i Altinn Studio for å enkelt kunne koble komponenter og dynamikk til datafeltene.
  • .schema.json-filen benyttes av altinn-app-frontend for skjemavalidering på klientsiden.
  • Egenskapene minOccurs og maxOccurs er ikke overført til modellen.
  • nillable er kun overført på enkelte typer som f.eks. decimal.
  • XmlElement.Order er innført som en dekorasjon på hver egenskap.
    • Dette sørger for at rekkefølgen på elementene alltid vil bli den samme når dataen serialiseres til xml.

Tekster i Altinn Studio lagres i en egne språkfiler (også kalt tekstressurser) og kan knyttes til skjema-komponenter via en tekstnøkkel. Tekstene kan opprettes og redigeres i Altinn Studio Designer eller direkte i filen.

MERK: Visningsnavn for applikasjonen må endres både i App/config/applicationmetadata.json og i språkfilene.

Krav fra kommunen

For at tjenesten skal være brukervennlig og mulig å benytte for de som sitter med synshemninger er det viktig at alle komponenter har gode og beskrivende overskrifter (labels).

Oppgaver

  1. Opprett tekstressurser for komponentene til det første skjemaet. Tekstene skal beskrive hva som skal fylles inn og vil vises over feltene. Ta en titt på neste oppgave for å se hvilke komponenter du trenger tekst til.
  2. Endre visningsnavn for applikasjonen. Det er viktig at applikasjonens visningsnavn klinger godt og er beskrivende for tjenesten.
  3. Legg til oversettelse(r) for tekstene. Applikasjonen må være tilgjengelig både på bokmål, nynorsk og engelsk. I en første versjon er det tilstrekkelig at kun ett av disse språkene støttes.

Husk å laste opp endringer når du jobber i Designer så de reflekteres i repoet. I neste steg skal du opprette komponenter og knytte tekstene du har opprettet til disse.

Nyttig dokumentasjon

Forståelsessjekk

I Altinn i dag støtter vi tre skriftspråk: bokmål, nynorsk og engelsk.

For å manuelt legge til støtte for engelsk i en applikasjon må du opprette filen resources.en.json i mappen App/config/texts:

App/config/texts/resources.en.json
{
  "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4/schemas/json/text-resources/text-resources.schema.v1.json",
  "language": "en",
  "resources": []
}

Merk at language-egenskapen øverst i filen må settes til en.

Hvis nevnte tekstnøkkel ikke finnes i tekstressursfilen, vil tekstnøkkelen vises i stedet.

Du kan konfigurere komponentene i en applikasjon i det grafiske brukergrensesnittet Altinn Studio Designer. Alternativt kan du gjøre det manuelt ved å redigere filen <page>.json som beskriver strukturen til en skjemaside. Du finner filen i App/ui/layouts.

Krav fra kommunen

Første skjemaside innhenter personlig informasjon om tilflytteren og skal ha følgende komponenter:

  • Navn
    • Fornavn
    • Mellomnavn (valgfritt)
    • Etternavn
  • Alder
  • Adresse
    • Gateadresse
    • Postnummer
    • Poststed
  • Kontaktinformasjon
    • Epost
    • Telefon

Feltene skal være obligatoriske med mindre noe annet er indikert.

Oppgaver

  1. Sett opp den første skjemasiden med komponenter basert på kravene fra kommunen.
  2. Koble tekst til hver av komponentene.

Husk å laste opp endringer når du jobber i Designer så de reflekteres i repoet.

Nyttig dokumentasjon

Forståelsessjekk

I applikasjonsrepoet ditt finner du <page>.json i mappen App/ui/layouts. JSON-filen beskriver skjemasiden du har satt opp i Altinn Studio gitt at du har lastet opp endringene (<page> erstattes av navnet til siden, for eksempel data.json).

For å finne komponenten som er koblet til epost-feltet kan du søke etter ’epost’. Navnet på feltet som komponenten er koblet til finner du under dataModelBindings.simpleBinding (markert).

App/ui/layouts/{page}.json
{
  ...
  
  "id": "epost",
  "type": "Input",
  "dataModelBindings": {
    "simpleBinding": "Innflytter.Kontaktinformasjon.Epost"
  },
  "required": true,
  "readOnly": false,
  "textResourceBindings": {
    "title": "innflytter.epost"
  }
}
For å gjøre et felt valgfritt, kan man endre required: true til required: false.

Løsningen er å endre type-feltet fra Input til TextArea (markert).

App/ui/layouts/{page}.json
{
  "id": "mellomnavn",
  "type": "TextArea",
  "textResourceBindings": {
    "title": "innflytter.mellomnavn"
  },
  "dataModelBindings": {
    "simpleBinding": "Innflytter.Mellomnavn"
  },
  "required": true,
  "readOnly": false
}

Oppsummering

I denne modulen har du opprettet en applikasjon i Altinn Studio, lagt til en datamodell og satt opp en skjemaside som kobler komponenter til noen av feltene i datamodellen.

Dersom du har klargjort for lokal utvikling har du i tillegg klonet applikasjonen for å kunne videreutvikle den i ditt lokale utviklingsmiljø. Applikasjonen skal kunne kjøres på din lokale maskin med LocalTest og du skal kunne fylle inn feltene.

Løsningsforslag

Kildekode Modul 1

Nedenfor kan du se hvordan tekstene vi har lagt til ser ut i Altinn Studio og hvordan dette reflekteres i resources.nb.json filen i repoet.

    Tekster i Altinn Studio

    Tekstene vist i Altinn Studio. Bilde
    Tekstene vist i Altinn Studio

    Tekster i repository

    App/config/texts/resource.nb.json
    {
  "language": "nb",
  "resources": [
    {
      "id": "appName",
      "value": "Flyttemelding Sogndal"
    },
    {
      "id": "firstName",
      "value": "Fornavn"
    },
    {
      "id": "middleName",
      "value": "Mellomnavn"
    },
    {
      "id": "lastName",
      "value": "Etternavn"
    },
    {
      "id": "age",
      "value": "Alder"
    },
    {
      "id": "streetName",
      "value": "Gatenavn"
    },
    {
      "id": "postalCode",
      "value": "Postnummer"
    },
    {
      "id": "postalLocation",
      "value": "Sted"
    },
    {
      "id": "email",
      "value": "E-post"
    },
    {
      "id": "phone",
      "value": "Telefonnummer"
    }
  ]
}

    Nedenfor kan du se hvordan den første skjemasiden ser ut og hvilke komponenter vi har brukt.

    Skjermbilde av første skjemaside
    Første skjemaside

      Komponenter

      Se Kode for å se hvordan oppsettet av skjemasiden reflekteres i koden.

      Komponenter på første skjemaside. Bilde.
      Komponenter på første skjemaside

      Komponentinnhold

      Under kan du se innholdet til “Mellomnavn”-komponenten.
      Her har vi satt komponent-ID, feltet i datamodellen komponenten er knyttet til og angitt nøkkelen til tekstressursen som vi definerte i forrige steg.

      Innholdet til "Mellomnavn"-komponenten i Altinn Studio. Bilde.
      Innholdet til \"Mellomnavn\"-komponenten i Altinn Studio

      Innstillinger - “Påkrevd”

      Huk av for ‘Det skal være påkrevd for brukeren å svare’ for felt som er obligatoriske for brukeren (alle felt med unntak av “Mellomnavn”):

      Påkrevd instilling. Bilde.
      Påkrevd instilling

      Skjemaside

      Under finner du koden for den første skjemasiden som ligger i repoet under App/ui/layouts/.

      App/ui/layouts/innflytterPersonalia.json
      {
  "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4//schemas/json/layout/layout.schema.v1.json",
  "data": {
    "layout": [
      {
        "id": "firstName",
        "type": "Input",
        "dataModelBindings": {
          "simpleBinding": "Innflytter.Fornavn"
        },
        "required": true,
        "readOnly": false,
        "textResourceBindings": {
          "title": "firstName"
        }
      },
      {
        "id": "middleName",
        "type": "Input",
        "dataModelBindings": {
          "simpleBinding": "Innflytter.Mellomnavn"
        },
        "required": false,
        "readOnly": false,
        "textResourceBindings": {
          "title": "middleName"
        }
      },
      {
        "id": "lastName",
        "type": "Input",
        "dataModelBindings": {
          "simpleBinding": "Innflytter.Etternavn"
        },
        "required": true,
        "readOnly": false,
        "textResourceBindings": {
          "title": "lastName"
        }
      },
      {
        "id": "age",
        "type": "Input",
        "dataModelBindings": {
          "simpleBinding": "Innflytter.Alder"
        },
        "required": true,
        "readOnly": false,
        "textResourceBindings": {
          "title": "age"
        }
      },
      {
        "id": "address",
        "type": "Address",
        "dataModelBindings": {
          "address": "Innflytter.Adresse.Gateadresse",
          "zipCode": "Innflytter.Adresse.Postnr",
          "postPlace": "Innflytter.Adresse.Poststed"
        },
        "simplified": true,
        "readOnly": false,
        "required": true
      },
      {
        "id": "email",
        "type": "Input",
        "dataModelBindings": {
          "simpleBinding": "Innflytter.Kontaktinformasjon.Epost"
        },
        "required": true,
        "readOnly": false,
        "textResourceBindings": {
          "title": "email"
        }
      },
      {
        "id": "phoneNumber",
        "type": "Input",
        "dataModelBindings": {
          "simpleBinding": "Innflytter.Kontaktinformasjon.Telefonnummer"
        },
        "required": true,
        "readOnly": false,
        "textResourceBindings": {
          "title": "phone"
        }
      },
      {
        "id": "NavigationButtons-yxdxMR",
        "type": "NavigationButtons",
        "showBackButton": true
      }
    ]
  }
}