Altinn Studio V9 (preview) Utvikle tjenester Utforming Underskjema

Preview: Dette er dokumentasjonen for Altinn Studio v9, som er en forhåndsversjon. Gjeldende versjon er v8. For å se dokumentasjonen for gjeldende versjon, velg v8 i versjonsvelgeren i menyen til venstre.

Sette opp underskjema i en app

Slik setter du opp underskjema i appen din

Et underskjema er et lite skjema inne i hovedskjemaet, som brukeren kan fylle ut flere ganger. Hver utfylling blir en egen oppføring. Hovedskjemaet viser oppføringene i en tabell, der brukeren kan legge til, endre og slette dem.

Eksempel: I en søknad skal brukeren oppgi alle kjøretøyene til virksomheten. For hvert kjøretøy klikker brukeren på en knapp i tabellen, fyller ut underskjemaet om kjøretøyet og klikker på Ferdig for å gå tilbake til hovedskjemaet. Tabellen viser da en ny rad med for eksempel registreringsnummer og merke.

Velge mellom underskjema og repeterende gruppe

Både underskjema og repeterende grupper lar brukeren legge inn flere oppføringer av samme type. Et underskjema passer best når

hver oppføring har mange felter eller trenger flere sider
du vil gi brukeren en ryddig oversikt i hovedskjemaet, og vise detaljene først når brukeren åpner en oppføring
mottakeren trenger en egen PDF for hver oppføring

Har hver oppføring bare noen få felter, er en repeterende gruppe ofte enklere, både for deg og for brukeren.

Slik fungerer underskjema

Underskjemaet har sin egen datamodell, altså en egen beskrivelse av hvilke opplysninger det samler inn.
Appen lagrer hver oppføring som et eget dataelement, det vil si en egen datafil i instansen.
Underskjemaet har egne sider, som du utformer på samme måte som sidene i hovedskjemaet.
Underskjemaet er ikke et eget steg i prosessen. Brukeren fyller det ut mens hovedskjemaet er åpent, og sender inn alt samlet fra hovedskjemaet.
I hovedskjemaet bruker du komponenten Tabell for underskjema (Subform). Du velger selv hvilke opplysninger fra underskjemaet tabellen skal vise som kolonner.

Dette får du fra plattformen

Når du har satt opp underskjemaet, gjør Altinn Studio dette uten ekstra arbeid:

Tabellen får knapper for å legge til, endre og slette oppføringer.
Designer legger automatisk inn en knapp for å lukke underskjemaet på alle sidene i underskjemaet.
Appen lagrer opplysningene i underskjemaet og sørger for at alt er lagret før brukeren kommer tilbake til hovedskjemaet. Finnes det opplysninger som appen ikke kan lagre, blir brukeren stående i underskjemaet.
Appen viser en feilmelding hvis brukeren legger inn færre eller flere oppføringer enn du har tillatt. Da må du ha satt både minste og største antall.
Oppføringene kommer med i PDF-en for hovedskjemaet.

Dette har du ansvar for

Som tjenesteeier må du bestemme

hvilke opplysninger tabellen skal vise, slik at brukeren kjenner igjen hver oppføring
hvor mange oppføringer brukeren må eller kan legge inn
om appen skal kontrollere opplysningene i underskjemaet før brukeren kan lukke det
om mottakeren trenger én PDF for hele innsendingen, eller én PDF for hver oppføring

Du har også ansvar for at tekstene på knapper og kolonnetitler er tydelige, slik at også brukere av skjermleser forstår tabellen. Test alltid med et realistisk antall oppføringer før du setter tjenesten i produksjon.

Begrensninger

Et underskjema kan ikke inneholde

komponenten for filopplasting, så brukeren kan ikke legge ved filer
et annet underskjema
knapper som sender skjemaet videre i prosessen
komponenten for betaling

Designer kan foreløpig ikke forhåndsvise underskjemaet. Du må teste det i appen.

Hovedskjemaet kan heller ikke koble felter direkte til datamodellen for underskjemaet. Vil du vise opplysninger fra underskjemaet i hovedskjemaet, bruker du kolonnene i tabellen eller en oppsummering.

Legge til et underskjema

Du kan sette opp underskjemaet i Altinn Studio Designer eller manuelt i filene til appen. Designer er det trygge standardvalget. Det manuelle oppsettet trenger du bare hvis du vil bruke innstillinger som Designer ikke har ennå.

I denne delen av veiledningen bruker du for det meste Utforming-siden i Designer. Klikk på Utforming i toppmenyen for å gå dit.

Legg til en tabell for underskjema Gå til siden i hovedskjemaet der tabellen skal ligge. I listen over komponenter går du til Avansert og velger Tabell for underskjema.
Velg eller lag underskjemaet Når du velger tabellen, ser du Velg underskjemaet du vil bruke i panelet til høyre.
- Har du allerede et underskjema, velger du det i listen Velg et underskjema.
- Vil du lage et nytt, klikker du på Opprett et nytt underskjema. Skriv inn Navn på underskjema, og velg datamodellen under Velg datamodellfelt. Har du ikke en datamodell for underskjemaet, velger du Lag ny datamodell og skriver inn Navn på ny datamodell. Klikk på Lagre.
Velge eller opprette et underskjema
Utform underskjemaet Klikk på Utform underskjemaet. Du kommer da til sidene i underskjemaet, og kan legge til komponenter som i hovedskjemaet. Designer legger automatisk til komponenten Knapp for å lukke underskjema på hver side. Knappen tar brukeren tilbake til hovedskjemaet. Du kan slette den på sider som ikke skal ha den, men pass på at brukeren alltid kommer seg tilbake.
Legg til kolonner i tabellen Gå tilbake til hovedskjemaet og velg Tabell for underskjema. Under Valg for tabell klikker du på Legg til kolonne.
Sett opp kolonnene For hver kolonne gjør du dette:
- Velg en komponent under Velg komponenten fra underskjemaet som skal vises her. Listen viser bare komponenter som har en ledetekst og er koblet til datamodellen.
- Har komponenten flere felter, velger du hvilket felt kolonnen skal vise under Velg et felt.
- Skriv inn en Kolonnetittel.
Klikk på Lagre når du er ferdig.
Sette opp kolonnene

Når du lager en ny datamodell for underskjemaet, setter Designer både minste og største antall oppføringer til 1. Brukeren kan da bare legge inn én oppføring. Slik endrer du antallet:

Gå til Datamodell i toppmenyen og velg datamodellen for underskjemaet i nedtrekkslisten.
Klikk på navnet til datamodellen øverst i treet.
På fanen Metadata fyller du ut Minste mulige antall og Største mulige antall. Med 0 som minste antall trenger ikke brukeren legge inn noen oppføringer. Med 0 som største antall er det ingen øvre grense.

Designer lagrer endringene automatisk.

Lag en datamodell for underskjemaet. Du får da tre filer under App/model: klassen i C#, JSON-skjemaet og XSD-filen.
Kontroller at datatypen for underskjemaet ligger i App/config/applicationmetadata.json. Med minCount og maxCount styrer du hvor mange oppføringer brukeren må og kan legge inn. Sett begge verdiene, ellers viser ikke appen feilmelding om antallet mens brukeren fyller ut skjemaet. maxCount satt til 0 betyr at det ikke er noen øvre grense.
App/config/applicationmetadata.json
```
{
  "id": "Kjoretoy",
  "allowedContentTypes": ["application/xml"],
  "appLogic": {
    "autoCreate": false,
    "classRef": "Altinn.App.Models.Kjoretoy.Kjoretoy"
  },
  "minCount": 1,
  "maxCount": 10
}
```
Lag en mappe under App/ui med navnet du vil gi underskjemaet, for eksempel kjoretoy.
Vanligvis må mappenavnet under App/ui være likt ID-en til et steg i prosessen. Underskjemaet er et unntak, fordi det ikke er et eget steg. Her velger du mappenavnet selv, og det er dette navnet du bruker i layoutSet når du legger til tabellen i hovedskjemaet.
Legg til en Settings.json-fil og en mappe som heter layouts i underskjemamappen. Sett defaultDataType til ID-en til datatypen for underskjemaet, og type til subform. Designer bruker type til å kjenne igjen mappen som et underskjema.
App/ui/kjoretoy/Settings.json
```
{
  "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4/schemas/json/layout/layoutSettings.schema.v1.json",
  "defaultDataType": "Kjoretoy",
  "type": "subform",
  "pages": {
    "order": ["side1"]
  }
}
```
Resten av Settings.json setter du opp på samme måte som for andre sider.
Legg til sidene til underskjemaet i layouts-mappen, slik du gjør for hovedskjemaet. Se begrensningene for hvilke komponenter du ikke kan bruke i et underskjema.

Legg til en knapp som lukker underskjemaet. Det er en CustomButton med handlingen closeSubform. Uten egen tekst viser knappen teksten Ferdig. Legg til validation hvis du vil at appen skal kontrollere opplysningene før brukeren lukker underskjemaet.

App/ui/kjoretoy/layouts/side1.json

{
  "id": "kjoretoy-ferdig",
  "type": "CustomButton",
  "textResourceBindings": {
    "title": "kjoretoy.ferdig"
  },
  "actions": [
    {
      "type": "ClientAction",
      "id": "closeSubform",
      "validation": {
        "page": "all",
        "show": ["All"]
      }
    }
  ]
}

Gå til layoutfilen for siden i hovedskjemaet der tabellen skal ligge.

Legg til en Subform-komponent med innstillingene du vil ha. Sett layoutSet til navnet på underskjemamappen. Hver kolonne henter verdien sin fra datamodellen til underskjemaet med et dataModel-uttrykk i value.

App/ui/{taskId}/layouts/{page}.json

{
  "id": "kjoretoy-tabell",
  "type": "Subform",
  "layoutSet": "kjoretoy",
  "textResourceBindings": {
    "title": "kjoretoy-tabell.title",
    "addButton": "kjoretoy-tabell.add"
  },
  "showAddButton": true,
  "showDeleteButton": true,
  "entryDisplayName": ["dataModel", "RegNr"],
  "tableColumns": [
    {
      "headerContent": "kjoretoy-tabell.regnr",
      "cellContent": {
        "value": ["dataModel", "RegNr"]
      }
    },
    {
      "headerContent": "kjoretoy-tabell.merke",
      "cellContent": {
        "value": ["dataModel", "Merke"],
        "default": "kjoretoy-tabell.merke.ukjent"
      }
    }
  ]
}

Et underskjema kan ha sin egen oppsummeringsside, og du kan også ta det med i oppsummeringen for hovedskjemaet. Da bruker du Summary2 med "target": { "type": "component", "id": "kjoretoy-tabell" }, altså ID-en til tabellen i hovedskjemaet.

Vise underskjemaet i oppsummering og PDF

Du kan ta med underskjemaet i oppsummeringen for hovedskjemaet. I egenskapene til oppsummeringen legger du til en overstyring under Overstyringer og velger tabellen i Velg komponent. Under Visningstype velger du mellom

Tabell, som viser de samme kolonnene som tabellen i hovedskjemaet
Fullstendig, som viser alle opplysningene i hver oppføring

PDF-en som appen lager for hovedskjemaet, viser automatisk alle opplysningene i alle oppføringene. Har utviklerne laget en egen side for PDF-en, er det den siden som bestemmer hva PDF-en viser.

Trenger mottakeren en egen PDF for hver oppføring, må utviklerne legge inn et eget steg i prosessen. Les hvordan de gjør det i PDF-generering for underskjema.

PDF-generering for underskjema
Slik setter du opp PDF-generering for underskjema
Innstillinger for underskjema
Oversikt over innstillingene for komponenten Tabell for underskjema (Subform)