Working version v32.1.X v32.0.X v29.1.X
Working version v32.1.X v32.0.X v29.1.X Dutch

Backoffice aanpassen

Vooraf

De backoffice is gebouwd in AngularJS, op het platformpakket @skryv/core-ng1. Je past ze aan in de module backoffice van je applicatie. In oudere applicaties heet die module soms frontend. Welke aanpassingen mogelijk zijn en hoe zwaar ze wegen bij een upgrade, lees je in het Overzicht uitbreidingspunten.

Je hebt nodig:

  • een applicatie die lokaal draait, zie Lokale setup

  • toegang tot de npm-registry van Skryv, voor de @skryv-pakketten

  • basiskennis van AngularJS-componenten

Stap 1: registreer je aanpassingen via de plugin

Alles wat je in de backoffice aanpast, komt samen in het bestand index.js van de module. Daar start de backoffice op, via een ketting van customize(...)-aanroepen:

JavaScript
import skryv, { navigation, translation, search } from "@skryv/core-ng1";
import mijnappCustomizations from "./customizations";

// hier configureer je navigation, search en translation (stap 3 tot 5)

skryv
  .customize(mijnappCustomizations)
  .customize(navigation)
  .customize(search)
  .customize(translation)
  .initialize(document.getElementById("root"));

Je eigen componenten bundel je in een plugin die Angular1Plugin uitbreidt. Die plugin krijgt een naam en een lijst AngularJS-modules mee:

JavaScript
// customizations/index.js
import { Angular1Plugin } from "@skryv/core-ng1";
import components from "./components";

export class MijnappCustomizations extends Angular1Plugin {
  constructor() {
    super("mijnapp", [components]);
  }
}

export default new MijnappCustomizations();

Een gangbare indeling van de map customizations:

Map

Inhoud

components

Je eigen AngularJS-componenten

constants

Gedeelde constanten, zoals de keys van dossiertypes en documenten

search

Componenten en configuratie voor eigen zoekschermen

store

Eigen acties voor de store

Stap 2: maak een eigen component

Een eigen component is een gewoon AngularJS-component in een eigen module:

JavaScript
import angular from "angular";
import template from "./MijnappDossier.html";

const namespace = "mijnapp/components/dossier/MijnappDossier";

angular
  .module(namespace, [])
  .component("mijnappDossier", {
    template,
    bindings: {
      apiDossier: "<",
      dosdef: "<",
    },
    controller: function () {},
  });

export default namespace;

Geef je componenten een prefix van je applicatie, zoals mijnapp. Zo onderscheid je ze in een template meteen van de platformcomponenten, die met skr- beginnen.

In je eigen componenten kun je platformcomponenten hergebruiken. Een eigen zoekscherm kan bijvoorbeeld gewoon het platformcomponent <skr-search> gebruiken, met een eigen configuratie.

Stap 3: vervang een standaardpagina

Wil je een standaardpagina, zoals het dossieroverzicht of het dashboard, vervangen door een eigen versie? Dan overschrijf je de view content van die pagina in index.js:

JavaScript
const skrPages = skryv.constants.navigation.pageNames;

navigation
  .page(skrPages.DASHBOARD, {
    extend: true,
    views: { content: "mijnappDashboard" },
  });

Met extend: true behoud je de rest van de paginadefinitie en vervang je alleen de view die je opgeeft. Je verwijst naar je component met zijn naam.

Alleen vervangen waar nodig

Je hoeft een pagina niet voor alle dossiertypes te vervangen. Je component kan per dossiertype kiezen tussen een eigen weergave en het standaardcomponent:

HTML
<mijnapp-dossier-subsidie
  ng-if="$ctrl.dosdef.key === $ctrl.dossierKeys.SUBSIDIE"
  api-dossier="$ctrl.apiDossier">
</mijnapp-dossier-subsidie>

<skr-dossier-overview
  ng-if="$ctrl.dosdef.key !== $ctrl.dossierKeys.SUBSIDIE"
  api-dossier="$ctrl.apiDossier"
  dosdef="$ctrl.dosdef"
  procdefs="$ctrl.procdefs"
  processes="$ctrl.processes"
  authorizations="$ctrl.authorizations">
</skr-dossier-overview>

Zo blijven alle andere dossiertypes het standaardscherm van het platform gebruiken, inclusief de verbeteringen uit nieuwe platformversies.

Je component krijgt van het platform dezelfde bindings als het component dat het vervangt, bijvoorbeeld apiDossier, dosdef, procdefs, processes en authorizations op de dossierpagina. Val je terug op het standaardcomponent, geef dan alle bindings door. Een nieuwe platformversie kan een binding verplicht maken: sinds versie 29 vraagt <skr-dossier-overview> bijvoorbeeld de binding authorizations. Controleer daarom bij elke upgrade de release notes.

Wie een pagina vervangt, neemt de verantwoordelijkheid over voor alles wat ze deed, zoals verversen na een wijziging of het tonen van de juiste knoppen per rol. Vervang daarom zo weinig mogelijk.

Stap 4: configureer de zoekfunctie

De zoekfunctie configureer je zonder iets te vervangen.

Extra zoekvelden

Met search.setSearchOptionsConfigurationFor(...) voeg je zoekvelden toe aan de dossierzoekopdracht. Je beschrijft de velden met dezelfde syntax als een formulier, en koppelt elk veld via queryRules aan een of meer paden in de documenten:

JavaScript
const skrSearchTables = skryv.constants.search.searchNames;

search.setSearchOptionsConfigurationFor(skrSearchTables.SEARCH_DOSSIERS, {
  definition: {
    fields: [
      { type: "text", name: "ondernemingsnummer", label: "Ondernemingsnummer" },
    ],
  },
  queryRules: {
    ondernemingsnummer: {
      paths: ["document.aanvraag.aanvrager.ondernemingsnummer"],
    },
  },
});

Omdat de velddefinitie de syntax van formulieren volgt, kun je ook validaties toevoegen met computedExpressions en conditions.

Standaardweergave van de takenlijst

Met search.defaultForTasks(...) stel je de kolommen, filters en sortering in die gebruikers standaard zien:

JavaScript
search.defaultForTasks({
  name: "Standaardweergave",
  columns: ["task.name", "dossier.label", "task.due", "task.created"],
  filters: [],
  sort: { criterion: "task.created", desc: true },
});

Stap 5: voeg vertalingen toe

Teksten van je eigen componenten vertaal je in .po-bestanden. Je voegt ze toe in index.js, samen met de vertalingen van je configuratie, en je stelt de standaardtaal en de selecteerbare talen in:

JavaScript
translation
  .add("nl_BE", configuratieVertalingen)
  .add("nl_BE", customizatieVertalingen)
  .locale("nl_BE")
  .selectable(["nl_BE", "fr_BE"]);

Gebruik ook in de configuratie van zoekvelden vertaalbare teksten in plaats van vaste labels in één taal.

Stap 6: voeg store-acties toe

De backoffice gebruikt een store in Redux-stijl. Met een eigen actie haal je gegevens op die de standaardbackoffice niet ophaalt. Een actie kan een bestaand actietype van het platform hergebruiken, maar met een andere API-aanroep, bijvoorbeeld naar een eigen REST-endpoint in de back-end:

JavaScript
export function mijnappFetchTasklist(listKey = "DEFAULT", payload = {}, page, size) {
  return {
    type: "FETCH_TASKS",
    listKey,
    api: {
      url: "/api/mijnapp/tasks/filtered",
      method: "POST",
      params: { page: page - 1, size },
      data: payload,
    },
  };
}

Het platform voert de aanroep uit die in api beschreven staat. Zo'n eigen endpoint bouw je als backend-extensie, zie Backend-extensie bouwen.

Stap 7: bouw en test

De backoffice wordt meegebouwd met de volledige applicatie. Wil je alleen de backoffice compileren of testen, dan doe je dat in de module zelf:

Bash
cd backoffice
npm install
npx skryv-cli compile
npm test

Snapshottests van je componenten moet je na een platformupgrade vaak bijwerken, omdat nieuwe platformversies extra gegevens ophalen of andere componenten tonen.

Waar je op moet letten

Verwijs je in code naar keys uit je configuratie, zoals de key van een dossiertype, een document of een mijlpaal? Bundel ze dan in één bestand in constants, en hernoem ze in Skryv Studio niet zonder ook de code aan te passen. Een hernoemde key geeft geen foutmelding: je eigen scherm verschijnt dan gewoon niet meer. Geef elementen waarnaar code verwijst bovendien een betekenisvolle key, en niet de ID die de BPMN-editor automatisch toekent.

Het thema en de iconen van de backoffice pas je aan zoals beschreven op Custom backoffice thema en Iconen toevoegen in backoffice.

Resultaat

Je aanpassingen zijn geregistreerd via één plugin en worden mee opgebouwd met de applicatie. Waar je een standaardpagina vervangt, blijven de andere dossiertypes het standaardscherm van het platform gebruiken.