Skip to main content

Custom Fields

Custom Field Reference

This page lists what a custom field can use: the DotCustomFieldApi methods for working with the form, the Velocity variables available on the server, and the settings and field variables that configure the field.

DotCustomFieldApi#


Every custom field can use DotCustomFieldApi to work with the form. Put your code inside ready(), and look up each field once:

DotCustomFieldApi.ready(() => {
  const title = DotCustomFieldApi.getField('title');
  const slug = DotCustomFieldApi.getField('urlSlug');

  title.onChange((value) => slug.setValue(slugify(value || ''), { markDirty: false }));
});
MethodDescription
ready(callback)Runs your code as soon as the form is ready. Always start here.
getField(variable)Gives you any field on the form, by its variable name, so you can read or change it. See Field Methods.
openBrowserModal(options)Opens the dotCMS picker so the editor can choose a file, image, page or menu link. New content editor only. See openBrowserModal.
get(id) · set(id, value) · onChangeField(id, cb)Older shortcuts, still supported. Use getField() instead.

Field Methods#


MethodDescription
getValue()Returns the field's current value. See What Values Look Like.
setValue(value, { markDirty })Changes the field's value, as if the editor had typed it. For values your code fills in by itself (a default or a suggestion), pass { markDirty: false } so the content isn't marked as changed.
onChange(callback)Runs your code every time the field's value changes. It doesn't run when the form first opens, so read the starting value with getValue(). Returns a function that stops it.
getValidationState()Tells you whether the field is valid, for example whether a required field is still empty: { valid, invalid, touched, dirty, errors }.
onValidationChange(callback)Runs your code with that information right away and every time it changes. Use it to show the field in red.
show() · hide()Shows or hides a field, label included. A hidden field keeps its value.
enable() · disable()Lets the editor change a field, or locks it.

getField() never fails, even for a variable that doesn't exist on the form. Its methods then have no effect: getValue() returns undefined, getValidationState() reports a valid field, and onChange logs a warning in the browser console.

What Values Look Like#


Field typeNew content editorOld content editor
Text, Textarea, Custom, Select, Radio…stringstring
Checkbox, Multi Select, Tag, Categorystring[]comma-separated string
Block Editorobject (the JSON document)JSON string
Date, Time, Date and Timetimestampstring

When you change another field with setValue, give it a value of the same kind.

openBrowserModal#


openBrowserModal(options) takes these options:

OptionDescription
titleDialog header.
kindsWhat the editor can pick: "file", "dotasset", "page", "link". Default ["file", "dotasset"].
mimeTypesLimits the file types, for example ["image/*"] for images only. Don't combine it with "link": menu links have no file type.
status"live" to show only published items, or "archived" to start with the Archived filter on. Default "working".
pathFolder to open first, as //site/folder/.
sortSort order, for example { field: "modDate", direction: "desc" }.
onCloseRuns when the picker closes, with what the editor picked, or null if they cancelled.

What the editor picked comes with its title, url, identifier, inode and kind; files and dotAssets also include their mimeType. For a dotAsset, url doesn't point to the file: build the address as /dA/ followed by its identifier.

openBrowserModal() returns an object with a close() method, which closes the picker from your code.

Where Each Method Works#


MethodRecommendedDeprecatedOld content editor
readyYesYesYes
getValue / setValue / onChangeYesYesYes, values as text
getValidationState / onValidationChangeYesYesNo (always reports valid)
show / hideYesOnly when the form also has a Recommended custom fieldYes
enable / disableYesYesYes
openBrowserModalYesYesNo

Velocity Context#


Velocity runs on the server before the field is shown. Use it to bring in information about the content being edited, or settings, and hand it to your JavaScript. These variables are ready to use:

VariableWhat it isOn new content
$structureThe content typeSet (empty in Deprecated fields)
$fieldThis custom fieldSet
$contentletThe content being editedEmpty
$inodeThe id of this version of the contentEmpty
$identifierThe content's identifierEmpty
$langThe content's language idEmpty

Content that hasn't been saved yet has no $contentlet, $inode, $identifier or $lang. The usual Velocity tools ($dotcontent, $config…) also work.

Guard for New Content#

#if( $utilMethods.isSet($inode) )
  <input type="hidden" id="myField-inode" value="$inode" />
#else
  <p class="text-sm text-base-content/70">Save the content first to use this field.</p>
#end

Pass Server Values to Your Script#

<script type="module">
  const DEFAULT_TTL = $config.getIntProperty("DEFAULT_PAGE_CACHE_SECONDS", 15);

  DotCustomFieldApi.ready(() => {
    const ttl = DotCustomFieldApi.getField('cachettl');
    if (!ttl.getValue()) ttl.setValue(String(DEFAULT_TTL), { markDirty: false });
  });
</script>

Settings and Field Variables#


The options in the field's Overview and Settings tabs are saved as field variables. You'll normally use the tabs; this table is for when you see them on the Field Variables tab or set them through the API.

VariableValuesSet fromApplies to
newRenderModecomponent = Recommended, iframe = Deprecated. If it's missing, the field is Deprecated. Use lowercase.Overview → ImplementationBoth
hideLabeltrue hides the field's labelSettings → Hide LabelBoth
customFieldOptionsThe pop-up options in one value, for example {"showAsModal":true,"width":"800px","height":"600px"}Settings → Show as ModalDeprecated
showAsModaltrue shows an Open button, and the field opens in a pop-upField Variables, added by handDeprecated
width · heightSize of the pop-up, for example 800px or 90vwField Variables, added by handDeprecated

Show as Modal appears in the Settings tab only for Deprecated fields. Its width and height are set in pixels and start at 398 × 400; if no size is stored at all, the pop-up is 500 × 500 pixels. The separate showAsModal, width and height variables take priority over customFieldOptions. The Settings tab accepts pixels only; for other units such as vw, add the width and height variables by hand.