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 }));
});| Method | Description |
|---|---|
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#
| Method | Description |
|---|---|
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 type | New content editor | Old content editor |
|---|---|---|
| Text, Textarea, Custom, Select, Radio… | string | string |
| Checkbox, Multi Select, Tag, Category | string[] | comma-separated string |
| Block Editor | object (the JSON document) | JSON string |
| Date, Time, Date and Time | timestamp | string |
When you change another field with setValue, give it a value of the same kind.
openBrowserModal#
openBrowserModal(options) takes these options:
| Option | Description |
|---|---|
title | Dialog header. |
kinds | What the editor can pick: "file", "dotasset", "page", "link". Default ["file", "dotasset"]. |
mimeTypes | Limits 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". |
path | Folder to open first, as //site/folder/. |
sort | Sort order, for example { field: "modDate", direction: "desc" }. |
onClose | Runs 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#
| Method | Recommended | Deprecated | Old content editor |
|---|---|---|---|
ready | Yes | Yes | Yes |
getValue / setValue / onChange | Yes | Yes | Yes, values as text |
getValidationState / onValidationChange | Yes | Yes | No (always reports valid) |
show / hide | Yes | Only when the form also has a Recommended custom field | Yes |
enable / disable | Yes | Yes | Yes |
openBrowserModal | Yes | Yes | No |
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:
| Variable | What it is | On new content |
|---|---|---|
$structure | The content type | Set (empty in Deprecated fields) |
$field | This custom field | Set |
$contentlet | The content being edited | Empty |
$inode | The id of this version of the content | Empty |
$identifier | The content's identifier | Empty |
$lang | The content's language id | Empty |
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>
#endPass 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>Velocity reads $ and # in your script. Velocity may misread JavaScript that contains ${…} or text like '#end-date'. Build strings with + instead, or wrap the script in #[[ … ]]# so Velocity leaves it alone. Velocity variables such as $inode or $config don't work inside the wrapped block, so read them in a small script above it.
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.
| Variable | Values | Set from | Applies to |
|---|---|---|---|
newRenderMode | component = Recommended, iframe = Deprecated. If it's missing, the field is Deprecated. Use lowercase. | Overview → Implementation | Both |
hideLabel | true hides the field's label | Settings → Hide Label | Both |
customFieldOptions | The pop-up options in one value, for example {"showAsModal":true,"width":"800px","height":"600px"} | Settings → Show as Modal | Deprecated |
showAsModal | true shows an Open button, and the field opens in a pop-up | Field Variables, added by hand | Deprecated |
width · height | Size of the pop-up, for example 800px or 90vw | Field Variables, added by hand | Deprecated |
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.