Opbouw van extern JSON-bestand

Inleiding

Dit artikel beschrijft hoe een extern JSON-bestand is opgebouwd en hoe de verschillende velden gebruikt worden binnen Mach3Blocks. Aan de hand van een voorbeeldbestand leggen we de structuur en betekenis van alle onderdelen uit.

Een voorbeeld JSON bestand is te bekijken via de collectie in het systeem. Ga hiervoor naar de collectie-instellingen en klik op de tab 'data'.
Daar zie je een link 'Voorbeeld JSON'.

Het JSON-bestand bestaat uit twee hoofdonderdelen:

• tags de tags worden gebruikt voor filtering
• items de daadwerkelijke content

1. Tags (filterstructuur)

De tags-sectie definieert de filterstructuur die gebruikt kan worden in overzichten.

Opbouw

Een taggroep bevat:

• name* naam van de taggroep (meertalig mogelijk)
• slug URL-vriendelijke naam
• hidden bepaalt of de taggroep zichtbaar is
• tags lijst met onderliggende tags

{
  "name": {
    "nl": "Taggroep 1",
    "en": "Taggroep 1"
  },
  "slug": {
    "nl": "taggroep-1",
    "en": "taggroep-1"
  },
  "hidden": false,
  "tags": [
    {
      "id": 3,
      "name": {
        "nl": "Tag 1.1",
        "en": "Tag 1.1"
      },
      "slug": {
        "nl": "tag-1-1",
        "en": "tag-1-1"
      },
      "hidden": false
    }
  ]
}

Belangrijke velden

• id* unieke identifier van een tag (wordt gebruikt bij items)
• name* de naam zoals de tag wordt weergegeven (meertalig)
• slug hiermee kun je de slug van het filter bepalen
• hidden bepaalt zichtbaarheid in filters

2. Items (content)

Basisvelden

• nano-id unieke identificatie
• name* naam van het item
• slug hiermee kun je slug van de pagina bepalen
• href hiermee link je het item naar een externe url. Dit werkt alleen als de collectie-instelling 'standaard item link' op 'uit externe data' ingesteld staat.
• target bepaalt hoe de link opent (_blank, _self). Dit werkt alleen als de collectie-instelling 'standaard item link doel' op 'uit externe data' ingesteld staat.
• aria-label toegankelijkheidslabel welke op de href naar de detailpagina wordt geplaatst.

Voorbeeld:

"nano-id": "abc123",
"name": "Paginanaam",
"slug": "specifieke-pagina-naam-slug",
"href": "https:\/\/www.example.com\/externe-data\/item-1\/",
"target": "_blank",
"aria-label": "Lees over paginanaam",

SEO-velden

• meta-title de titel van de detailpagina
• meta-description de META omschrijving van de detailpagina
• meta-keywords de META keywords van de detailpagina.

Voorbeeld:

"meta-title": "Dit is de pagina titel",
"meta-description": "Dit is de omschrijving van de pagina",
"meta-keywords": "keyword-1, keyword-2, keyword-3",

Share-velden

• share-title Titel welke je ziet bij het delen van de detailpagina.
• share-description Omschrijving welke je ziet bij het delen van de detailpagina.
• share-image Afbeelding welke je ziet bij het delen van de detailpagina.

Voorbeeld:

"share-title": "Dit is de share titel.",
"share-description": "Dit is de share omschrijving",
"share-image": "https:\/\/www.example.com\/share.jpg",

Zichtbaarheid en gedrag

• hidden item verbergen
• unsearchable uitsluiten in de website zoekresultaten
• noindex niet indexeren door zoekmachines
• nofollow links niet laten volgen door zoekmachines

Voorbeeld:

"hidden": false,
"unsearchable": false,
"noindex": false,
"nofollow": false,

Publicatieperiode

• show-from datum vanaf wanneer zichtbaar
• hide-from datum tot wanneer zichtbaar
• last-modified laatste wijziging, dit is zichtbaar in de sitemap.xml

Voorbeeld:

"show-from": "2026-01-13 00:00:00",
"hide-from": "2026-05-14 00:00:00",
"last-modified": "2026-04-10 00:00:00",

3. Koppeling met tags

Items worden gekoppeld aan tags via het veld:

"tags": [1, 3, 5]

Dit zijn de id-waarden uit de tags-structuur.

4. Fields (flexibele contentvelden)

Het fields-object bevat alle vrij definieerbare velden die in de frontend gebruikt worden.

Voorbeeld:

"fields": {
  "item-heading": {
    "value": {
      "nl": "Item 1",
      "en": "Item 1"
    }
  }
}

Een field kan bestaan uit:

• value: de daadwerkelijke waarde (meertalig mogelijk)
• attrs: extra attributen, bijvoorbeeld bij buttons

Button

"bekijk-button": {
  "value": {
    "nl": "Lees meer",
    "en": "Read more"
  },
  "attrs": {
    "href": {
      "nl": "https://www.example.com/",
      "en": "https://www.example.com/"
    },
    "target": {
      "nl": "_blank",
      "en": "_blank"
    }
  }
}

Galerij

"gallerij": [
    "<img src=\"https:\/\/www.example.com\/files\/afbeelding-1.jpg\" alt=\"afbeelding 1\">",
    "<img src=\"https:\/\/www.example.io\/files\/afbeelding-2.jpeg\" alt=\"afbeelding 2\">"
]

5. Meertaligheid

Alles wat je in het systeen in meerdere talen kunt invoeren, kun je ook verwerken in het JSON bestand.

"heading": {
    "nl": "Dit is mijn heading",
    "en": "This is my heading"
}

6. Redirects

Met 301-redirect kunnen oude URL’s worden doorgestuurd, dit kunnen er 1 of meerdere per item zijn:

"301-redirect": {
    "nl": [
        "\/nieuws\/oude-url-1\/",
        "\/nieuws\/oude-url-2/"
    ],
    "en": [
        "\/news\/old-url\/"
    ]
}

7. Praktische tips

• Probeer het JSON bestand zo klein mogelijk te houden.
• Aanpassingen in de JSON zijn direct zichtbaar op de website, er hoeft niet gepubliceerd te worden.
• Gebruik escaping, dit betekent dat speciale tekens in een string worden "geëscaped" (voorzien van een backslash ) zodat ze correct geïnterpreteerd worden.
• Zorg dat id-velden van tags uniek zijn, evenals de slug en nano-id's.
• Regel caching bij de bron, bijvoorbeeld door de JSON eens per uur te overschrijven.

Conclusie

Met een extern JSON-bestand kun je flexibel content beheren, filteren en presenteren binnen je website. Door de duidelijke scheiding tussen tags en items en de ondersteuning voor meertaligheid en SEO is dit een krachtige manier om dynamische content aan te sturen.