Hoe custom DDM veldtypes maken in Liferay 7.x

De DDM-modules in Liferay uitbreiden met aangepaste veldtypes is niet zo eenvoudig. Deze blogpost is het resultaat van onze pogingen om het te doen. Het eerste deel geeft een overzicht van wat DDM eigenlijk betekent en waar je het gebruikt. Daarna laten we een voorbeeld zien van een flexibel custom DDM veldtype dat we hebben gemaakt. Tot slot geeft het laatste deel van deze blog je wat aanwijzingen over hoe je zelf aangepaste DDM veldtypes kunt maken.

DDM... wat is DDM?

DDM staat voor Dynamic Data Mapping, een set modules die verschillende typen velden definieert die worden gebruikt om samen te stellen:

• Web content structuren voor het maken van web content artikelen.
• Gegevensdefinities voor het maken van dynamische gegevenslijstrecords.
• Metadata sets voor het maken van documenten gebaseerd op document types.

Liferay wordt gebundeld met een steeds groter wordende set out-of-the-box DDM veldtypes. Op dit moment (Liferay 7.1 is net uitgebracht) zijn de volgende veldtypen beschikbaar:

Is het ooit genoeg?

Voor basisbehoeften op het gebied van contentbeheer is de standaardset DDM-veldtypen meestal voldoende. Er zijn echter zeker use cases waarbij je aangepaste veldtypes moet maken:

• Je wilt de opties van een drop-downveld dynamisch vullen vanuit het antwoord van een REST-eindpunt.
• Je wilt een veld dat kan verwijzen naar een gebruiker, een groep of een andere entiteit in Liferay.
• Je wilt een tekstveld met een zeer specifieke validatie, bijvoorbeeld e-mailadres, URL of telefoonnummer validatie.

In dit artikel zullen we onderzoeken hoe u dergelijke aangepaste velden kunt maken. Als voorbeeld nemen we de eerste use case en proberen we een veldtype te maken dat de respons van een REST endpoint als mogelijke waarden van een vervolgkeuzelijst neemt.

Een nieuw veldtype is geboren: REST Select

Met het standaard Select-veld in Liferay kunnen auteurs van inhoud een waarde kiezen uit een vooraf gedefinieerde lijst met mogelijke waarden voor een artikel. Dit is prima voor eenvoudige doeleinden, maar wat als je deze vervolgkeuzelijst dynamisch wilt vullen met waarden van een extern platform? Of als de waarden in de lijst afhankelijk zijn van de gebruiker die erom vraagt?

Maak kennis met het gloednieuwe REST Select-veld. Met dit dropdown-veld kun je een REST-eindpunt configurerenen de JSON-velden in het antwoordtoewijzen aan de labels en waarden van de mogelijke opties.

De module installeren

Voer de volgende handelingen uit om de module te installeren in je Liferay installatie:

1. Kloon https://github.com/limburgie/com.liferay.dynamic.data.mapping.field.extender en check de 7.x/field/ddm-rest-select branch.
2. Bouw het project met Maven door mvn clean package uit te voeren.
3. Verplaats de resulterende JAR (je kunt het vinden in de doelmap) naar de deploy map van Liferay.

Definieer het veld in een structuur

1. Maak een nieuwe web content structuur.
   (Merk op dat je in plaats daarvan ook een dynamische gegevensdefinitie of een metadataset kunt maken. Voor testdoeleinden is het echter eenvoudiger om te beginnen met de bekende webcontentstructuur).
2. Sleep het veldtype "REST Select" naar de structuurdefinitie.
   
3. Configureer het eindpunt en de optietoewijzingen van het veld door het veld te selecteren
   

Naast de standaardattributen zoals "Field Label" en "Required", zijn er 3 extra attributen die je moet configureren. Het eerste attribuut moet je vullen met de URL van een REST endpoint. Dit moet een eindpunt zijn dat een lijst met JSON-objecten retourneert. Bijvoorbeeld het eindpunt http://localhost:8080/api/jsonws/country/get-countries (een ingebouwd eindpunt in Liferay) retourneert de volgende output:

Met de twee resterende attributen configureer je wat er respectievelijk in het label en de waarde van de HTML <option>-elementen moet komen. Als je in dit geval bijvoorbeeld het JSON-attribuut "nameCurrentValue" kiest voor het label van de optie en het JSON-attribuut "a3" voor de waarde van de optie, dan levert dat de volgende HTML op:

Een nieuw artikel maken met behulp van de structuur

Als je een nieuw webcontentartikel maakt op basis van de structuur die je zojuist hebt gemaakt, kun je een land selecteren uit de dynamisch geladen vervolgkeuzelijst!

Cool, nu wil ik mijn eigen aangepaste DDM veldtype maken! Dus... hoe?

In dit deel van de blog onderzoeken we hoe Liferay is uitgebreid om het nieuwe REST Select veld te ondersteunen. Hopelijk geeft dit je genoeg inzicht om aan de slag te gaan met je eigen custom DDM veldtype!

Disclaimer

Het bleek een hele reis te zijn om nieuwe DDM velden te maken in Liferay, zelfs in 7.x. Je zou verwachten dat elk veldtype is gedefinieerd in zijn eigen OSGi module, maar de jammerlijke waarheid is dat de definitie en rendering van deze velden verspreid is over verschillende Liferay modules in zowel client-side als server-side code. Dus het resultaat is op zijn zachtst gezegd nogal lastig.

Overweeg deze oplossing alleen als het echt niet anders kan!!!

Met dat gezegd hebbende, ga door met het lezen van dit artikel.

De code

Het startpunt is https://github.com/limburgie/com.liferay.dynamic.data.mapping.field.extender. Deze repository biedt een skeletproject dat kan worden uitgebreid om nieuwe DDM veldtypen te ondersteunen. Elk deel dat moet worden uitgebreid of geïmplementeerd is gemarkeerd met een //TODO commentaar. Je kunt een diff doen van deze hoofdtak met de 7.x/field/ddm-rest-select tak om de verschillende wijzigingen te zien om je eigen implementatie te maken.

Aanbevelingen

• Zorg ervoor dat je ALLE to-dos configureert. Vergeet er slechts één te implementeren en het zal niet werken, en Liferay zal u geen aanwijzing geven.
• Zorg ervoor dat je Liferay start in developer mode -Dexternal-properties=portal-developer.properties met setenv.sh (Unix) of setenv.bat (Windows).
• Als je wijzigingen niet lijken te worden gereflecteerd, verwijder dan de module uit de Gogo shell en installeer deze vervolgens opnieuw om de resterende status te wissen.

Conclusie

Hoewel het een echte uitdaging was om een aangepast DDM veld te maken, IS het mogelijk. Als je genoeg flexibiliteit in je veld injecteert, kan het zelfs meerdere doelen dienen. Stuur me je feedback over hoe jij het anders zou doen of welke veldtypes je op dit moment mist in Liferay 7.x.

Bedankt voor het lezen!