Custom Fields in Joomla

1. De basis

1.1 Wat is een Custom Field?

Een Custom Field is een extra invoerveld, naast titel en inhoud, dat je aan een Joomla-item kunt koppelen. Elk veld heeft een type (tekst, lijst, afbeelding, datum enzovoort), een naam, een label en een kleine set configuratieopties.

Je kunt Custom Fields koppelen aan:

• Artikelen (com_content.article)
• Categorieën (com_content.categories)
• Contacten (com_contact.contact)
• Gebruikers (com_users.user)
• Tags (com_tags.tag)
• Extensies van derden die ondersteuning bieden

De context-string (component.view) koppelt een veld aan zijn doel. Dezelfde field engine stuurt al deze doelen aan.

1.2 Welk probleem lossen ze op?

Voor Custom Fields hadden editors drie opties om extra gegevens aan een artikel toe te voegen:

• Een eigen component bouwen.
• HTML verbergen in de artikeltekst.
• Een third-party content construction kit (CCK) installeren zoals K2, Seblod of Fabrik.

Sinds Joomla 3.7 levert het CMS dit standaard mee. Er is geen extra extensie nodig.

Zonder Custom Fields hebben editors de neiging om:

• Alles in de artikeltekst te proppen.
• De introtekst verkeerd te gebruiken.
• Te vertrouwen op copy-paste templates.
• Verplichte informatie te vergeten.
• Inconsistente content te produceren.

Met Custom Fields krijg je gestructureerde data, voorspelbare layouts, validatie, formulieren per categorie en rendering zonder code.

3. De 18 standaard veldtypes in Joomla 6

Joomla 6 bevat 18 standaard veldtypes, waaronder twee nieuwe: Number en Note. Elk type is een plugin onder plugins/fields/.

3.1 Basisinvoer

3.2 Keuzevelden

3.3 Mediavelden

Het Media-veld gebruikt de Media Manager-modal van Joomla 6, ondersteunt submappen en slaat een padstring op.

3.4 Relationele velden

3.5 Numerieke velden

Gebruik Number in plaats van Integer wanneer decimalen belangrijk zijn. Voor Joomla 6 moest je dit nabootsen met een Text-veld plus een filter.

3.6 Datum, kleur en URL

3.7 Helper- en structuurvelden

Het Note-veld is puur bedoeld als instructie. Het slaat geen waarde op. Het bestaat om editors te helpen, niet om gegevens vast te leggen.

Het Subform-veld is het werkpaard voor situaties waarin "één artikel meerdere items van iets bevat". De waarden worden opgeslagen als JSON, waar we later op terugkomen.

3.8 Het SQL-veld

Het SQL-veld toont een dropdown gevuld met een databasequery die je zelf schrijft. Een typische query ziet er zo uit:

SELECT id AS value, title AS text
  FROM `#__content`
 WHERE catid IN (8) AND state = 1
 ORDER BY title ASC;

Het SQL-veld is krachtig maar risicovol:

• De query draait met siterechten bij elke formulierlading.
• Alleen Super Users mogen SQL-velden aanmaken.
• Bouw de query nooit op basis van ongefilterde gebruikersinvoer.

Als je alleen een eenvoudige lookup nodig hebt, gebruik dan liever een normaal List-veld.

3.9 Overzicht in één oogopslag

5. Custom Fields renderen

5.1 Automatische weergave

De optie Automatic Display plaatst de gerenderde output op één van vier posities:

• After Title: tussen de titel en de introtekst.
• Before Display Text: boven de artikelinhoud.
• After Display Text: onder de artikelinhoud.
• Do not automatically display: zelf renderen.

Een volledige Field Group wordt samen weergegeven als één blok, in de ingestelde volgorde.

5.2 Handmatige plaatsing met shortcodes

Binnen de artikeltekst kun je eenvoudige shortcodes gebruiken:

            → rendert veld-id 5 (label + waarde)
       → rendert alle velden in veldgroep-id 2

Je kunt gewone tekst combineren met veldoutput:

Spreker: 
Datum: 

5.3 Layout overrides

Field rendering gebruikt layouts onder:

layouts/com_fields/
   render.php          (wrapper)
   field/
     render.php        (enkele veldrij)
     list.php          (lijstveldtype)
     media.php
     subform.php
     ...

Override ze in je template:

templates/your_template/html/layouts/com_fields/field/render.php

Voor één specifiek veldtype override je het bestand met de naam van dat type, bijvoorbeeld media.php. Voor één specifiek benoemd veld gebruik je:

render-<fieldname>.php

5.4 Waar de waarden vandaan komen

Wanneer Joomla een artikel laadt, gebeurt het volgende:

1. Leest #__fields_values voor dat item-id.
2. Voegt #__fields samen voor de metadata.
3. Filtert op categorietoewijzing.
4. Filtert op toegangsniveau en permissies.
5. Rendert de output via de layoutketen.

7. Het Subform-veld

7.1 Waarom een Subform gebruiken?

Gebruik een Subform wanneer één item op een gestructureerde manier meerdere items van iets bevat:

• Sessies in een conferentieartikel.
• Sprekers bij een evenement.
• Downloads op een productpagina.
• FAQ-items in een helpartikel.

Elke rij in een Subform is zijn eigen mini-formulier, met eigen onderliggende velden.

7.2 Hoe bouw je er één?

1. Maak eerst de onderliggende velden aan (Text, URL, Image enzovoort).
2. Maak een Subform-veld aan.
3. Kies op het tabblad Options de onderliggende velden. Zet Repeatable op Yes en definieer minimum- en maximumrijen.
4. Wijs het Subform toe aan de juiste categorieën.

7.3 Wat wordt opgeslagen?

De waarde van een Subform wordt opgeslagen als JSON in #__fields_values.value:

[
  {"speaker_name": "Ada", "speaker_role": "Keynote"},
  {"speaker_name": "Tim", "speaker_role": "Workshop"}
]

Deze JSON stuurt zowel de editorinterface als de gerenderde output aan.

7.4 Een Subform renderen

Het Subform heeft zijn eigen layoutbestand:

layouts/com_fields/field/subform.php

Override dit bestand wanneer je volledige controle nodig hebt over de loop, de markup, de CSS-klassen en de layout per rij.

9. Onder de motorkap (developer view)

9.1 De vier databasetabellen

Custom Fields worden opgeslagen in vier standaardtabellen:

#__fields              velddefinities (name, type, params, ...)
#__fields_groups       definities van veldgroepen
#__fields_values       waarden per item (item_id, field_id, value)
#__fields_categories   koppelingen tussen velden en categorieën

Een value kan gewone tekst zijn, JSON (voor een Subform) of elke string die het veldtype kiest.

9.2 Belangrijke kolommen in #__fields

id
title
name           (machinenaam, gebruikt in )
type           (text, list, media, subform, ...)
context        (com_content.article, com_users.user, ...)
group_id
state          (1 gepubliceerd, 0 gedepubliceerd)
access
language
fieldparams    (JSON: type-specifieke opties)
params         (JSON: weergave en gedrag)

9.3 Pluginarchitectuur

Custom Fields zijn plugins. Elk veldtype leeft in zijn eigen map:

plugins/fields/<type>/

De core bevat onder andere: calendar, checkboxes, color, editor, imagelist, integer, list, media, note, number, radio, sql, subform, text, textarea, url, user en usergrouplist.

Een field-type plugin definieert:

• Hoe de invoer in het formulier wordt weergegeven (formulier-XML).
• Hoe de waarde op de frontend wordt weergegeven.
• Optionele validatie.
• Optionele onSave- en onPrepare-logica.

9.4 Plugin-events

Dit zijn de uitbreidingspunten voor je eigen custom field-type:

10. Veelgemaakte fouten en valkuilen

10.1 Het veldtype wijzigen nadat er data bestaat

De value-kolom is één enkele string. Overschakelen van list naar subform nadat editors al waarden hebben ingevuld leidt meestal tot verouderde of onleesbare data.

Kies het type zorgvuldig vanaf dag één. Als je het toch moet wijzigen, exporteer dan eerst de waarden, wis ze en importeer ze opnieuw.

10.2 Vergeten categorieën toe te wijzen

Een veld zonder toegewezen categorieën verschijnt bij geen enkel item. "All" is de veilige standaard. Je kunt het later altijd beperken.

10.3 SQL-velden en beveiliging

Het SQL-veld voert ruwe SQL uit bij elke formulierlading:

• Alleen Super Users kunnen SQL-velden aanmaken.
• Bouw queries nooit op basis van ongefilterde gebruikersinvoer.
• Gebruik liever een List-veld met handmatige lookup of een eigen plugin-type.

10.4 Kwetsbare shortcodes

De shortcode verwijst naar het veld-id, niet naar de naam. Wanneer je een veld tussen websites verplaatst, verandert het id en breekt de shortcode.

Voor draagbare content gebruik je beter in combinatie met automatische plaatsing.

10.5 Over-engineering

Een Custom Field is niet altijd de juiste oplossing:

• Een eenmalige tekstregel hoort gewoon in de artikeltekst thuis.
• Veel velden, veel rijen en veel relaties zijn een teken dat je een echte custom component nodig hebt.

10.6 Slordige machinamen

Het veld name is de machine-identificatie. Het verschijnt in overrides, shortcodes en de API. Behandel het als een code-identificatie.

Goed:

event_date
speaker_name
product_price

Vermijd:

Field1
TestField
my new field

Gebruik kleine letters, underscores als scheidingstekens en betekenisvolle namen. Zodra een veld in gebruik is, breekt hernoemen overrides en API-consumenten.

10.7 Andere valkuilen

• Meertalige websites: de taal van het veld moet overeenkomen met de taal van het item, of ingesteld staan op "All".
• Verplichte velden op frontendformulieren: worden alleen afgedwongen als het frontendformulier ze ondersteunt.
• Caching: agressieve caches kunnen verouderde veldwaarden tonen na wijzigingen.
• Verwarring rond permissies: het weigeren van "Edit Custom Field Value" op componentniveau blokkeert alle onderliggende editors.

12. Best practices en snelle referentie

Als je maar een paar dingen uit dit artikel onthoudt, laat het dan deze zijn:

• Plan je velden en veldgroepen voordat je content gaat aanmaken.
• Kies vanaf dag één het juiste type. Later wijzigen is pijnlijk.
• Gebruik duidelijke machinamen zoals event_date, nooit Field1.
• Groepeer gerelateerde velden in Field Groups voor een nette editorervaring.
• Gebruik het Number-veld (nieuw in Joomla 6) voor prijzen en percentages.
• Gebruik het Note-veld (nieuw in Joomla 6) om editors binnen het formulier te begeleiden.
• Gebruik Subforms voor data waarbij "één item meerdere items van iets bevat".
• Stel ACL alleen op veldniveau in wanneer dat nodig is. Gebruik overerving waar mogelijk.
• Override layouts onder layouts/com_fields/field/ voor volledige controle.

Cheat Sheet

CREATE FIELD     Content → Fields → New
CREATE GROUP     Content → Field Groups → New
ASSIGN           Field → Assigned Categories tab
DISPLAY          Field → Automatic Display setting
INLINE            of  in de inhoud
OVERRIDE         templates/{tpl}/html/layouts/com_fields/...
TYPE OVERRIDE    render-<fieldname>.php voor één veld
USERS            Users → Manage → Fields
CONTACTS         Components → Contacts → Fields
CATEGORIES       Content → Categories → Fields
TAGS             Components → Tags → Fields
CORE TYPES       18 in Joomla 6 (Number + Note zijn nieuw)
SUBFORM          Herhalende data, opgeslagen als JSON
SQL FIELD        Alleen Super User, voorzichtig gebruiken
API              FieldsHelper::getFields('com_content.article', $item)
HEADLESS         /api/index.php/v1/content/articles/N → fields[]
TABLES           #__fields / _groups / _values / _categories