dotCMS and the Scripting Worlds Collide

The Problem

Although Velocity is great and dotCMS has a bunch of rich web tooling, sometimes it is easier or more practical to use a script in another language.  While it is possible to provide any kind of custom tooling or logic one might need through the use of Viewtools, Struts and other related tooling, it has become apparent that dotCMS web developers could benefit from more flexible options when it comes to implementing their logic.  Our new plugin architecture aids greatly in deploying java+velocity stack kinds of solutions but all still require custom Java classes and of course a restart of the dotCMS to deploy. Additionally, most dotCMS web developers prefer to stay within the familiar confines of HTML, CSS, and scripting languages. Enter the dotCMS Scripting Plugin.

Download and Deploy your Plugin

To use scripting, first you will need to download the scripting plugin. There is a version for both the dotCMS trunk and dotCMS released code. Both can be checked out via SVN and you can download the released version of the plugin here.

After the download is complete, you must deploy your plugin. In order to deploy your plugin, unzip the download and copy resulting folder to the plugins directory and run "ant deploy-plugins" from the root of the dotCMS. In the future dotCMS will be providing binary plugins which won't require ANT but for now it is a minor inconvenience considering the power plugins bring to the dotCMS. If you need more help deploying your plugins see

Getting your System Ready to Script

Once your plugin is deployed and the dotCMS has been restarted you will see a new role in the dotCMS named "Scripting Developer". You need to add this role to any user who will be using the new scripting tools. The reason for this is that the scripting plugin checks for the latest modified user of the web asset with the scripting code to ensure not just anyone can deploy code to your dotCMS installation. This can be a problem as the scripting languages are really powerful and can even be used to call and execute Java code or any dotCMS java class.

Evaluating your First Script in dotCMS

There are two primary ways to interact with the dotCMS Scripting engine. First you can simply just evaluate an expression from Velocity. Consider the example below




   $scriptingUtil.evalGroovy("2 + 2") 


   $scriptingUtil.evalRuby("2 * 2")


   $scriptingUtil.evalPython("4 * 1")

The $scriptingUtil is the Velocity tool that allows you to interact with with the dotCMS scripting engine. It has methods on it which, as seen above, will both evaluate and execute your scripts. In the example we asked the tool to evaluate a JavaScript expression for us. The result on the screen would be 4. Now lets add a little more to our test in the following example

#set($jsObject= $scriptingUtil.evalJS('
function printMe(num){
return "Printed from function"

The result would print "Printed from function" to the screen. As you can see, we defined a function and then called the JavaScript function we defined.  The last arguement of the method, currently null, can be used to pass in parameters for the called function.

Setting Variables

Some people may be wondering if they can set variables to use within the scripting languages.  Our "declare" method allows you to do just that.  Let's alter our first example a little.

   $scriptingUtil.declare("xyz", 4)




   $scriptingUtil.evalGroovy("xyz + 2")


   $scriptingUtil.evalRuby("$xyz * 2") 


   $scriptingUtil.evalPython("xyz * 1")

As you can see we declared xyz and then used it within each scripting language. Notice a couple of things here.

  1. We only had to declare it once.
  2. Within the scripting languages it is handled as a global variable hence the $ in front of xyz in the Ruby example.

Keeping Scripts as dotCMS File Assets

You can also maintain your scripts within the dotCMS as files. This is beautiful because combined when combined with webdav you can get into some great RAD style programming. Need a quick Help Desk application or some custom form/report, no problem. Consider the following

Ruby Greeter program.

# The Greeter class 
class Greeter
def initialize(name)
@name = name.capitalize
  def salute 
  "Hello #{@name}! from ruby salute"

From a piece of content look at how we interact with our class


The key here is that you must first execute the file. This will execute any code within the file. In our case all we did was define a class but if we had logic outside of the class definition of after it called the class or a function within the script it would execute that code. Remember that before you can evaluate an expression on a file you must execute the file. From this point the file is loaded and is referenced with the file name as the key. In our expression"Jason") we constructed a new instance of the Greeter. After we got our greeter instance we called the salute method which printed o the screen for us.

Curl in PHP

Here is another example of how you can script - this time with php.  This short script will curl (fetch) the contents of as a string and return them as a java string for you to parse to your hearts content.

$buffer = curl_exec($curl_handle);
return $buffer;

As you can see, the possibilities are endless.  There is much more to show and much more that can be done but as you can see this blows the doors wide open and brings tremendous power to what is already one of the most flexible wCMS frameworks on the market. And best of all it is all open source :-)

August 16, 2009

Filed Under:

python ruby scripting

Recommended Reading

dotCMS JavaScript SDK: Everything you need to know

It is critical that content authors have a top-notch experience when creating and modifying their pages, so dotCMS has introduced our new JavaScript SDK.

Beware of Content Management System (CMS) Fads

This blog warns against adopting new technologies without sufficient consideration, using examples to illustrate how jumping on trends can lead to wasted resources.

24.04.24 LTS: Upgrade to the Universe

Now available: dotCMS 24.04.24 LTS, the first long-term supported release of 2024