Web Content Structures with Data Engine

Beginning with Liferay 7.4, web content structures were migrated from using Dynamic Data Mapping (DDM) to Data Engine (DE) as the backend framework for building forms.

The Data Engine framework brings new changes and enhancements to web content structures.

New and Improved Field Types

Field types have been added and improved as part of the move to Data Engine:

• The Select from List field’s options can be ordered alphabetically (use the advanced settings of the Select from List field).
• Configure a Numeric field as an integer or decimal field.
• The Grid field is a new field type in web content and documents and media. See Forms Field Type Reference for more information.
• The HTML field was replaced by the Rich Text field, which includes a convenient toolbar.

Warning

Boolean field versus Multiple Selection field: Data Engine did not initially include a Boolean field. Instead, Boolean fields in upgraded structures were migrated to use the Data Engine’s Multiple Selection field, using the same label and just one option. Some issues can arise from this, for example if templates were built on structures with Boolean fields. In Liferay 7.4 Update/GA 23, the Boolean field type is added to Data Engine. Upgraded structures after Update 23 successfully convert 7.3 DDM Boolean fields to 7.4 DE Boolean fields in web content structures. If your installation was upgraded before this change, you must manually change these single-option Multiple Selection fields to Boolean fields by editing the affected structures.

Changes in Rich Text Field Behavior

As part of the migration to the Data Engine framework, the Rich Text field in web content structures has undergone significant changes. The new Rich Text field uses CKEditor as the default WYSIWYG editor, replacing the previous Dynamic Data Mapping (DDM) Rich Text field.

Beginning with Liferay DXP 2024.Q1+/Portal GA112+, you can customize CKEditor’s configuration using client extensions offering flexibility to tailor the editor to your needs.

Child Structures are Replaced by Structure Fieldsets

Structures backed by DDM could include child structures that inherited all the parent’s fields and settings. This relationship no longer exists because you can now create fieldsets, with which you can create reusable fieldsets for your structures. Fieldsets improve the editing experience since you can see what the structure looks like as you edit.

Warning

A fieldset is reusable across multiple structures. Editing it within a single structure causes changes to all the structures at once.

If a fieldset or structure is being used in web content, editing produces a warning to users:

To work with fieldsets,

1. Go to the Site Menu () and navigate to Content and Data → Web Content.

2. Select the Structures tab.

3. Click New to create a new structure.

4. In the web content structure form builder view (), click the Fieldsets tab.

5. Click Create New Fieldset. Name the fieldset.

6. Add and configure its fields. Click Save.

When you begin creating a new structure, any existing fieldset or structure can be selected in the Fieldsets tab. The basic web content structure is included as an out-of-the-box fieldset.

Structure Definition Source Changes

Structures in DE are represented by JSON (it was XML in DDM). Rather than editing code in the web content structures UI, you can now import and export the structure definition to work with the structure’s source JSON locally.

Warning

Be careful working with the JSON structure source as it can be more complicated than it appears at first glance. For example, when adding a field to the structure, you must update both the dataDefinitionFields array and the defaultDataLayout element.

In Liferay DXP 2025.Q1+/Portal GA132+, web content structures are exported with an internally generated external reference code (ERC). When imported into a new system or environment, entities referencing the structure by its ERC continue to function without manual updates.

Exporting a Structure’s JSON

1. Go to the Site Menu () and navigate to Content and Data → Web Content.

2. Click the Structures tab.

3. If there’s no existing structure, create one and save it.

4. In the main structures list view, open the structure’s Actions menu () and click Export as JSON.

Importing a Structure’s JSON to Overwrite an Existing Structure

To overwrite an existing structure’s JSON,

1. Go to the Site Menu () and navigate to Content and Data → Web Content.

2. Click the Structures tab.

3. If there’s no existing structure, create one and save it.

4. In the main structures list view, open the structure’s Actions menu () and click Import and Override.

5. Upload the JSON file.

Importing a Structure’s JSON to Create a New Structure

To import a new structure,

1. Go to the Site Menu () and navigate to Content and Data → Web Content.

2. Click the Structures tab.

3. Open the Options menu () for web content in the upper right corner of the screen.

4. Click Import Structure.

   

Flexible Structure Layout

Previously, structure fields could be ordered on the form and nested to create a hierarchical view of the form. The Data Engine representation of the structure adds the ability to define columns.

Add two form fields next to each other in the structure builder and drag the edge of a field to resize the columns.

In addition to columns, use field groups to lock a subset of the structure’s fields together for easy management. Create a field group by dropping a field on top of another field.

Setting the Web Content Structure Key

Warning

You can set the structure key manually when creating a new structure (as documented below) or when importing JSON as a new structure. You cannot update an existing structure’s key, even when importing and overwriting an existing structure.

1. Open the Global Menu () and go to the Control Panel tab.

2. To configure at the system level, go to Configuration → System Settings → Web Content (under Content and Data).

3. Liferay DXP 2024.Q4+/Portal GA129+ To configure at the instance level, go to Configuration → Instance Settings → Web Content (under Content and Data).

4. Click Administration. Uncheck Autogenerate Structure Key and click Update.

   For Liferay DXP 2024.Q4+/Portal GA129+, click Web Content under Virtual Instance Scope. Uncheck Autogenerate Structure Key and click Update.

   Tip

   To apply the same configuration to web content templates, uncheck Autogenerate Templates Key.

5. Go to the Site Menu () and navigate to Content and Data → Web Content. Open the Structures tab and add a new structure.

6. Add a field and name the structure. To set the structure key manually, open the Properties sidebar by clicking the configuration icon ().

7. Edit the Structure Key field, adding your custom value (e.g., MY_STRUCTURE_KEY).

8. Save the structure.

With the new Data Engine-backed structures, the export process strips the structure key out of the JSON. This means that importing the definition (for example, into a new site) generates a new structure key. If you wish to keep the structure key across an export-import process or perhaps provide a new custom key, you must edit the exported JSON.

To add a custom structure key to the exported JSON,

1. Open the exported JSON file (e.g., Structure_my structure_42153_20220721144913685.json).

2. Add a "dataDefinitionKey" element before the "dataDefinitionField" element:

   {
      "availableLanguageIds": ["en_US"],
      "contentType": "journal",
      "dataDefinitionKey": "MY_STRUCTURE_KEY",
      "dataDefinitionFields": [{"..."}]
   }
   

3. Import the structure definition file and verify that the key was imported by checking in the Properties tab.

   

Developer Considerations: Breaking Changes in Headless API Responses

The migration to the Data Engine framework introduced breaking changes to the structured-contents endpoint in the Headless API:

• Nested Fields: Responses now use a new FieldSet type to group nested fields, adding a layer to the response structure. Applications must refactor logic for parsing and handling these nested fields.

• Select Field Data Format: The data attribute for select fields has changed, affecting how select field values are retrieved and processed. Applications relying on the previous format need updates to ensure compatibility.

Related Topics

• Web Content Structures
• Creating Web Content Structures