Junkfood

Most Roller customization documents I've read seem to deal with customizing the look of the weblog by editing page templates or CSS stylesheets. However, they are not helpful if what you want to change is output produced by Roller macros. Here are some tips for writing/customizing Roller macros (levels 4 and 5 of the Levels of Roller Customization below).

Levels of Roller Customization (from high to low-level):

1. Edit CSS stylesheets to customize styles.
2. Edit page templates to add/delete/move page elements and Roller macros.
3. Select different theme packages to get different base page templates and CSS stylesheets.
4. Create and use new macros.
5. Override existing Roller macros.
6. Change Roller configuration and installation.
7. Change Apache configuration.
8. Edit Roller source code.

Unfortunately, the documentation you need is scattered across many different sites. Specifically, you need documentation on Roller macros, Roller templates, Roller Java source code, the Velocity Template Language, and the Java programming language.

1. The Roller source code can be downloaded at: https://roller.dev.java.net/servlets/ProjectDocumentList?folderID=2525&expandFolder=2525&folderID=0
1. The Roller Velocity macros are in roller/web/WEB-INF/classes/*.vm
2. The themes are in roller/web/themes/*. They are useful to see what can be done by simply editing CSS and page templates.
3. The Java source code is in roller/src/*. You need it to be able to discover the many useful (but undocumented) Roller variables. You'll also want to see how the hardcoded functions work. The most interesting classes are:
• org.roller.pojos.CommentData
• org.roller.pojos.PageData
• org.roller.pojos.RefererData
• org.roller.pojos.WeblogCategoryData
• org.roller.pojos.WeblogEntryData
• org.roller.pojos.WebsiteData
• org.roller.presentation.velocity.PageHelper
• org.roller.presentation.velocity.PageModel
• org.roller.business.RefererManagerImpl
• org.roller.business.WeblogManagerImpl
• org.roller.util.*
2. Roller documentation is available at:
   1. User Guide (incomplete, but an okay start): http://www.rollerweblogger.org/wiki/Wiki.jsp?page=UserGuide
   2. Macro and Variable Reference (very incomplete): http://www.rollerweblogger.org/wiki/Wiki.jsp?page=RollerMacros
3. Velocity documentation is needed to learn how to program in the Velocity Template Language. Specifically, you'll need:
1. User Guide: http://jakarta.apache.org/velocity/user-guide.html
2. Reference Guide (really, it's the second half of the User Guide): http://jakarta.apache.org/velocity/vtl-reference-guide.html
4. Java documentation is needed to find out what can be done with Velocity objects. You will probably need to know how to program in the Java language. Documentation is at: http://java.sun.com/j2se/1.4.2/docs/api/index.html. The most useful classes are:
1. java.lang.String
2. java.util.ArrayList
3. java.util.Map

Customization at this level is really just programming: writing new macros and re-writing the Roller macros. This requires knowledge of the Velocity Template Language (which is a programming language). It also requires knowledge of Java since Velocity is designed to interface with Java. Its basic variable types (String, ArrayList, Map) are Java objects whose methods are available to be used (if you know how). Roller is written in Java, and its objects, variables, and methods can also be used. Unfortunately, Roller is poorly documented and reading/interpreting its Java source code is necessary.

Some tips:

• Create a (possibly hidden) test page which is a duplicate of your main Weblog page. Do all your experimentation on the test page. When things work right, you can copy the changes over to the Weblog page.
• Removing the stylesheet from your test page may be helpful to prevent CSS from affecting how changes appear.
• Velocity seems to be very picky about how lines are indented. Be sure to indent all lines properly (following the Roller macros as examples), with 4 spaces per indent. I've found that mis-indented lines can cause mysterious errors.
• If you make a change to a template macro and the resulting page is blank, you've made a mistake that prevents the macro from running. Try commenting out lines in the macro to see where the problem lies.
• Velocity control operators and data structures are very primitive. You will probably need to write programs that do things the hard way to work around this.
• Starting with page templates, drill down through the macros to see how things work and how the Roller developers did things.
• Instead of making a few big changes, make many small changes.
• Reload the test page after each change you make. This will help to identify problems as soon as they are introduced.
• Be sure to save copies of your page templates offline. You may want to save a copy each time you make a major change.
• Velocity macros take space-separated arguments, but Java methods take comma-separated arguments.
• The showWeblogEntries macro and its sub-macros contain most of the "guts" of how Roller works for weblog entries, comments, and search pages. It is the main "black box" whose contents can be overridden and customized.

Good luck!