šŸ‘ HAN-DS

# Finder API

De finder wordt op de volgende pagina's gebruikt:

# Opzetten finder

Voor het plaatsen van de finder is een section--finder nodig met window.FinderSettings. Bekijk de pagina's voor exacte implementatie per zoeker.

<div class="section section--finder layout-media">
  <div class="section-wrapper">
    <div class="section__content">
      <script>
        window.FinderSettings = {
          api: "/.netlify/functions/coursefinder/",
          showSearch: true,
          paginate: 10,
          breadcrumb: [{
              label: "Home",
              href: "/",
              preventDefault: false
          }, {
              label: "Studenten",
              href: "/studenten/",
              preventDefault: false
          }, {
              label: "Opleidingen",
              href: "/studenten/opleidingen",
              preventDefault: false
          }],
          labels: {
            title: 'Opleidingen',
            showMoreFilters: "Toon meer",
            showLessFilters: "Toon minder",
            clearAllFilters: "Alle filters wissen",
            noResults: "Geen resultaten",
            show: "Toon",
            resultsSingle: "resultaat",
            resultsPlural: "resultaten",
            clearAll: "Alles wissen",
            close: "Sluiten",
            filters: "Filters",
            filterAll: "Filter opleidingen",
            noResultsTitle: "Helaasā€¦",
            noResultsMessage: "We kunnen helaas geen resultaten vinden voor:",
            noResultsFound: "Geen opleidingen gevonden",
            singleResultFound: "1 Opleiding gevonden",
            multipleResultsFound: 'Er zijn <x> opleidingen gevonden',
            searchInputLabel: "Zoek een opleiding, cursus etc.",
            clearSearchInput: "Zoekveld leegmaken",
            searchButtonLabel: "Zoeken",
            errorTitle: "Oepsā€¦",
            errorMessage: "Er ging iets mis.",
            errorMessageReload: "Herlaad deze pagina.",
            showTooltip: "Bekijk tooltip",
            showFilterGroup: "Filters tonen",
            hideFilterGroup: "Filters verbergen",
            loading: "Ladenā€¦",
            paginationLabel: "Resultaatpagina's",
            paginationNext: "Volgende",
            paginationPrev: "Vorige",
          }
        };
      </script>
      <div class="js-finder"></div>
    </div>
  </div>
</div>

# Javascript inladen

Naast de findersettings moet ook op de pagina van een finder finder.js worden ingeladen.

  <script src="/static/js/images.vx.x.x" defer></script>
  <script src="/static/js/libs.vx.x.x" defer></script>
  <script src="/static/js/components.vx.x.x" defer></script>
  <script src="/static/js/modal.vx.x.x" defer></script>
- <script src="/static/js/coursefinder.vx.x.x" defer></script>
+ <script src="/static/js/finder.vx.x.x" defer></script>

# Request payload

Er gaat een POST met de volgende payload naartoe:

{
  "filters": ["type-opleiding-voltijd"],
  "query": "foo",
  "handshake": "jwt5edcw",
}

wanneer pagination wordt gebruikt is de payload als volgt:

{
  "filters": ["type-opleiding-voltijd"],
  "query": "foo",
  "handshake": "jwt5edcw",
  "resultsPerPage": 10,
  "currentPage": 5
}

# API JSON response

De finder verwacht de volgende JSON als response van api.

{
  "numResults": 428,
  "handshake": "jwt5edcw",
  "results": [
    {
      "name": "Afasie: communicatie na hersenletsel",
      "url": "https://www.google.com",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis elementum augue, in dapibus arcu. Nulla semper, tortor vel volutpat porta, enim arcu interdum mi, at ultricies lacus felis quis mauris.",
      "avatar": "https://hannl.imgix.net/han-balk.png?w=144&h=144",
      "meta": [
        { "label": "Arnhem", "icon": "marker" },
        { "label": "32 uur", "icon": "clock-line" },
        { "label": "2.850", "icon": "euro" },
        { "label": "Mbo", "icon": "diploma" }
      ]
    },
    ā€¦
  ],
  "filters": [
    {
      "title": "Type opleiding",
      "id": "type-opleiding",
      "collapsed": true,
      "fields": [
        {
          "label": "Voltijd",
          "id": "type-opleiding-voltijd",
          "numResults": 3,
          "helpText": "dit is uitleg over <a href=\"#takeover1\">Voltijd</a>",
          "collapsible": true
        },
        {
          "label": "Deeltijd",
          "id": "type-opleiding-deeltijd",
          "numResults": 2,
        },
        {
          "label": "Duaal",
          "id": "type-opleiding-duaal",
          "numResults": 0,
          "helpText": "dit is uitleg over bachelor",
        }
      ]
    },
    ā€¦
  ]
}

# Results

Required Key Type Description
x numResults {Integer} totaal aantal resultaten
x handshake {String} unieke key om oude requests te kunnen annuleren
x results {Array} Lege array of gevuld met ResultObject
x filters {Array} Lege array of gevuld met FilterObject
totalResults {Number} Totaal aantal resultaten, voor als pagination aanwezig is
currentPage {Number} waarde van currentPage parameter uit request payload

# ResultObject

Required Key Type Description
x name {String} Naam van de opleiding
x url {String} Link naar de pagina
x description {String} Korte beschrijving van de opleiding
avatar {String} Link naar afbeelding, 144x144
image {String} Link naar afbeelding, 450x375. Wordt gebruikt in detail weergave
note {String} Voor bijvoorbeeld aanvullende eisen
meta {Array} Bevat label/icon pairs
meta[].label {String} bijv. Voltijd, Deeltijd
meta{}.icon {String} bijv. arrow, hat etc

# FilterObject

Required Key Type Description
x title {String} Label van de filter groep
x id {String} Id van de filter groep
x collapsed {Boolean} Groep verborgen/getoond
x fields {Array}
x fields[].label {String} label bij het filter
x fields[].id {String} unieke id van de filter
x fields[].numResults {Integer} aantal bijbehorende resultaten
fields[].helptext {String} optionele helptekst, kan html-link bevatten (tooltip)
fields[].collapsible {true} optioneel uitklapbaar (zoals bij startdatum)

# Extra zoekopties

Optioneel kunnen er nog extra zoek opties (queryOptions) meegegeven worden.

# Request payload

{
  "filters": ["type-opleiding-voltijd"]
  "query": "foo",
  "queryOptions": ["team"],
  "handshake": "jwt5edcw"
}

# API JSON response

{
  ā€¦
  "queryOptions": [
    {
      "label": "Zoekresultaten uitbreiden metā€¦",
      "options": [
        {
          "id": "role-expertise",
          "label": "Rol & expertise"
        },
        {
          "id": "team",
          "label": "Team"
        },
        {
          "id": "department",
          "label": "Afdeling"
        }
      ]
    }
  ],
}

# Details / Lijst weergave

Voor de finder kunnen tab knoppen toegevoegd worden waarmee de gebruiker kan kiezen voor detail of lijst weergave. Dit kan geconfigureerd worden met de volgende finder settings:

window.FinderSettings = {
  ā€¦
+ listDisplayActive: "detail",
+ listDisplayOptions: [
+   {
+     label: "Details",
+     value: "detail",
+     icon: "detail",
+   },
+   {
+     label: "Lijst",
+     value: "list",
+     icon: "list",
+   },
+ ],
}

Op de detail weergave wordt een afbeelding getoond bij een resultaat. In ResultObject wordt hiervoor de image property uitgelezen.

# Notitie weergeven in finder result

Bij de resultaten kan een optionele notitie weergegeven worden. Notitie kan toegeovegd worden door op een ResultObject een string mee te geven via de note property.

# Aanbevolen resultaten

In de finder kunnen bovenaan de resultatenlijst aanbevolen resultaten getoond worden.

De finder verwacht de volgende data:

{
  ā€¦
  recommendations: [
    {
      "numResultsLabel": "Deze <b>2 opleidingen</b> sluiten het meest aan op jouw vooropleiding",
      "results": []
    },
    {
      "numResultsLabel": "Deze <b>3 opleidingen</b> sluiten breeder aan op jouw vooropleiding",
      "results": []
    }
  ]
}

De property recommendations is een lijst van objecten. Zo kunnen er verschillende lijsten met aanbevelingen weergegeven worden.

# RecommendationObject

Required Key Type Description
x numResultsLabel {String} Label van met aantal resultaten. Omdat de label qua inhoud afhankelijk is van de filter zit deze niet in de finder settings.
x results {Array} Lijst met ResultObjects

Verder aan de finder settings kunnen de volgende optionele labels toegevoegd worden:

singleResultFoundWithRecommendation: "Er is <b>1 andere opleiding</b> gevonden",
multipleResultsFoundWithRecommendation: "Er zijn <b><x> andere opleidingen</b> gevonden"

# Filter met tabbladen

Om onder een filter titel tabladen te tonen met meerdere filters verwacht de finder de property subfilters in plaats van fields:

{
  "title": "Vooropleiding",
  "id": "vooropleiding",
-  "fields": []
+  "subfilters": [
+    {
+      "title": "Havo/Vwo",
+      "fields": []
+    },
+    {
+      "title": "Mbo Niveau 4",
+      "fields": []
+    }
+  ]
}

# Filter widget met zoekveld

De widget van een subfilter kan aangepast worden naar een widget met zoekveld:

{
  "title": "Vooropleiding",
  "id": "vooropleiding",
  "subfilters": [
    {
      "title": "Havo/Vwo",
      "fields": []
    },
    {
      "title": "Mbo Niveau 4",
      "fields": [],
+     "widget": "filterable-multiselect",
+     "labels": {
+       "input": "Wat is jouw mbo-4 opleiding?",
+       "noResults": "Geen opleidingen gevonden",
+       "toggleItems": "Schakel weergave van mbo-opleidingen lijst"
+     }
    }
  ]
}

ā† Topsearch ā†’