@liferay-editor-custom-fields/framework 7.4.1

package/README.md

@@ -0,0 +1,34 @@
+# Liferay Custom Fields Framework
+
+The engine behind Liferay Custom Fields. You only need this if you are creating a Liferay Editor Custom Fields package. Otherwise you can just install the package.
+
+You can read more about how it works [Creating a Liferay global JS client extension with TypeScript and Webpack](https://xtivia.com/blog/creating-a-liferay-global-js-client-extension-with-typescript-and-webpack).
+
+## Getting Started
+
+ 
+
+
+## Events and Helpers
+
+The framework profides the Liferay events and exposed functions below to use in your implementation.
+
+### 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 children of Liferay.editorCustomFields
+- `debounce(callback:function, wait:number)` - A simple callback function
+- `getContentImageInput(label:string)` - Gets the metadata input field associated with the web content image.
+- `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
+
+## License
+
+MIT Licensed. Copyright (c) Xtivia 2026.

package/eslint.config.mjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+import eslint from "@eslint/js";
+import { defineConfig, globalIgnores } from "eslint/config";
+import tseslint from "typescript-eslint";
+
+export default defineConfig(
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  [globalIgnores(["**/*.js", "**/*.cjs", "**/*.mjs"])],
+);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@liferay-editor-custom-fields/framework",
+  "repository": "https://github.com/lbeharxtivia/liferay-editor-custom-fields-framework",
+  "author": "lbehar@xtivia.com",
+  "license": "MIT",
+  "description": "An framework to create custom fields for Liferay fragments and structured web content",
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "eslint-webpack-plugin": "^5.0.2",
+    "ts-loader": "9.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
+    "webpack": "5.90.1",
+    "webpack-cli": "5.1.4",
+    "webpack-dev-server": "4.15.1"
+  },
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "webpack",
+    "start": "webpack serve",
+    "watch": "tsc --watch"
+  },
+  "version": "7.4.1"
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+declare const Liferay;
+
+import { observeFragmentConfig, observeWebContentFields } from "./observers";
+import {
+  debounce,
+  getContentImageInput,
+  getFieldByLabel,
+  getPreviewImage,
+  setReactDomInputValue,
+} from "./util";
+
+const initFramework:()=>void = () => {
+  const startObservers = () => {
+    observeWebContentFields();
+    // Fragment element we are watching is loaded client-side, and AFAIK there is no event fired when client-side is loaded.
+    setTimeout(observeFragmentConfig, 500);
+  };
+  if (Liferay && !Liferay?.editorCustomFields) {
+    Liferay.editorCustomFields = {
+      debounce,
+      getFieldByLabel,
+      setReactDomInputValue,
+      getContentImageInput,
+      getPreviewImage,
+    };
+    Liferay.on("allPortletsReady", () => {
+      startObservers();
+    });
+    Liferay.on("endNavigate", () => {
+      startObservers();
+    });
+  }
+}
+export default initFramework;

package/src/messagingEvents/fireFragmentConfigOnLoad.ts

@@ -0,0 +1,2 @@
+declare const Liferay;
+export const fireFragmentConfigOnLoad = () => Liferay.fire('EditorCustomFields_FragmenConfig_OnLoad');

package/src/messagingEvents/fireImageOnChange.ts

@@ -0,0 +1,4 @@
+declare const Liferay;
+export const fireImageOnChange = () => {
+    Liferay.fire('EditorCustomFields_Image_OnChange');
+};

package/src/messagingEvents/fireWebContentFieldsOnLoad.ts

@@ -0,0 +1,2 @@
+declare const Liferay;
+export const fireWebContentFieldsOnLoad = () => Liferay.fire('EditorCustomFields_WebContentFields_OnLoad');

package/src/observers/index.ts

@@ -0,0 +1,4 @@
+import { observeFragmentConfig } from "./observeFragmentConfig";
+import { observeWebContentFields } from "./observeWebContentFields";
+
+export {observeFragmentConfig, observeWebContentFields};

package/src/observers/observeFragmentConfig.ts

@@ -0,0 +1,27 @@
+declare const Liferay;
+
+import { fireFragmentConfigOnLoad } from "../messagingEvents/fireFragmentConfigOnLoad";
+import { debounce } from "../util";
+
+import { observePreviewImage } from "./observePreviewImage";
+
+export const observeFragmentConfig = () => {
+    const sidePanelQuery = ".page-editor__item-configuration-sidebar";
+    const sidePanelEl: HTMLDivElement = document.querySelector(
+        sidePanelQuery
+    );
+
+    if (sidePanelEl) {
+        if (Liferay.editorCustomFields.fragmentObserver) {
+            Liferay.editorCustomFields.fragmentObserver.disconnect?.();
+        }
+        const debouncedAddButton = debounce(() => {
+            observePreviewImage('fragment');
+            fireFragmentConfigOnLoad();
+        }, 500);
+        Liferay.editorCustomFields.fragmentObserver = new MutationObserver(debouncedAddButton);
+        const observer = Liferay.editorCustomFields.fragmentObserver;
+        const config = { attributes: false, childList: true, subtree: false };
+        observer.observe(sidePanelEl, config);
+    }
+};

package/src/observers/observePreviewImage.ts

@@ -0,0 +1,22 @@
+declare const Liferay;
+
+import { fireImageOnChange } from "../messagingEvents/fireImageOnChange";
+import { ContentType } from "../types/ContentType.type";
+import { debounce, getContentImageInput, getPreviewImage } from "../util";
+
+export const observePreviewImage = (contentType: ContentType) => {
+    if(Liferay.editorCustomFields.imageObserver){
+        Liferay.editorCustomFields.imageObserver.disconnect?.();
+    }
+    // For when image changes
+    const elToObserve = contentType === 'fragment' ? getPreviewImage() : getContentImageInput();
+    if (contentType && elToObserve && !Liferay.editorCustomFields.imageObserver) {
+        const debouncedAddContentBlurhash = debounce(() => fireImageOnChange(), 500);
+        Liferay.editorCustomFields.imageObserver = new MutationObserver(debouncedAddContentBlurhash);
+        const observer = Liferay.editorCustomFields.imageObserver
+        const config = { attributes: true, childList: false, subtree: false };
+        observer.observe(elToObserve, config);
+    }
+    // For when image is already present on load
+    fireImageOnChange();
+}

package/src/observers/observeWebContentFields.ts

@@ -0,0 +1,24 @@
+declare const Liferay;
+
+import { fireWebContentFieldsOnLoad } from "../messagingEvents/fireWebContentFieldsOnLoad";
+import { debounce } from "../util";
+import { observePreviewImage } from "./observePreviewImage";
+
+export const observeWebContentFields = () => {
+    const fieldsContainerEl: HTMLDivElement = document.querySelector(
+        "#_com_liferay_journal_web_portlet_JournalPortlet_fieldsContent",
+    );
+    if (fieldsContainerEl) {
+        if (Liferay.editorCustomFields.webContentObserver) {
+            Liferay.editorCustomFields.webContentObserver.disconnect?.();
+        }
+        const debouncedFieldEvent = debounce(() => {
+            observePreviewImage('content');
+            fireWebContentFieldsOnLoad();
+        }, 500);
+        Liferay.editorCustomFields.webContentObserver = new MutationObserver(debouncedFieldEvent);
+        const observer = Liferay.editorCustomFields.webContentObserver
+        const config = { attributes: false, childList: true, subtree: true };
+        observer.observe(fieldsContainerEl, config);
+    }
+};

package/src/types/ContentType.type.ts

@@ -0,0 +1 @@
+export type ContentType = 'fragment' | 'content';

package/src/util/debounce.ts

@@ -0,0 +1,9 @@
+export const debounce = (callback, wait) => {
+    let timeoutId = null;
+    return (...args) => {
+        window.clearTimeout(timeoutId);
+        timeoutId = window.setTimeout(() => {
+            callback(...args);
+        }, wait);
+    };
+};

package/src/util/getContentImageInput.ts

@@ -0,0 +1,5 @@
+export const getContentImageInput = () => {
+    const contentImageInputQuery = 'input[name^="_com_liferay_journal_web_portlet_JournalPortlet_ddm$$Image"]';
+    const contentImageInput: HTMLInputElement = document.querySelector(contentImageInputQuery);
+    return contentImageInput;
+}

package/src/util/getFieldByLabel.ts

@@ -0,0 +1,25 @@
+  /**
+   * Uses xpath to get a LR field by label
+   * since there is no attribute that corresponds with field name or key
+   *
+   */
+  type GetFieldByLabel = (label:string) => HTMLInputElement;
+  export const getFieldByLabel:GetFieldByLabel = (label) => {
+    const parentEl = document.querySelector(
+      "#portlet_com_liferay_journal_web_portlet_JournalPortlet, .page-editor__item-configuration-sidebar",
+    );
+    const match = document.evaluate(
+      `//label[text()='${label}']`,
+      parentEl,
+      null,
+      XPathResult.FIRST_ORDERED_NODE_TYPE,
+      null,
+    ).singleNodeValue as HTMLElement;
+
+    const inputEl =
+      match?.closest(".form-group, .field-wrapper")?.querySelector("input") ||
+      match?.nextElementSibling?.querySelector("input") ||
+      match?.nextSibling;
+
+    return inputEl as HTMLInputElement;
+  };

package/src/util/getPreviewImage.ts

@@ -0,0 +1,10 @@
+export const getPreviewImage = () => {
+    const parentEl:HTMLDivElement = document?.querySelector(
+        "#portlet_com_liferay_journal_web_portlet_JournalPortlet, .page-editor__topper.active",
+    );
+    const previewImage:HTMLImageElement = parentEl?.querySelector(
+        ".page-editor__topper.active img.page-editor__editable, .image-picker-preview>img",
+    ) as HTMLImageElement;
+    
+    return previewImage;
+}

package/src/util/index.ts

@@ -0,0 +1,7 @@
+import { debounce } from "./debounce";
+import { getContentImageInput } from "./getContentImageInput";
+import { getFieldByLabel } from "./getFieldByLabel";
+import { getPreviewImage } from "./getPreviewImage";
+import { setReactDomInputValue } from "./setReactDomInputValue";
+
+export { debounce, getContentImageInput, getFieldByLabel, getPreviewImage, setReactDomInputValue };

package/src/util/setReactDomInputValue.ts

@@ -0,0 +1,22 @@
+/**
+ * The fragment editor config inputs use react DOM
+ * So setting input element value doesn't work
+ *
+ * @param {element} inputEl
+ * @param {string} value
+ */
+export const setReactDomInputValue = (inputEl:HTMLInputElement, value:string) => {
+  inputEl.focus();
+  const nativeValueSetter = Object.getOwnPropertyDescriptor(
+    window.HTMLInputElement.prototype,
+    "value",
+  ).set;
+  nativeValueSetter.call(inputEl, value);
+
+  inputEl.dispatchEvent(new Event("input", { bubbles: true }));
+  inputEl.dispatchEvent(new Event("change", { bubbles: true }));
+
+  document.body.focus();
+
+  inputEl.dispatchEvent(new Event("blur", { bubbles: true }));
+};

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+	"compilerOptions": {
+		"declaration": true,
+		"esModuleInterop": true,
+		"lib": [
+			"DOM",
+			"ES2020"
+		],
+		"module": "ES2020",
+		"moduleResolution": "node",
+		"outDir": "./build/static",
+		"resolveJsonModule": true,
+		"sourceMap": false,
+		"target": "ES2020",
+		"types": [
+		]
+	},
+	"include": [
+		"./src/**/*"
+	]
+}

package/webpack.config.js

@@ -0,0 +1,62 @@
+/**
+ * SPDX-FileCopyrightText: (c) 2000 Liferay, Inc. https://liferay.com
+ * SPDX-License-Identifier: LGPL-2.1-or-later OR LicenseRef-Liferay-DXP-EULA-2.0.0-2023-06
+ */
+
+const path = require("path");
+const webpack = require("webpack");
+const ESLintPlugin = require("eslint-webpack-plugin");
+
+const DEVELOPMENT = process.env.NODE_ENV === "development";
+const WEBPACK_SERVE = !!process.env.WEBPACK_SERVE;
+
+module.exports = {
+  devServer: {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+    },
+    port: 3000,
+  },
+  devtool: DEVELOPMENT ? "source-map" : false,
+  entry: {
+    index: "./src/index.ts",
+  },
+  experiments: {
+    outputModule: true,
+  },
+  mode: DEVELOPMENT ? "development" : "production",
+  module: {
+    rules: [
+      {
+        test: /\.ts$/i,
+        use: ["ts-loader"],
+      },
+    ],
+  },
+  optimization: {
+    minimize: !DEVELOPMENT,
+  },
+  output: {
+    clean: true,
+    environment: {
+      dynamicImport: true,
+    },
+    filename: WEBPACK_SERVE ? "[name].js" : "[name].js",
+    library: {
+      type: "module",
+    },
+    path: path.resolve("build", "static"),
+  },
+  plugins: [
+    new ESLintPlugin({
+      files: "src/**/*.ts",
+      overrideConfigFile: `eslint.config.mjs`,
+    }),
+    new webpack.optimize.LimitChunkCountPlugin({
+      maxChunks: 1,
+    }),
+  ],
+  resolve: {
+    extensions: [".js", ".ts"],
+  },
+};