npm package: @liferay-editor-custom-fields/framework
Description: An framework to create custom fields for Liferay fragments and structured web content
Author: lbehar@xtivia.com
Latest version: 26.0.2

# Liferay Custom Fields Framework

The engine behind Liferay Editor Custom Fields. 

You only need this if you are creating a new Liferay Editor Custom Fields package, otherwise it is provided as a dependency on existing ones.

## Supported Liferay Versions
This app supports DXP versions in their premium support phase at the time of this release.
- 2025 Q4
- 2025 Q3
- 2025 Q2
- 2025 Q1
- 2024 Q1
- 7.4

If you need compatibility for older DXP releases, you can create a legacy version with a year that supports the release, and submit a PR.

## Before You Start

Any client extension using this framework should not run on a production or pre-prod staging environment. It is only intended for the fragment and web content editors. Any JS that will end up on the page should be elsewhere, either in a separate client extension or in the fragment/web content template.

If you are creating/appending DOM elements, make sure that you check for an existing element to avoid infinite MutationObserver loops.

## Getting Started

- Download the boilerplate starter at https://github.com/lbeharxtivia/liferay-editor-custom-fields-sample
- See below for available events and helper functions

## Events

Use Liferay.on to subscribe to these events:

- `EditorCustomFields_WebContentFields_OnLoad` - Fires when web content field DOM is loaded.
- `EditorCustomFields_FragmenConfig_OnLoad` - Fires when a new Fragment config is loaded on the right pane of a page editor.
- `EditorCustomFields_Image_OnChange` - Fires when an lfr-editable image or Web Content image is changed.

## Helper functions

The helper functions below are available for import in any file. For example, to use the getFieldByLabel helper you would use `import { getFieldByLabel } from "@liferay-editor-custom-fields/framework";`

- `clickFragmentConfigTab(label:string)` - Clicks a tab on the Fragment Configuration screen
- `debounce(callback:function, wait:number)` - A simple callback function
- `fragmentConfigLoadingStart()` - Create a overlay with a loading spinner over the active fragment and reduce the opacity of the config panel so we can programatically manipulate it without flicker
- `fragmentConfigLoadingEnd()` - Remove the overlays
- `getContentImageInput(label:string)` - Gets the metadata input field associated with the web content image.
- `getElementByLabel(label:string)` - Gets an element (not an input) by innerText
- `getFieldByLabel(label:string)` - Uses Xpath to get an input field by its label. Usually used to append a GUI element.
- `getPreviewImage()` - Gets the preview Image
- `setReactDomInputValue({fieldEl:element,value:string})` - Sets React DOM input value and triggers an autosave on fragment config
- `wait(ms)` - (Use `await wait()`) - an async function that pauses the process for a bit. Good for multiple actions on the same input
- `waitForElement({ parentEl: Element, label: string, searchQuerySelector?: string })` - Starts a Mutation Observer that queries a parent element for a specified selector/innertext combo. Destroys the observer and resolves the promise when it finds it. Times out after 5 seconds.

## License

MIT Licensed. Copyright (c) Xtivia 2026.