RFC: Custom Fields Compatibility Across Editors

[nicobytes]

Authors: @oarrietadotcms & @nicobytes

---

Summary

Support custom fields for both versions of the editor: the new Angular-based editor and the legacy Dojo-based editor.

---

Background

Custom fields require access to form fields to enable custom behaviors. In the old editor, VTL syntax is used with plain JavaScript to achieve this. For example, in the VTL template text-count.vtl, the field value is accessed with:

document.getElementById('${fieldId}').value;

This approach enables features like counting characters in a field.

text-count.vtl

However, in the new editor with Angular, custom fields are loaded in an iframe. To access the field value, a reference to the parent element is required:

parent.document.getElementById('${fieldId}').value;

This works in the new editor but breaks compatibility with the old editor.

Another approach is to expose the Angular form to custom fields, this way was implemented by @kevindaviladev in this PR, allowing access via:

form.get('${fieldId}').value;

While this works well in the new editor, it fails in the old editor due to the lack of Angular form references. Additionally, exposing Angular Forms ties the implementation to Angular APIs, which might change over time, necessitating VTL template rewrites.

---

Proposal

Using the Bridge and Facade Patterns, create a DotFormAPI to standardize access to field values across both editors. The API provides methods like:

DotFormAPI.getFieldValue('${fieldId}');
DotFormAPI.setFieldValue('${fieldId}', value);
DotFormAPI.onFieldChange('${fieldId}', (value) => {
    // Handle changes
});

Example

text-count.vtl

document.addEventListener("DOMContentLoaded", function() {
    function countCharacters${fieldId}(textEntered) {
        const counter = textEntered.length;
        const countRemaining = document.getElementById('charactersRemaining-${fieldId}');
        countRemaining.textContent = counter;
        document.getElementById('${fieldId}-counter-text').style.color = counter <= $maxChar ? "#6c7389" : "red";
    }

    // Initial count
    countCharacters${fieldId}();

    // Event listener for changes
    DotFormAPI.onFieldChange('${fieldId}', (value) => {
        countCharacters${fieldId}(value);
    });
});

Or in another vtl template to create a slug.

DotFormAPI.onFieldChange('title', (titleValue) => {
    const slug = titleValue
        .toLowerCase()
        .replace(/[^a-z0-9]+/g, '-')
        .replace(/^-+|-+$/g, '');
    DotFormAPI.setFieldValue('urlTitle', slug);
});

Using this approach, we can create a custom field that works in both the new and the old editor. More importantly, we are not exposed to the Angular Forms API, and we can change the API without affecting the VTLSs. For example, if we use the new Angular Signals forms in the future, we can change the API without affecting the VTLSs. Alternatively, if in the future dotAdmin wants to use another form library, such as TanStack Angular Form, we can change the API (DotFormAPI) without affecting the VTLs.

---

Impact

Benefits

• Custom fields work seamlessly across both editors.
• Decouples implementation from Angular Forms API, reducing maintenance risk.
• Allows flexibility to change form libraries without impacting custom fields.

Trade-offs

• Customers need to update their custom fields to use the new API.
• We need to create the proper documentation for the customers to implement DotFormAPI.

---

Technical Details

DotFormAPI For Angular

class DotFormBridge {
    constructor(private form: any, private zone: NgZone) {}

    getField(fieldName: string) {
        return this.zone.run(() => {
            const control = this.form.get(fieldName);
            return {
                value: control?.value,
                valid: control?.valid ?? false,
                errors: control?.errors,
                dirty: control?.dirty,
                touched: control?.touched,
                disabled: control?.disabled
            };
        });
    }

    setFieldValue(fieldName: string, value: any) {
        this.zone.run(() => {
            this.form.get(fieldName)?.setValue(value);
        });
    }

    onFieldChange(fieldName: string, callback: (field: any) => void) {
        this.zone.run(() => {
            const control = this.form.get(fieldName);
            if (control) {
                control.statusChanges.subscribe(() => {
                    callback({
                        value: control.value,
                        valid: control.valid,
                        errors: control.errors,
                        dirty: control.dirty,
                        touched: control.touched,
                        disabled: control.disabled
                    });
                });
            }
        });
    }
}

@Component({
    selector: 'dot-edit-content-custom-field',
    // other configurations
})
export class DotEditContentCustomFieldComponent {
    onIframeLoad() {
        const iframeWindow = this.iframe.nativeElement.contentWindow as Window;
        iframeWindow['DotFormAPI'] = new DotFormBridge(this.form, this.zone);
    }
}

DotFormAPI for Dojo

class DotFormBridge {
    constructor(formElement) {
        this.formElement = formElement;
        this._initFieldStates();
    }

    _initFieldStates() {
        const inputs = this.formElement.querySelectorAll('input, select, textarea');
        inputs.forEach((input) => {
            input.dataset.dirty = 'false';
            input.dataset.touched = 'false';
        });
    }

    getField(fieldName) {
        const field = this.formElement.querySelector(`[name="${fieldName}"]`);
        if (!field) return null;
        return {
            value: field.value,
            valid: field.checkValidity(),
            errors: field.validationMessage,
            dirty: field.dataset.dirty === 'true',
            touched: field.dataset.touched === 'true',
            disabled: field.disabled
        };
    }

    setFieldValue(fieldName, value) {
        const field = this.formElement.querySelector(`[name="${fieldName}"]`);
        if (field) field.value = value;
    }

    onFieldChange(fieldName, callback) {
        const field = this.formElement.querySelector(`[name="${fieldName}"]`);
        if (!field) return;

        const handler = () => {
            field.dataset.dirty = 'true';
            callback(this.getField(fieldName));
        };

        field.addEventListener('input', handler);
        field.addEventListener('blur', () => {
            field.dataset.touched = 'true';
            callback(this.getField(fieldName));
        });
    }
}

// Usage
const formElement = document.getElementById('myForm');
const formBridge = new DotFormBridge(formElement);
formBridge.onFieldChange('name', (state) => console.log('Name field changed:', state));

---

[oidacra]

https://github.com/dotCMS/core/pull/27665/files

[rjvelazco]

Does This Break Customer Implementation?

This code is a promising solution that provides an API for communication between users and the new edit content feature. However, will this impact the current client implementations? Specifically, clients with extensive custom fields might face challenges when addressing these changes.

Discussing this point is crucial, especially if these custom fields are transitioning to a "Legacy" status —something we considered while I was working on Edit Content.

Dojo/Dijit Considerations

dojo is currently used in custom fields, enabling users to modify field values through methods like dijit.byId('${fieldId}').value and dojo.byId("currentHostIdForTagSuggestion").value. Have we accounted for this functionality?

Alternative Solutions

While working on Edit Content, I prioritized maintaining compatibility with existing customer implementations. I developed a POC to ensure custom fields worked seamlessly while emitting their values to Angular. This approach involved dynamically constructing the form for each custom field, preserving all values.

The process included creating hidden input elements within an iframe, allowing users to access field values without visual disruptions.

Proposal: Custom Fields Compatibility Across Editors

Summary

Embed all input fields within the iframe's HTML to ensure customers can access their values seamlessly. Synchronize Angular and custom fields using PostMessages.

Technical Details

1. Retrieve Input Fields

The Angular iframe points to legacy-custom-fields.jsp, where we reference the form:

Legacy Custom Fields JSP

We can utilize contentType.fieldMap() to obtain a JSON representation of all custom fields:

String fieldJson = mapper.writeValueAsString(contentType.fieldMap());

2. Create Input Fields in the iframe HTML

The following script generates hidden input fields, allowing customers to access them without disrupting their current implementation:

<script>
    const fields = Object.values(<%= fieldJson %>);
    const bodyElement = document.querySelector('body');
    // Create fields in the local environment (iframe)
    fields.forEach(({ variable, value }) => {
        const input = document.createElement('input');
        input.type = 'hidden';
        input.name = variable;
        input.id = variable;
        input.setAttribute('dojoType', 'dijit.form.TextBox');
        input.value = value;
        bodyElement.appendChild(input);
    });

    <!-- Insert custom field code -->
    <%= HTMLString %>
</script>

Considerations

1. Check the id used by the old Edit Contentlet for inputs to ensure consistency.
2. Adjust attributes as needed.
3. The dojoType attribute is necessary for Dojo to recognize the inputs, allowing users to access their values via Dojo.

3. Synchronize State

Utilize postMessage to keep the form states synchronized:

fields.forEach(({ variable }) => {
    const input = dojo.byId(variable);
    handleGlobalSetInInput(input, variable);
});

function handleGlobalSetInInput(input, variable) {
    // Copy the original descriptor from the prototype
    const valueDescriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value');
    Object.defineProperty(input, 'value', {
        get() {
            return valueDescriptor.get.apply(this);
        },
        set(value) {
            console.log("Triggered on any change, including Dojo updates");
            postMessageEditor(variable, value);
            valueDescriptor.set.apply(this, [value]);
        }
    });
}

Considerations
Why use the valueDescriptor instead of an event listener?

Dojo's behavior can bypass standard events; for instance, setting dojo.byId(variable).value = 'newValue' updates the reference but doesn’t trigger events. The custom value descriptor handles:

Normal HTML updates:

• document.getElementById(variable).value = 'newValue'
• document.getElementById(variable).setAttribute("value", "newValue")
• Events: change/input
  Dojo updates:
• dojo.byId(variable).setValue()
• dojo.byId(variable).value = 'newValue'

Reference

• PR: POC(Edit Content): Make custom fields work and emit value to Angular #27665

[nicobytes]

This approach is interesting from the perspective of keeping VTLs running without any changes for our customers. However, I have two concerns:

Performance

With this code, all fields are cloned in custom fields. For large forms with many fields, this means we’re effectively cloning the entire form for each custom field:

<script>
    const fields = Object.values(<%= fieldJson %>);
    const bodyElement = document.querySelector('body');
    // Create fields in the local environment (iframe)
    fields.forEach(({ variable, value }) => {
        const input = document.createElement('input');
        input.type = 'hidden';
        input.name = variable;
        input.id = variable;
        input.setAttribute('dojoType', 'dijit.form.TextBox');
        input.value = value;
        bodyElement.appendChild(input);
    });

    <!-- Insert custom field code -->
    <%= HTMLString %>
</script>

Maintaining Dojo

The main benefit of this proposal is also its drawback: it continues to rely on references like dojo.byId or dijit.byId in the VTL, effectively preserving legacy code. Since we plan to remove Dojo soon, this may not be ideal for the long term.

---

In my opinion, if we want to move forward, we need to create the DotFormAPI bridge. I understand that migrating all our customers’ VTL templates could be painful, so we could offer both solutions:

• Create the new DotFormAPI and recommend that customers use it for new VTL templates.
• Provide backward compatibility using your current approach, so customers aren’t forced to make immediate changes.

Another solution could be offer a migration tool but I think is it complex but this a great task for a LLM.

[rjvelazco]

@nicobytes, as you mentioned, the proposed solution was aimed at minimizing disruption for customer support. If we’re comfortable with customers manually migrating these files, then the Bridge approach would indeed be the best option.

Regarding the performance concern, while it's valid, I believe the impact should be minimal since these are just HTML text inputs. It shouldn't significantly affect performance.

On the other hand, concerning the Dojo maintenance, my understanding was that the next step for Custom Fields wasn’t to remove the current ones entirely, but rather to deprecate the existing fields while introducing a new custom field format that supports HTML, JavaScript, and CSS.

[nicobytes]

The final decision is to create the bridge and to create a migration tool for the customers

@danielmdob @john-thomas-dotcms @wezell

The plan:

Goal
Create a bridge tool that enables seamless form interaction in Custom Fields across both DOJO and Angular versions of Edit Content, providing:

Primary Objective
Develop a bridge that allows Custom Fields to:

• Read/write field values within the form
• Access other form fields
• Handle form validations and Angular form features
• Maintain compatibility with existing VTL implementations

Key Outcomes

• Smooth transition path between DOJO and Angular versions
• Backward compatibility for existing implementations
• Forward compatibility using DotCustomFieldApi
• Consistent API for form interactions

Important Note
Clients will need to update their VTL implementations to use DotCustomFieldApi when transitioning to the new version.

Release Tasks:
-Bridge Core Development (Task 1, 1 Issue):
-Initial bridge library setup (based on existing example)

• Implement iframe-parent communication (integrate DotCustomFieldApi)

Create core API methods for field manipulation:

• Field getters/setters
• Field registration system
• Develop unit tests for bridge functionality

Demo Site VTLs Enhancement (Task 2, 1 Issue):

• Create inventory of existing demo VTLs
• Update VTLs to use DotCustomFieldApi
• Create example VTLs showcasing best practices
• Update existing VTLs to use the bridge

Starter Site Updates (Task 3):

• Generate new Starter version with updated VTL
• Essential Documentation (Task 4):
• Update existing custom fields documentation
• Basic migration guide
• Key implementation examples

Post-Release Tasks:
Bridge Enhancement Features (Task 1):

• Implement events system for validations and triggers

Migration Tools (A must) (Task 2 / DotAI + Documentation well defined):
Automated migration scripts where possible.

JavaScript Viewtool Implementation (Task 3)
Definition pending

More context: https://dotcms.slack.com/archives/C058GCQ7T39/p1736876783363529