Custom Field documentation for the dotCMS Content Management System

Custom fields allow developers to create unique and domain specific form controls and interactions that can be used by content editors. These fields use your own custom code to display and handle fields, and then store the resulting values in dotCMS content fields where it is accessible when the content is accessed or rendered. Custom fields are simple to write, and can add powerful interaction to your content editing screens.

Code Use

Any code which is valid in a dotCMS widget may be used in a Custom field, including HTML, Velocity and Javascript.


You may use any valid Javascript inside a Custom field, and you may use any Javascript libraries accessible within dotCMS.


dotCMS uses Dojo internally on the Edit Content screen, which means that it is easier to use Dojo than other Javascript libraries when working with Custom fields. Very little Dojo code is needed to use it effectively within Custom fields, so even if you're familiar with another Javascript library, it may be easier to use and work with Dojo within your Custom fields. For examples of the minimal Dojo required in custom fields, please see the examples referenced below.


You may use jQuery in dotCMS, and a number of organizations use jQuery in dotCMS Custom fields. However be aware that dotCMS does not use jQuery internally on the Edit Content screen, so to use jQuery you must provide all libraries and code to support it, and this may be a significant effort to implement and maintain.


Simple Custom Field Example

Below is a simple example of a custom field. To use it, you need to add a Custom Field to a content object and name this field “Test”. Place the code below in the “value” textbox for the custom field. (Pro Tip: Make your custom fields a .vtl file and then put a #dotParse(“/application/my-custom-field.vtl”) in the value textbox of the custom field. This allows you to edit the custom field via webdav and it is versionable, etc..) Because custom fields are just HTML/JS/Velocity, you have access to all the velocity tools provided by dotCMS, including custom ones that you can provide.

## This example uses a custom field that is called "test" and has the variable name "test"

## first we get the content (we have access to all our 
## velocity tools, including any custom ones that have been written

#set($content = $dotcontent.find($request.getParameter("inode")))

## then we write some ugly js to get and set the values on the edit content form - 
## the of the hidden field that stores the value is just the velocity variable name
## so watch out for js variable scope issues

    function myButtonClick(){
        var x = document.getElementById('test').value;

        if(x==undefi/dA/ned || x.length==0){

## then we write out our user controls, displaying the value stored in the content object by default
## with a button (dojo styled) that calls our js

Custom Value: <span id="customValue">$!content.test</span> 
<button dojoType="dijit.form.Button" id="myButton" onclick="myButtonClick">Click me!</button>

Google Maps Example

The dotCMS Demo Site provides several demonstrations of how custom fields can be leveraged. For example, if you edit a “News” content item from the demo site's admin screen, you can see a button control that pops up a Google Maps window. This widget allows you to select a geographic location for your news content. The location you select sets the latitude and longitude, which is stored in the “News” content object and makes the news geo-locatable.

YouTube Widget Example

Another example on thedemo siteis the Youtube Widget. This content type allows users to search Google's YouTube library and select a video. The custom field stores the YouTube ID and then populates the rest of the contents fields with the video's metadata (from Google).

Other Examples

For more examples of custom fields, see our codeshare site: