Dispatcher and flavor configuration - blojsom - Confluence

Terminology

A dispatcher is the component which handles loading of page templates and making available certain objects for you to use in your templates. blojsom's default installation comes with two different dispatchers, one for using JavaServer Pages (JSP) and one for using Velocity.

A flavor is the format in which data from your blog, most notably categories and entries, are presented back to the requesting client.

Dispatcher configuration

The dispatcher configuration is located in the /WEB-INF/dispatcher.properties file. The default blojsom installation has the JSP and Velocity dispatchers configured as follows.

jsp=org.blojsom.dispatcher.JSPDispatcher
vm=org.blojsom.dispatcher.VelocityDispatcher

The format of this file is:

template_extension=fully-qualified class name handling the dispatcher capabilities

In the above configuration, this is telling blojsom that it should associate template files that end in .jsp with the JSP dispatcher and that it should associate template files that end in .vm with the Velocity dispatcher.

If you wanted to change the name of the dispatcher configuration file, you could change the following initialization parameter for the blojsom servlet in /WEB-INF/web.xml.

<init-param>
    <param-name>dispatcher-configuration</param-name>
    <param-value>/WEB-INF/dispatcher.properties</param-value>
</init-param>

Configuring your flavor templates to use a particular dispatcher

In your individual /WEB-INF/(blog-id)/flavor.properties file, you can configure which templates are to be used to render a particular flavor. The default blojsom installation has a default user configured as follows.

atom=atom.vm, text/xml;charset=UTF-8
html=html.vm, text/html;charset=UTF-8
rsd=rsd.vm, text/xml;charset=UTF-8
rss=rss.vm, text/xml;charset=UTF-8
rss2=rss2.vm, text/xml;charset=UTF-8
rdf=rdf.vm, text/xml;charset=UTF-8
text=text.vm, text/plain;charset=UTF-8
admin=org/blojsom/plugin/admin/templates/admin.vm, text/html;charset=UTF-8

The format of this file is:

flavor_name=template_name, content-type;charset=(some character set)

The flavor_name can be any name you want. blojsom comes configured with default templates for HTML and the various syndication formats (Atom and RSS).
The template_name property is the template filename, which must be placed in the blog's /WEB-INF/(blog-id)/templates directory.
The content-type property is used by blojsom to tell the requesting client (e.g. a web browser or aggregator) what type of data to expect.
The charset property can be configured if you want to change the encoding of the data that blojsom sends back to the requesting client. You are safe choosing UTF-8 as the character set.

As you can see from the above configuration, each template filename ends with a .vm extension. This creates the association or binding between that flavor template and the particular dispatcher. In this case, all of the templates will be dispatched or handled by the Velocity dispatcher. If you had changed the html flavor to be as follows:

html=html.jsp, text/html;charset=UTF-8

blojsom would look for the filename, html.jsp in the user's /WEB-INF/(blog-id)/templates directory.

Configuring flavors through the administration console

Using the blojsom administration console, you can add, modify, and delete flavors from your blog. All of these options are available from the Edit blog flavors link of the main menu after logging into the administration console.

Adding a flavor

If you are adding a new flavor, you need to provide a name for the flavor in addition to its MIME content type and character encoding. Select from one of the available templates and click the Add blog flavor button to add the flavor. You can now see the new flavor on your blog by adding ?flavor=flavor_name to the end of the URL to your blog. For example, http://your.blog.com/blojsom/blog/default/?flavor=geek.

As of blojsom 2.15, there is not currently a way to upload new templates to the system. This capability will be addressed in a future version of blojsom.

Modifying a flavor

If you are modifying an existing flavor on your blog, you need to provide the same information as when you are adding a flavor to your blog.

Deleting a flavor

You can delete any flavor on your blog except for the default flavor that is configured in your blog properties. Also, deleting flavors from your blog does not delete the corresponding template file.