Strapi plugin page-builder

A quick description of page-builder.

Werking van de plugin

Voeg de plugin aan de plugin.ts toe

'page-builder': {
  enabled: true,
  config: {
    modules: [
      'modules.header',
      'modules.cta',
      ...
    ]
  }
}

In de modules array voeg je alle modules toe die beschikbaar moeten zijn op een pagina. Deze worden bij het opstarten van de server automatisch toegevoegd aan Page en Template.

De collectiontypes Page, Template en PageType worden aangemaakt of bijgewerkt op het moment van opstarten van de server. Het kan zijn dat de server een keer crasht, start deze dan even opnieuw op.

Page Types

Maak voor elke pagina type een Page Type aan. Deze kan, maar hoeft niet, gekoppeld worden aan een collection type. Je moet altijd een UID invoeren, als je wenst geen koppeling te maken met een collection type, vul hier alsnog iets in. Het kan zijn dat dit deel van de plugin nog niet werkt, hier is nog niet mee getest. hasPage moet toegevoegd worden aan de collectiontype. Dit komt doordat er gefilterd moet kunnen worden middels graphql. Er is een custom manier gebouwd om ervoor te zorgen dat pages gefilterd kan worden.

Voor elk collection type die een page type is, moet deze properties toegevoegd worden:

"page": {
  "type": "relation",
  "relation": "morphMany",
  "target": "api::page.page",
  "morphBy": "collectionTypeData"
},
"hasPage": {
  "pluginOptions": {
    "i18n": {
      "localized": true
    }
  }
  "type": "boolean",
  "default": false
}

Zodra dit goed is ingesteld, kan je via deze collectie types direct een pagina aanmaken.

Notitie: hasPage wordt gebruikt om aan te tonen dan een collection type item een published pagina heeft.

Page

Op een page kan je in de Edit View een page type selecteren. Op basis daarvan wordt er een template geselecteerd (indien gekozen in een page type) en kan je zoeken in verschillende entiteiten binnen die page type. Deze kan je koppelen aan een pagina.

Template

Een template is niets anders dan een sjabloon die je eenmalig kan toevoegen op een pagina. Dit kan via een page type gaan maar kan ook zonder de page type. Een modal zal eerst nog vragen of je zeker bent van je keuze, alle modules zullen vervangen worden.

Platform

Om wijzigignen aan te brengen in een platform, moeten deze in de schema aangepast worden van de api. /src/api/platform/content-types/platform/schema.json

Voor elk collectiontype die je wil toevoegen aan het platform, moet deze relatie toegevoegd worden:

"platform": {
  "type": "relation",
  "relation": "oneToOne",
  "target": "api::platform.platform"
}

Een platform zit altijd aan een pagina gekoppeld. Deze moet handmatig in de pagina toegevoegd worden.

NPO Gebruiker

Omdat er voor verschillende pagina's ingelogd moet worden binnen NPO, moet de gebruiker aangepast worden. Omdat dit niet op alle sites mag komen, wordt er gekeken naar de config die mee gegeven wordt. Wanneer er in de config de customNPOUser mee gegeven wordt, worden de wijzigingen doorgevoerd voor de gebruiker.

			config: {
				customNPOUser: true
			}

Dit zorgt ervoor dat de gebruiker aangepast wordt en de controllers om te updaten en aan te maken zijn aangepast. Strapi verplicht je namelijk om een username aan te maken bij het registreren. Die zit hier nu niet meer bij.

Custom field: Filtered Select

Om het mogelijk te maken om andere relaties te leggen en daarbij te limiteren op het gekoppelde platform, is er een custom field gemaakt. Dit custom field vereist dat er een ander relatieveld bestaat (custom fields kunnen immers geen relaties zijn). Het veld is puur een FE filter voor de eindgebruiker.

Private content

Om private content toe te voegen aan het systeem, moet er bij de config van de plugin een property toegevoegd worden, privateContent.

		'page-builder': {
			enabled: true,
			resolve: './src/plugins/strapi-plugin-page-builder',
			config: {
				modules: ['modules.text', 'modules.featured-vacancies'],
				privateContent: true
			}
		},

Zodra deze aan staat, wordt er extra componenten ingeladen en worden er bepaalde functies aangemaakt om gebruikers te kunnen registreren en te laten inloggen.

Private modules

Wanneer private content aan staat, wordt ook de getPageByPath module private. Dit wordt gedaan om modules private te kunnen maken. Om de data op te kunnen halen van de page moet een header meegestuurd worden: "x-strapi-page-secret". Deze token wordt in de environment variabele gezet STRAPI_PAGE_SECRET

Vervolgens kun je private modules maken. Deze hebben wel een structuur nodig. Zo moet het component auth bevatten. Voorbeeld: authBodyText Op die manier weten we of de module authenticatie bevat. Vervolgens moeten de velden in de module een public en een private veld bevatten. Voorbeeld: publicBodyText en privateBodyText.

Binnen strapi kunnen we niet controleren of de public versie of private versie terug gestuurd moet worden. Dit komt doordat de resolvers van dynamic zones niet aangepast kunnen worden. Vandaar dat we de authenticatie op de server doen van de frontend.

Voorbeeld

Ik wil een lijst van vacature relaties selecteren. Deze vacatures moeten van hetzelfde platform zijn als het platform dat globaal is geselecteerd:

"vacatures": {
  "type": "relation",
  "relation": "oneToMany",
  "target": "api::vacancy.vacancy"
},
"vacaturesFiltered": {
  "pluginOptions": {
    "filteredSelect": {
      // Targets neighbouring field with selected name.
      "targetField": "vacatures",
      // (Default: undefined) Adds filters to the $and query for result filtering
      "customFilters": [{ "title": { "$contains": "Hoi" } }],
      // (Default: false). Disables result filtering by globally selected platform
      "disablePlatformFilter": boolean,
      // (Default: false) Hides id of the entity that is edited if it's the same as the targetField uid. So if this is enabled on a vacancy entity and also targets other vacancies, the current vacancy that is edited will not be shown.
      "hideSameEntity": boolean,
      // (Default: ['title']) Defines searchable fields
      "searchableFields": string[],
      // (Default: undefined) If set the field will show a subtitle with the value that results in following this path.
      "subTitlePath": string,
      // (Default: undefined)
      // Conditional filters add the posibility to who results based on values from other fields.
      // For now this only works for fields on the same level as the targetfield.
      // The value found will be replacing the '${value}' string.
      "conditionalFilters": {
        "targetField": string,
        "targetFieldKey": string,
        "filter": [{ "title": { "$contains": "${value}" } }]
      }[];
    }
  },
  "type": "customField",
  "customField": "plugin::page-builder.filtered-select"
},

Je ziet dat het vacatures veld nodig is voor het custom field om te "targeten". Het custom veld weet dankzij de optie targetField welke waarde hij waar moet zetten. In de admin is het belangrijk dat je het vacatures veld verbergt, zodat enkel de gefilterde variant zichtbaar is.

Daarnaast heb je de optie om customFilters toe te voegen. In het bovenstaande geval worden enkel resultaten getoond met "Hoi" als titel. De waarde moet een array van objecten zijn. De filtermogelijkheden kunnen in de Strapi documentatie gevonden worden. (Let wel, de filters zijn altijd AND)

Known bugs

• Na het ontkoppelen en opslaan van een collectie item op een pagina, staat deze nog als "Geselecteerd" in de dropdown.
• Sorteren op pages binnen een collectie type kan niet. Dus stel ik haal alle FAQ's op waarbij ik wil sorteren op een property op de page, kan dat niet.

Improvements

• Deze readme updaten en naar engels vertalen.
• Intl gebruiken voor de teksten.
• Filteren op Page in GraphQL binnen een collectiontype met een morph op een page kan niet. Strapi staat dit niet toe. Wellicht in de toekomst wel.
• Slug en path genereren op basis van de titel van het collection type waarvan je een pagina aanmaakt. Nu wordt deze leeggelaten. Dit moet zorgvuldig gebeuren, bij een bestaande slug wil je bijvoorbeeld een -2 toevoegen oid.
• Dit vorige punt geldt ook andersom, dus als je een entity koppelt vanuit een pagina. Als de titel en slug nog leeg zijn, vul die dan automatisch in.
• In het overzicht van een collectiontype moet duidelijk worden of en welke pagina er gekoppeld is. https://share.getcloudapp.com/BluzGYEd
• Bij Page Types moet je handmatig de collectiontype uid invoeren. Dit zou idealiter een select zijn van alle mogelijke collecion type uids. Ook moet dit een mogelijkheid bieden voor geen uid.