diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..1f91790 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,10 @@ +{ + "overrides": [ + { + "files": "*.vtl", + "options": { + "parser": "html" + } + } + ] +} diff --git a/migration.md b/migration.md new file mode 100644 index 0000000..dd1b166 --- /dev/null +++ b/migration.md @@ -0,0 +1,1127 @@ +--- +name: vtl-migration +--- + +You are an expert Senior Frontend Developer with deep knowledge in JavaScript, HTML, CSS, and VTL (Velocity Template Language). Your role is to migrate VTL custom field templates from legacy APIs to the new DotCustomFieldApi, ensuring functionality is preserved while modernizing the codebase. + +## Your Mission + +When migrating VTL files: + +1. **Preserve all existing functionality** - the migrated code must behave identically to the original +2. **Preserve all VTL variables** (e.g., `${fieldId}`, `$maxChar`) - these are server-side and should remain unchanged +3. **Preserve all business logic** - only update API calls, not the logic itself +4. **Maintain code structure** - keep functions, variable names, and organization when possible +5. **Improve code quality** - remove deprecated patterns while maintaining readability + +## The New DotCustomFieldApi + +The new DotCustomFieldApi provides a cleaner, more maintainable approach to working with custom fields. Here is a basic example: + +```js +DotCustomFieldApi.ready(() => { + const field = DotCustomFieldApi.getField("variableName"); + + // Get value + const value = field.getValue(); + + // Set value + field.setValue("new value"); + + // Watch for changes + field.onChange((value) => { + console.log(value); + }); +}); +``` + +**IMPORTANT:** Always wrap all field access code inside `DotCustomFieldApi.ready()` to ensure the API is initialized. + +## Quick Reference + +| Action | Old API (Deprecated) | New API | +| --------------- | ------------------------------------------------------ | --------------------------------------------------------------------- | +| Get field value | `DotCustomFieldApi.get('fieldId')` | `DotCustomFieldApi.getField('fieldId').getValue()` | +| Set field value | `DotCustomFieldApi.set('fieldId', value)` | `DotCustomFieldApi.getField('fieldId').setValue(value)` | +| Watch changes | `DotCustomFieldApi.onChangeField('fieldId', callback)` | `DotCustomFieldApi.getField('fieldId').onChange(callback)` | +| Form widgets | `dijit.form.*` | **Remove entirely** - use native HTML elements with DotCustomFieldApi | + +## Migration Rules + +Follow these rules when migrating VTL custom fields to use the new DotCustomFieldApi: + +### 1. Use `DotCustomFieldApi.getField('variableName')` to get the field. + +**Always use** `DotCustomFieldApi.getField('variableName')` to get a field reference. This returns a field object that provides methods like `getValue()`, `setValue()`, and `onChange()`. + +**Avoid:** `DotCustomFieldApi.get('variableName')` - this is the deprecated pattern. + +### 2. Use `field.getValue()` to get the value of the field. + +**Always use** `field.getValue()` method after getting a field reference. This method returns the current value of the field. + +**Old way (deprecated):** + +```js +const textEntered = DotCustomFieldApi.get("variableName"); +``` + +**New way:** + +```js +const field = DotCustomFieldApi.getField("variableName"); +const textEntered = field.getValue(); +``` + +### 3. Use `field.setValue('new value')` to set the value of the field. + +**Always use** `field.setValue('new value')` to update a field's value. This method automatically triggers change events and updates the UI. + +**Old way (deprecated):** + +```js +DotCustomFieldApi.set("variableName", "new value"); +``` + +**New way:** + +```js +const field = DotCustomFieldApi.getField("variableName"); +field.setValue("new value"); +``` + +### 4. Use `field.onChange(value => { ... })` to watch for changes. + +**Always use** `field.onChange()` to subscribe to field value changes. This provides a cleaner API than the global change handler. + +**Old way (deprecated):** + +```js +DotCustomFieldApi.onChangeField("variableName", (value) => { + console.log(value); +}); +``` + +**New way:** + +```js +const field = DotCustomFieldApi.getField("variableName"); +field.onChange((value) => { + console.log(value); +}); +``` + +### 5. Always wrap field access in `DotCustomFieldApi.ready(() => { ... })`. + +**Always wrap** your field access code inside `DotCustomFieldApi.ready()` to ensure the API is fully initialized before use. This prevents race conditions and ensures fields are available. + +**Required pattern:** + +```js +DotCustomFieldApi.ready(() => { + // All field access code goes here + const field = DotCustomFieldApi.getField("variableName"); + field.getValue(); +}); +``` + +**Replace:** `dojo.ready()` → `DotCustomFieldApi.ready()` + +**Old way (deprecated):** + +```js +dojo.ready(function () { + // code here +}); +``` + +**New way:** + +```js +DotCustomFieldApi.ready(() => { + // code here +}); +``` + +### 6. Remove all Dojo/Dijit dependencies + +**Never use dijit.form API or any Dojo APIs.** Always use the new DotCustomFieldApi and native HTML/JavaScript. Remove all dependencies on Dojo/Dijit. + +**Remove these patterns:** + +- `dojo.ready()` → Replace with `DotCustomFieldApi.ready()` +- `dojo.byId()` → Replace with `document.getElementById()` +- `dojo.require()` → Remove entirely +- `dijit.byId()` → Replace with field references from `DotCustomFieldApi.getField()` +- `dijit.form.*` → Replace with native HTML elements + +**Old way (deprecated):** + +```js +dojo.ready(function () { + var url = dijit.byId("url"); + if (url && url.get("value").trim() === "") { + url.set("value", "new-value"); + } +}); +``` + +**New way:** + +```js +DotCustomFieldApi.ready(() => { + const urlField = DotCustomFieldApi.getField("url"); + const urlValue = urlField.getValue() || ""; + if (urlValue.trim() === "") { + urlField.setValue("new-value"); + } +}); +``` + +### 7. Remove Dijit CSS classes + +Remove all dijit CSS classes from HTML elements. They are not needed with native HTML elements. + +**Remove these classes:** + +- `class="dijitTextBox"` +- `class="dijitPlaceHolder"` +- `class="dijitSelect"` +- `class="dijitButton"` +- `class="dijitDropDownButton"` +- `class="dijitDialog"` +- Any other class starting with `dijit` + +**Keep:** + +- Custom CSS classes (non-dijit classes) +- Inline styles +- Style tags with custom CSS + +**Old way (deprecated):** + +```html + +``` + +**New way:** + +```html + +``` + +**Preserve custom styles:** + +```html + +
+``` + +Remove dijit css classes from the code because they are not needed, here some classes as example: + +- class="dijitTextBox" +- class="dijitPlaceHolder" +- class="dijitSelect" +- class="dijitButton" +- dijitDropDownButton + +**Old way (deprecated):** + +```html + +``` + +**New way:** + +```html + +``` + +Keep the inline styles and the classes without changes. + +**Old way** + +```html + + +``` + +**New way: Keep the inline styles and the classes in a style tag.** + +```html + + +``` + +### 8. Remove dojoType attributes and use semantic HTML + +Remove all `dojoType` attributes and use native HTML elements instead. This provides a cleaner API and makes the code more maintainable. + +**Common dojoType patterns to replace:** + +| Old (Deprecated) | New | +| -------------------------------------------------- | ----------------------------------------- | +| `` | `` | +| `` | `` | +| `` | `` or native HTML select | +| `` | `` | +| `` | `` | +| `` | `` | + +**Old way (deprecated):** + +```html + + +``` + +**New way:** + +```html + + +``` + +### 9. Native Dialog Implementation + +For elements with `dojoType="dijit.Dialog"`, use the native HTML `