Custom Fields
Migrating Legacy Custom Fields
Older custom fields were built with the Dojo library: you'll recognize them by code such as dojo.ready, dijit.byId or dojoType. In the new content editor they run as Deprecated until you update them. Updating one takes three steps: replace the old code with DotCustomFieldApi, replace the old controls with daisyUI ones, and switch the field to Recommended.
You can do it by hand with the tables below, or let Claude Code do it for you, one field at a time or all at once: see Migrating Custom Fields with Claude Code.
Code Changes#
| Legacy | New |
|---|---|
dojo.ready(fn) | DotCustomFieldApi.ready(fn) |
DotCustomFieldApi.get('id') | DotCustomFieldApi.getField('id').getValue() |
DotCustomFieldApi.set('id', v) | DotCustomFieldApi.getField('id').setValue(v) |
DotCustomFieldApi.onChangeField('id', cb) | DotCustomFieldApi.getField('id').onChange(cb) |
dijit.byId('id') for another field | DotCustomFieldApi.getField('id') |
dojo.byId('el') | document.getElementById('el') |
| Showing, hiding or locking a field by hand | field.show(), hide(), enable(), disable() |
dojo.require(…) | Remove |
dotcms.dijit.FileBrowserDialog | DotCustomFieldApi.openBrowserModal({ … }) |
onclick="fn()" and other inline handlers | addEventListener('click', fn) |
All the new methods are described in Custom Field Reference.
Control Changes#
| Legacy | New |
|---|---|
dijit.form.TextBox | <input class="input w-full"> |
dijit.form.Button | <button type="button" class="btn"> |
dijit.form.FilteringSelect | <select class="select"> |
dijit.form.RadioButton | <input type="radio" class="radio"> |
dijit.Dialog | <dialog class="modal"><div class="modal-box">… |
class="dijit…" and inline style | daisyUI and Tailwind classes |
See Styling Custom Fields for the classes you can use.
If Some Editors Still Use the Old Content Editor#
Keep both versions in the same field: the new code first, and your original code, unchanged, after #else. The first part runs when the field is set to Recommended. Deprecated fields, and the old content editor, run the part after #else.
This example is a field that ships with dotCMS, shown here combined into one file:
#if( $structures.isNewEditModeEnabled() )
<script type="application/javascript">
DotCustomFieldApi.ready(() => {
const cachettlField = DotCustomFieldApi.getField("cachettl");
const cachettlbox = document.getElementById("cachettlbox");
let currentValue = cachettlField.getValue() || "";
if (currentValue === "") {
currentValue = $config.getIntProperty("DEFAULT_PAGE_CACHE_SECONDS", 15);
cachettlField.setValue(currentValue);
}
cachettlbox.value = currentValue;
cachettlbox.addEventListener("change", () => {
cachettlField.setValue(cachettlbox.value);
});
});
</script>
<input type="text" class="input w-full" id="cachettlbox" />
#else
<script type="application/javascript">
dojo.ready(function () {
var currentValue = dojo.byId("cachettl").value;
if (currentValue === "") {
currentValue = $config.getIntProperty("DEFAULT_PAGE_CACHE_SECONDS", 15);
dojo.byId("cachettl").value = currentValue;
}
new dijit.form.TextBox(
{
name: "cachettlbox",
value: currentValue,
onChange: function () {
dojo.byId("cachettl").value = this.get("value");
},
},
"cachettlbox",
);
});
</script>
<input id="cachettlbox" />
#end- Don't change the original code in the second part.
- If the original code has a Velocity syntax error, such as a missing
#end, it can break the new version too. In that case, keep the two versions in separate files; Claude Code can do this for you. - Once nobody uses the old editor, delete the
#elsepart.
Checklist#
- No
dojoordijitleft in the new code. - No
DotCustomFieldApi.get,.setor.onChangeFieldleft; usegetField(). - All the code that uses the form is inside
DotCustomFieldApi.ready(). - The field does the same thing it did before.
- It uses daisyUI and Tailwind classes instead of custom styles where possible.
- It's switched to Recommended, and you've tried it in the editor.
Deprecated is not a drop-in for old code. Some older fields stop working when set to Deprecated, with the error DotCustomFieldApi.get is not a function. Until you update them, wrap their code in DotCustomFieldApi.ready(function () { … }).