0
# Liferay Dynamic Data Mapping API
1

2
The Liferay Dynamic Data Mapping (DDM) API provides comprehensive functionality for creating, managing, and processing dynamic forms, data structures, and templates within Liferay Portal. This OSGi bundle enables developers to build flexible form-based applications with support for complex field types, data validation, expression evaluation, template rendering, and external data integration.
3

4
## Package Information
5

6
- **Package Name**: com.liferay.dynamic.data.mapping.api
7
- **Package Type**: maven
8
- **Language**: Java (OSGi Bundle)
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.liferay</groupId>
13
    <artifactId>com.liferay.dynamic.data.mapping.api</artifactId>
14
    <version>35.2.1</version>
15
    <scope>provided</scope>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import com.liferay.dynamic.data.mapping.model.DDMStructure;
23
import com.liferay.dynamic.data.mapping.model.DDMTemplate;
24
import com.liferay.dynamic.data.mapping.model.DDMFormInstance;
25
import com.liferay.dynamic.data.mapping.model.DDMForm;
26
import com.liferay.dynamic.data.mapping.model.DDMFormLayout;
27
import com.liferay.dynamic.data.mapping.service.DDMStructureLocalService;
28
import com.liferay.dynamic.data.mapping.service.DDMTemplateLocalService;
29
import com.liferay.dynamic.data.mapping.service.DDMFormInstanceLocalService;
30
import com.liferay.dynamic.data.mapping.storage.DDMFormValues;
31
import com.liferay.dynamic.data.mapping.util.DDMFormFactory;
32
import com.liferay.dynamic.data.mapping.form.field.type.DDMFormFieldType;
33
```
34

35
## Basic Usage
36

37
```java
38
@Component
39
public class MyDDMService {
40
    
41
    @Reference
42
    private DDMStructureLocalService ddmStructureLocalService;
43
    
44
    @Reference 
45
    private DDMFormInstanceLocalService ddmFormInstanceLocalService;
46
    
47
    public DDMStructure createStructure(long groupId, String name, String definition) 
48
        throws PortalException {
49
        
50
        ServiceContext serviceContext = new ServiceContext();
51
        serviceContext.setScopeGroupId(groupId);
52
        
53
        Map<Locale, String> nameMap = new HashMap<>();
54
        nameMap.put(LocaleUtil.getDefault(), name);
55
        Map<Locale, String> descriptionMap = new HashMap<>();
56
        descriptionMap.put(LocaleUtil.getDefault(), name);
57
        
58
        return ddmStructureLocalService.addStructure(
59
            null, // externalReferenceCode
60
            0L, // userId
61
            groupId,
62
            0L, // parentStructureId
63
            PortalUtil.getClassNameId(DDMContent.class),
64
            null, // structureKey - auto-generated
65
            nameMap,
66
            descriptionMap,
67
            definition,
68
            "json", // storageType
69
            serviceContext
70
        );
71
    }
72
    
73
    public DDMFormInstance createFormInstance(long groupId, long structureId, 
74
        String formName) throws PortalException {
75
        
76
        DDMStructure structure = ddmStructureLocalService.getStructure(structureId);
77
        DDMForm ddmForm = structure.getDDMForm();
78
        
79
        ServiceContext serviceContext = new ServiceContext();
80
        serviceContext.setScopeGroupId(groupId);
81
        
82
        Map<Locale, String> nameMap = new HashMap<>();
83
        nameMap.put(LocaleUtil.getDefault(), formName);
84
        Map<Locale, String> descriptionMap = new HashMap<>();
85
        descriptionMap.put(LocaleUtil.getDefault(), formName);
86
        
87
        DDMFormValues settingsDDMFormValues = createDefaultSettings();
88
        
89
        return ddmFormInstanceLocalService.addFormInstance(
90
            0L, // userId
91
            groupId,
92
            structureId,
93
            nameMap,
94
            descriptionMap,
95
            settingsDDMFormValues,
96
            serviceContext
97
        );
98
    }
99
}
100
```
101

102
## Architecture
103

104
The DDM API is built around several key architectural components:
105

106
- **Model Layer**: Entity models representing structures, templates, forms, and data records
107
- **Service Layer**: Local and remote services providing CRUD operations and business logic
108
- **Storage Abstraction**: Pluggable storage backends for form data with JSON as the default
109
- **Expression Engine**: Rule evaluation system supporting complex conditional logic
110
- **Form Field Framework**: Extensible field type system with built-in and custom field types
111
- **Template Engine**: Template processing system supporting multiple template languages
112
- **Data Provider Framework**: External data source integration for dynamic field options
113
- **Security Layer**: Comprehensive permission system with fine-grained access control
114

115
## Capabilities
116

117
### Core Data Models & Services
118

119
Primary entity models and CRUD services for structures, templates, forms, and data records. Essential for all DDM operations.
120

121
```java { .api }
122
// Core models
123
interface DDMStructure extends DDMStructureModel, PersistedModel;
124
interface DDMTemplate extends DDMTemplateModel, PersistedModel;
125
interface DDMFormInstance extends DDMFormInstanceModel, PersistedModel;
126

127
// Core services
128
interface DDMStructureLocalService extends BaseLocalService;
129
interface DDMTemplateLocalService extends BaseLocalService;
130
interface DDMFormInstanceLocalService extends BaseLocalService;
131
```
132

133
[Models & Services](./models-services.md)
134

135
### Form Management Framework
136

137
Comprehensive form building, rendering, field types, validation, and lifecycle management capabilities.
138

139
```java { .api }
140
interface DDMFormRenderer {
141
    String render(DDMForm ddmForm, DDMFormLayout ddmFormLayout, 
142
        DDMFormRenderingContext ddmFormRenderingContext) throws DDMFormRenderingException;
143
    Map<String, Object> getDDMFormTemplateContext(DDMForm ddmForm, DDMFormLayout ddmFormLayout,
144
        DDMFormRenderingContext ddmFormRenderingContext) throws Exception;
145
}
146

147
interface DDMFormFieldType {
148
    String getName();
149
    Class<? extends DDMFormFieldTypeSettings> getDDMFormFieldTypeSettings();
150
    String getModuleName();
151
    String getESModule();
152
    boolean isCustomDDMFormFieldType();
153
}
154

155
interface DDMFormEvaluator {
156
    DDMFormEvaluatorEvaluateResponse evaluate(DDMFormEvaluatorEvaluateRequest request);
157
}
158
```
159

160
[Form Management](./form-management.md)
161

162
### Data Provider Framework
163

164
External data source integration for populating form field options dynamically from REST APIs, databases, and other sources.
165

166
```java { .api }
167
interface DDMDataProvider {
168
    DDMDataProviderResponse getData(DDMDataProviderRequest ddmDataProviderRequest) throws DDMDataProviderException;
169
    Class<?> getSettings();
170
}
171

172
class DDMDataProviderRequest {
173
    String getDDMDataProviderInstanceId();
174
    Map<String, String> getParameters();
175
}
176
```
177

178
[Data Providers](./data-providers.md)
179

180
### Expression Engine
181

182
Rule evaluation system with support for complex conditional expressions, calculations, and form field interactions.
183

184
```java { .api }
185
abstract class Expression {
186
    public abstract <T> T accept(ExpressionVisitor<T> expressionVisitor);
187
}
188

189
interface DDMExpression<T> {
190
    T evaluate() throws DDMExpressionException;
191
    Map<String, Object> getVariables();
192
    void setVariable(String name, Object value);
193
}
194

195
interface DDMExpressionFactory {
196
    <T> DDMExpression<T> createExpression(CreateExpressionRequest createExpressionRequest) throws DDMExpressionException;
197
}
198
```
199

200
[Expression Engine](./expressions.md)
201

202
### Storage & I/O Framework
203

204
Pluggable storage abstraction for form data with support for JSON storage, import/export operations, and custom storage adapters.
205

206
```java { .api }
207
interface DDMStorageAdapter {
208
    long create(DDMStorageAdapterSaveRequest request) throws StorageException;
209
    void deleteByClass(long ddmStructureId) throws StorageException;
210
    DDMStorageAdapterGetResponse get(DDMStorageAdapterGetRequest request) throws StorageException;
211
}
212
```
213

214
[Storage & I/O](./storage-io.md)
215

216
### Template Engine & Rendering
217

218
Template processing system supporting FreeMarker, Velocity, and custom template languages for form and content rendering.
219

220
```java { .api }
221
interface DDMTemplateManager {
222
    Map<String, Object> getAutocompleteVariables(HttpServletRequest httpServletRequest, 
223
        HttpServletResponse httpServletResponse, Language language) throws Exception;
224
    String[] getRestrictedVariables(Language language);
225
}
226
```
227

228
[Templates & Rendering](./templates.md)
229

230
### Security & Validation
231

232
Permission system, access control, data validation framework, and security policy enforcement.
233

234
```java { .api }
235
interface DDMPermissionSupport {
236
    String getResourceName(String className);
237
    boolean contains(PermissionChecker permissionChecker, String name, 
238
        long primaryKey, String actionId) throws PortalException;
239
}
240

241
interface DDMValidator {
242
    void validate(DDMValidatorValidateRequest request) throws DDMValidatorException;
243
}
244
```
245

246
[Security & Validation](./security-validation.md)
247

248
### Integration & Extensions
249

250
Info framework integration, WebDAV support, utilities, comparators, and extensibility APIs.
251

252
```java { .api }
253
interface DDMFormValuesInfoFieldValuesProvider<T> {
254
    InfoFieldValue<Object> getInfoFieldValue(T model, String fieldName, Locale locale);
255
}
256

257
interface DDMStructureInfoItemFieldSetProvider {
258
    InfoFieldSet getInfoFieldSet(String itemClassName, long itemClassPK, long structureId);
259
}
260
```
261

262
[Integration & Extensions](./integration-extensions.md)