cfalzone ||

I seem to get a lot of questions on how to start with velocity coding. What is available? What is the Syntax? I think it’s a good question so it’s time to write up a quick post about it.

First off, I would start with actually building your site. Come up with a need. Start with something simple and something that you already have data for. I found that trial and error on real problems is the best way for me to learn a new language.

Most likely, if you’re trying to do something simple, there is already an example of how to do it in DotCMS’s Demo Site. The username/password is: test@dotcms.org/test. Remeber to put a /c after the host to get to the login page. I’ve found that most of my questions can be answered just by looking a good example.

From there my next stop is the documentation that DotCMS has on velocity:

1. Velocity and the dotCMS: This is a great file to find out what API’s or ViewTools that are avilable in your Velocity code. For example: If you wanted to use the EscapeTool, you would use the variable $esc in your code. I show you in a bit how to find out what is available in each tool.
2. Velocity Cheat Sheet: This file has several nice examples on how to use the various Macros and ViewTools available in DotCMS. I find a lot of my answers about how to do something in DotCMS here.
3. Macros Tips and Tricks: The nice thing about velocity coding is that you don’t really have to know how to do it to take advantage of it. That’s where macros come in to play. Macros take a whole ball of velocity code and wrap it up into one nice little line of code. (Just noting here that you can get some good examples of velocity coding in the macros file: /dotCMS/WEB-INF/velocity/*.vm)

If you really cannot find what you are looking for in that, the next step would be to look in the API docs. Now, if you’ve never looked at Javadocs before this might be a little overwhelming at first. But, I find it extremely useful when I am trying to do something out of the box. Browse to http://dotcms.org/api. From there scroll down the list and click on the “View Tools” class (com.dotmarketing.viewtools). From there you will get a list of all the api’s that DotMarketing has created.

That’s nice if what you want is a list of DotCMS’s View Tools, but if you are looking for the built in stuff, head over to Apache’s Velocity Site and click on the Tools link. From there click on Generic Tools and then the specific tool that want to look up.

I hope that helps to get new users up and going with velocity. If you still feel very confused, here is a lit of other resources that you might find handy:

• Apache has a nice Velocity user’s guide.
• If you want to start developing your own ViewTools, check out the Developer’s guide.
• Velocity Template Language Reference Guide.
• (more to come as I find them).

Update: 1:12 PM, July 23, 2008:

Jim S. over in the DotCMS IRC group pointed out a velocity mailing list: http://www.nabble.com/Velocity—User-f347.html. Thanks Jim!

Also, that brings up a good point. We have a core group of DotCMS-er’s over in the #dotcms IRC chatroom. Feel free to jump on board and ask us your questions! We are on freenode.