<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
<document>
<header>
<title>Customization</title>
</header>
<body>
<section>
<title>Categories</title>
<p>The default or "/" category has special meaning for blojsom. This category acts as an
"aggregator" whereby it can be mapped to display entries from all or a subset of your blog
categories.
</p>
<p>
By default, the
<em>blog-default-category-mapping</em> property in your individual
<code>blog.properties</code>
does not contain a value. This means that all your blog categories will be aggregated if someone
requests the default or "/" category. blojsom will obey the
<em>blog-directory-depth</em> parameter
so that
only blog directories will be aggregated to that directory depth. blojsom will also obey the
<em>blog-entries-display</em> parameter so that only that number of blog entries will be aggregated
for the
individual blog directories.
</p>
<p>
The
<em>blog-default-category-mapping</em> parameter takes a comma-separated list of blog directories
underneath
your
<em>blog-home</em>. The following configuration for
<em>blog-default-category-mapping</em> will
aggregate
</p>
<source>
blog-default-category-mapping=/java, /osx, /politics/voting
</source>
<p>the "/java", "/osx", and "/politics/voting" categories if someone requests the default or "/" category.
</p>
<p>
</p>
</section>
<section>
<title>Flavor-based default category mapping</title>
<p>
Starting with blojsom 1.4, you have the ability to configure a default category mapping based on
the particular flavor. The default flavor, HTML, will still be mapped using the
<em>blog-default-category-mapping</em>
parameter. However, if you would like to configure the RSS flavor to map a different set of
categories than
the HTML flavor for the default or "/" category, then you can add a line such as
</p>
<source>
rss.blog-default-category-mapping=/blojsom, /java
</source>
<p>to your individual
<code>blog.properties</code> file. In this case, the "/blojsom" and "/java" categories will be
aggregated if someone requests the RSS flavor for the default or "/" category.
</p>
</section>
<section>
<title>blojsom context</title>
<p>
There are a number of objects that get placed in a "Context" that is used by the particular
dispatcher handling the template for a requested flavor. A concrete instance of BlojsomDispatcher
will use this "Context" map and make the objects in it available, as appropriate, for the particular
presentation technology. For example, in the JSPDispatcher, the objects from this "Context" are placed
on the request using the setAttribute method.
</p>
<p>
However, you as a user should be aware of the name and type of objects that are available in the
"Context". You can see examples of how they are accessed by looking at the html.jsp (JSP page for the
html flavor) and html.vm (Velocity template for the html flavor).
</p>
<table>
<tr>
<th>Key</th>
<th>Object type</th>
</tr>
<tr>
<td>"BLOJSOM_BLOG"</td>
<td>org.blojsom.blog.Blog</td>
</tr>
<tr>
<td>"BLOJSOM_ENTRIES"</td>
<td>org.blojsom.blog.BlogEntry[]</td>
</tr>
<tr>
<td>"BLOJSOM_CATEGORIES"</td>
<td>org.blojsom.blog.BlogCategory[]</td>
</tr>
<tr>
<td>"BLOJSOM_REQUESTED_CATEGORY"</td>
<td>org.blojsom.blog.BlogCategory</td>
</tr>
<tr>
<td>"BLOJSOM_SITE_URL"</td>
<td>java.lang.String</td>
</tr>
<tr>
<td>"BLOJSOM_DATE"</td>
<td>java.lang.String (RFC-822 format)</td>
</tr>
<tr>
<td>"BLOJSOM_DATE_ISO8601"</td>
<td>java.lang.String</td>
</tr>
<tr>
<td>"BLOJSOM_DATE_OBJECT"</td>
<td>java.util.Date</td>
</tr>
<tr>
<td>"BLOJSOM_COMMENTS_ENABLED"</td>
<td>java.lang.Boolean</td>
</tr>
<tr>
<td>"BLOJSOM_PERMALINK"</td>
<td>java.lang.String</td>
</tr>
</table>
</section>
<section>
<title>blojsom category meta-data</title>
<p>
In blojsom 1.1, a per-category meta-data facility was added to blojsom. A configuration
property in your individual
<em>blog.properties</em> was added,
<em>blojsom-properties-extensions</em>, which
defaults to
<code>.properties</code>. As blojsom traverses the blog home directory looking for entries,
it will also look for files with the extensions listed in
<em>blojsom-properties-extensions</em>. If
a file matching an extension listed in this configuration property is found, it will be loaded and
stored as meta-data information for that category. The properties files
<strong>must</strong> adhere to the
restrictions for Java .properties files.
</p>
<p>
A sample
<code>category.properties</code> file in the blog home directory might look like:
</p>
<source>
blojsom.name=the aggregator
blojsom.description=This is a long description for the aggregator category
</source>
<p>There are two reserved properties for blojsom,
<em>blojsom.name</em> and
<em>blojsom.description</em>.
These two properties can be used to set another descriptive name for the current blog category and to
provide a detailed description of the entries in that category. Other properties can be extracted by
calling the
<em>BlogCategory.getMetaData()</em> method and then looking for the particular property in
the returned HashMap.
</p>
<p>
As a user, you can use the meta-data in any way you like. For example, besides an alternate name and
description, you could have per-category colors or other personalization features that are extracted
by the proper template. An example of printing out a category's alternate name, if found in the category
meta-data for a category, is given in the Velocity template for the HTML flavor,
<code>html.vm</code>.
</p>
<p>
<link href="screenshots/blojsom-screenshot.jpg">Click here</link> for a screen shot of the meta-data
facility in
action. Look for the string, "the aggregator".
</p>
</section>
<section>
<title>blojsom entry meta-data</title>
<p>
In blojsom 1.9, a per-entry meta-data facility was added to blojsom. A configuration property
in your individual
<code>blog.properties</code> was added,
<em>blog-entry-meta-data-extension</em>. There is no
default value for this property. If it is left blank, blojsom will not try to look for meta-data
for a blog entry. blojsom looks for the appropriate meta-data file by taking the blog entry
filename, stripping off its original extension, and adding the extension indicated by this
property.
</p>
<p>
As an example, if this property was set to
<code>.properties</code> and you had a blog entry
titled,
<em>some-blog-entry.html</em>, blojsom would look for
<em>some-blog-entry.properties</em>.
</p>
<p>
In the standard release of blojsom, the meta-data file must be a Java
.properties file. The properties file
<strong>must</strong> adhere to the restrictions for Java
.properties files.
</p>
<p>
As a user, you can use the meta-data in any way you like.
</p>
</section>
<section>
<title>blojsom flavor and template customization</title>
<p>
In blojsom, you have the ability to configure both the flavor and the template mechanism. Why would
you want to do this? Well, out of the box, blojsom can generate a few simple flavors for people to
view your blog, HTML and RSS. However, these flavors may be insufficient to "describe" your blog and
you may also want to use a particular presentation technology for rendering your blog.
</p>
</section>
<section>
<title>Configuring blojsom flavors</title>
<p>blojsom flavors are configured in
<code>/WEB-INF/(user-id)/flavor.properties</code>. Here is a sample of what the file looks
like when you download blojsom.
</p>
<source>
html=html.vm, text/html
rss=rss.vm, text/xml
</source>
<p>Each line represents a configuration of
<em>flavor</em>=
<em>flavor template filename</em>,
<em>flavor content type</em>. In this configuration, the
<em>html</em> flavor uses the
<code>html.vm</code> template and also uses a content type of
<em>text/html</em>. Each line must also
follow this configuration of
</p>
<source>
flavor=flavor template filename, flavor content type
</source>
<p>
This is the first half of the flavor/template equation. If you wanted to have the HTML flavor
for your blog rendered using JavaServer Pages (JSP), you can do this.
</p>
<p>
</p>
</section>
<section>
<title>Configuring blojsom dispatchers</title>
<p>blojsom dispatchers are configured in
<code>WEB-INF/dispatcher.properties</code>. Here is what the file
looks like when you download blojsom.
</p>
<source>
jsp=org.blojsom.dispatcher.JSPDispatcher
vm=org.blojsom.dispatcher.VelocityDispatcher
</source>
<p>Each line represents a configuration of
<em>template extension</em>=
<em>fully qualified
dispatcher classname</em>. For the template dispatcher to be configured correctly, the template
extension must be present in one of the configured flavors.
</p>
<p>
In the above configuration, the
<em>html</em> flavor is handled by the
<code>html.vm</code> template
which is dispatched by the
<em>org.blojsom.dispatcher.VelocityDispatcher</em>. Got that?
OK, well, let's say you wanted to use the JSP template for the HTML flavor to render your blog.
Here's how that configuration would look for the
<code>flavor.properties</code> and
<code>dispatcher.properties</code>, respectively.
</p>
<p>
<em>flavor.properties</em>
</p>
<source>
html=html.jsp, text/html
rss=rss.vm, text/xml
</source>
<p>
<em>dispatcher.properties</em>
</p>
<source>
jsp=org.blojsom.dispatcher.JSPDispatcher
vm=org.blojsom.dispatcher.VelocityDispatcher
</source>
<p>OK. So, one simple change to the
<code>flavor.properties</code> file and no change to the
<code>dispatcher.properties</code>. That's it. It's that simple!
</p>
<p>
</p>
</section>
<section>
<title>Writing a blojsom custom dispatcher</title>
<p>
For now, check out the
<a href="javadoc/index.html">javadocs</a> and the source code for the
JSPDispatcher and VelocityDispatcher. It's pretty straightforward.
</p>
<p>
</p>
</section>
<section>
<title>blojsom logging customization</title>
<p>
blojsom uses
<link href="http://jakarta.apache.org/commons/logging.html">Jakarta Commons Logging</link> to
do logging. blojsom also ships with
<link href="http://jakarta.apache.org/log4j/docs/index.html">Log4J
</link> as its logging package. In the
<code>/WEB-INF/classes</code> directory, you will find a file called
<code>log4j.properties</code>. Developers who have downloaded blojsom from CVS will find this file in the
directory where blojsom was checked out to in
<em>/properties</em>.
</p>
<p>
You may edit the
<code>log4j.properties</code> file to configure logging in blojsom as per your needs. How
ever, Log4J configuration is out of the scope of this document, so you should refer to the
<link href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</link> website for documentation on configuring
Log4J.
</p>
<p>
However, if you would like to turn off blojsom debugging log messages, you can change the following
statement in
<em>log4j.properties</em>:
</p>
<source>
log4j.rootLogger=DEBUG, stdout
</source>
<p>to</p>
<source>
log4j.rootLogger=INFO, stdout
</source>
<p>
This will ensure that only information messages get logged by blojsom.
</p>
</section>
</body>
</document>