Skip to main content

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#


LegacyNew
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 fieldDotCustomFieldApi.getField('id')
dojo.byId('el')document.getElementById('el')
Showing, hiding or locking a field by handfield.show(), hide(), enable(), disable()
dojo.require(…)Remove
dotcms.dijit.FileBrowserDialogDotCustomFieldApi.openBrowserModal({ … })
onclick="fn()" and other inline handlersaddEventListener('click', fn)

All the new methods are described in Custom Field Reference.

Control Changes#


LegacyNew
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 styledaisyUI 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 #else part.

Checklist#


  • No dojo or dijit left in the new code.
  • No DotCustomFieldApi.get, .set or .onChangeField left; use getField().
  • 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.