Blogs
This blog post is the result of an attempt to extend the DDM modules in Liferay with custom field types. First, we'll recap what DDM actually means and where it is used. After that, we'll showcase an example of a flexible custom DDM field type that we created. Finally, we'll give some pointers on how you can create custom DDM field types on your own.
Peter Mesotten
DDM... what's DDM?
DDM stands for Dynamic Data Mapping, a set of modules that define various types of fields that can be used to assemble:
- Web content structures for creating web content articles.
- Data definitions for creating dynamic data list records.
- Metadata sets for creating documents based on document types.
Liferay bundles with an ever expanding set of DDM field types out of the box. At the moment of speaking (Liferay 7.1 has just released), the following field types are available:
Is it ever enough?
For basic content management needs, the default set of DDM field types is usually sufficient. However, there certainly are use cases which would require you to create custom field types:
- You want to dynamically populate the options of a dropdown field from the response of a REST endpoint.
- You want to provide a field that can point to a user, a group or any other entity in Liferay.
- You want to have a text field with some very specific validation, e.g. email address, URL or phone number validation.
In this article, we will examine how to create such custom fields. As an example, we'll pick the first use case and try to create a field type which takes the response of a REST endpoint as the possible values of a dropdown list.
A new field type was born: REST Select
The default Select field in Liferay allows content authors to pick a value from a predefined list of possible values for an article. This is great for simple purposes, but what if you want to dynamically populate this dropdown list with values from an external platform? Or if the values that should be listed depend on the user that requests them?
Meet the brand new REST Select field. This dropdown field allows you to configure a REST endpoint and how to map the JSON fields in the response onto the labels and values of the possible options.
Install the module
Perform the following actions to install the module in your Liferay installation:
- Clone https://github.com/limburgie/com.liferay.dynamic.data.mapping.field.extender and checkout the 7.x/field/ddm-rest-select branch.
- Build the project using Maven by executing mvn clean package.
- Move the resulting JAR (you can find it in the target folder) into the deploy folder of Liferay.
Define the field in a structure
- Create a new web content structure.
- Drag the "REST Select" field type into the structure definition.
- Configure the field's endpoint and option mappings by selecting the field.
Apart from the default attributes like "Field Label" and "Required", notice there are 3 additional attributes to be configured. The first attribute should be filled with the URL of a REST endpoint. This should be an endpoint that returns a list of JSON objects. E.g. the endpoint http://localhost:8080/api/jsonws/country/get-countries (a built-in endpoint in Liferay) returns the following output:
With the two remaining attributes, you configure what should be respectively in the label and the value of the HTML <option> elements. E.g. in this case, if you pick the "nameCurrentValue" JSON attribute for the option label and the "a3" JSON attribute for the option value, this will produce the following HTML:
Create a new article using the structure
When creating a new web content article based on the structure you've just created, you're able to select a country from the dynamically loaded dropdown list!
Cool, now I want to create my own DDM field type! So... how?
In this part of the post, we'll explore how Liferay was extended to support the new REST Select field. Hopefully, this gives you enough insights to start working on your own custom DDM field type!
Disclaimer
It turned out to be quite a journey to create new DDM fields in Liferay, even in 7.x. You would expect that every field type is defined in its own OSGi module, but the woeful truth is that the definition and rendering of these fields is scattered throughout several Liferay modules in both client-side and server-side code. So the result is rather hacky to say the least.
Please only consider this solution if there is absolutely no other way!!
With that being said, do go on reading this article 
The code
The starting point is https://github.com/limburgie/com.liferay.dynamic.data.mapping.field.extender. This repository provides a skeleton project that can be extended to support new DDM field types. Each part that needs to be extended or implemented is marked with a //TODO comment. You can do a diff of this main branch with the 7.x/field/ddm-rest-select branch to see the different changes to provide your own implementation.
Recommendations
- Make sure that ALL todos are configured. Forgetting to implement only one of them and it will not work and Liferay will give you no clue.
- Make sure to start Liferay in developer mode
-Dexternal-properties=portal-developer.propertiesto setenv.sh (Unix) or setenv.bat (Windows). - If your changes don't seem to be reflected, uninstall the module from the Gogo shell and then reinstall it again to clear any remaining state.
Conclusion
While it was a real challenge to create a custom DDM field, it IS possible and if you inject enough flexibility in your field, it can serve multiple purposes. Please send me your feedback on how you would do things differently or what field types you are missing at the moment in Liferay 7.x.
Thanks for reading!
Related Assets...
More Blog Entries...
