org.clapper.curn.output.freemarker
Class FreeMarkerOutputHandler

java.lang.Object
  org.clapper.curn.output.FileOutputHandler
      org.clapper.curn.output.freemarker.FreeMarkerOutputHandler

All Implemented Interfaces:

OutputHandler

public class FreeMarkerOutputHandler
extends FileOutputHandler

Provides an output handler that uses the FreeMarker template engine to generate output. In addition to the configuration parameters supported by the FileOutputHandler base class, this handler supports the following additional configuration variables, which must be specified in the handler's configuration section.

Parameter	Explanation	Default
AllowEmbeddedHTML	Whether or not to pass embedded HTML to the FreeMarker template	false
MimeType	The MIME type of the document produced by the template. (See TemplateFile, below.) Required for all template types except "builtin".	None
TOCItemThreshold	The total number of items (not feeds, but individual items) that must be displayed before curn will generate a table of contents header. A value of 0 means "generate a table of contents regardless of how many items are displayed." The FreeMarker template is not obligated to honor this parameter. (Note, though, that the default FreeMarker HTML template does honor it.)	infinite (i.e., no table of contents is generated)
Title	Document title to pass to the template.	"RSS Feeds"
TemplateFile	Specifies the location of the FreeMarker template file. The location is specified with two white space-delimited fields: A type, which may be "file", "classpath", "url" or "builtin" An identifier string The form of the identifier string depends on the type value. For the "file" type, the identifier must be the path to the template file, on the machine where curn is running. For the "classpath" type, the identifier must be a relative path to a template file that can be found by searching the jar files and directories in the class path. For the "url" type, the identifier must be a valid URL. For the "builtin" type, the identifier can be one of three values: "html", "summary" or "text" Examples: file c:\curn\html.ftl url http://localhost/html.ftl classpath org/clapper/curn/output/freemarker/HTML.ftl builtin html Note: builtin html is short-hand for classpath org/clapper/curn/output/freemarker/HTML.ftl builtin text is short-hand for classpath org/clapper/curn/output/freemarker/Text.ftl builtin summary is short-hand for classpath org/clapper/curn/output/freemarker/Summary.ftl But, use the "builtin" form, rather than the "classpath" form, to refer to the built-in templates; if the locations of the built-in templates change in the future, your curn configuration file won't break if you're using the "builtin" forms.	"RSS Feeds"

This handler builds a FreeMarker data model; each call to displayChannel() adds the data for a channel to the data structure. When the flush() method is invoked, this handler loads the FreeMarker template and feeds it the FreeMarker data model, producing the output. The FreeMarker template can produce any kind of document; this handler doesn't care.

The FreeMarker Data Model

This handler builds the following FreeMarker data model tree.

 Tree                                         Description

 (root)
  |
  +-- curn
  |    |
  |    +-- showToolInfo                       (boolean) whether or not
  |    |                                      to display curn information
  |    |                                      in the output
  |    |
  |    +-- version                            version of curn
  |    |
  |    +-- buildID                            curn's build ID
  |
  +-- totalItems                              total items for all channels
  |
  +-- dateGenerated                           date generated
  |
  +-- extraText                               extra text, from the config
  |
  +-- encoding                                encoding, from the config
  |
  +-- tableOfContents                         hash of TOC data
  |    |
  |    +-- needed                             whether a TOC is needed
  |    |
  |    +-- channels                           sequence of channel TOC
  |          |                                items
  |          |
  |          +-- (channel)                    TOC entry for one channel
  |                |
  |                +-- title                  channel title
  |                |
  |                +-- url                    channel URL (from the XML)
  |                |
  |                +-- configuredURL          channel/feed URL from the
  |                |                          config file
  |                |
  |                +-- totalItems             total items in channel
  |                |
  |                +-- channelAnchor          HTML anchor for channel
  |
  +-- channels                                sequence of channel data
         |
         +-- (channel)                        hash for a single channel
                 |
                 +-- index                    channel's index in list
                 |
                 +-- totalItems               total items in channel
                 |
                 +-- title                    channel title
                 |
                 +-- anchorName               HTML anchor for channel
                 |
                 +-- url                      channel's URL
                 |
                 +-- date                     channel's last-modified date
                 |                            (might be missing)
                 |
                 +-- items                    sequence of channel items
                       |
                       +-- (item)             entry for one item
                             |
                             +-- index        item's index in channel
                             |
                             +-- title        item's title
                             |
                             +-- url          item's unique URL
                             |
                             +-- date         the date
                             |                (might be missing)
                             |
                             +-- author       the author (might be missing)
                             |
                             +-- description  description/summary
 

In addition, the data model provides (at the top level) the following methods:

 (root)
  |
  +-- wrapText (string[, indentation[, lineLength]])
  |
  +-- indentText (string, indentation)
  |
  +-- stripHTML (string)
 

Version:

$Revision: 6504 $

See Also:

OutputHandler, FileOutputHandler, Curn, RSSChannel

Field Summary

static TemplateLocation	BUILTIN_HTML_TEMPLATE Built-in HTML template.
static TemplateLocation	BUILTIN_SUMMARY_TEMPLATE Built-in summary template
static TemplateLocation	BUILTIN_TEXT_TEMPLATE Built-in text template
static java.lang.String	CFG_BUILTIN_HTML_TEMPLATE Configuration keyword: Built-in HTML template
static java.lang.String	CFG_BUILTIN_SUMMARY_TEMPLATE Configuration keyword: Built-in summary template
static java.lang.String	CFG_BUILTIN_TEXT_TEMPLATE Configuration keyword: Built-in text template
static java.lang.String	CFG_EXTRA_TEXT Configuration variable: extra text
static java.lang.String	CFG_TEMPLATE_FILE Configuration variable: template file
static java.lang.String	CFG_TEMPLATE_LOAD_BUILTIN Configuration keyword for built-in template
static java.lang.String	CFG_TEMPLATE_LOAD_FROM_CLASSPATH Configuration keyword for template loading from classpath
static java.lang.String	CFG_TEMPLATE_LOAD_FROM_FILE Configuration keyword for template loading from file
static java.lang.String	CFG_TEMPLATE_LOAD_FROM_URL Configuration keyword for template loading from URL
static java.lang.String	CFG_TITLE Configuration variable: title
static java.lang.String	CFG_TOC_ITEM_THRESHOLD Configuration variable: table-of-contents item threshold

Fields inherited from class org.clapper.curn.output.FileOutputHandler

CFG_ENCODING, CFG_SAVE_AS, CFG_SAVE_ONLY, CFG_SAVED_BACKUPS, CFG_SHOW_CURN_INFO

Constructor Summary

FreeMarkerOutputHandler()
Construct a new FreeMarkerOutputHandler.

Method Summary

void	displayChannel(RSSChannel channel, FeedInfo feedInfo) Display the list of RSSItem news items to whatever output is defined for the underlying class.
void	flush() Flush any buffered-up output.
java.lang.String	getContentType() Get the content (i.e., MIME) type for output produced by this output handler.
void	initOutputHandler(CurnConfig config, ConfiguredOutputHandler cfgHandler) Initializes the output handler for another set of RSS channels.

Methods inherited from class org.clapper.curn.output.FileOutputHandler

displayToolInfo, getGeneratedOutput, getName, getOutputEncoding, getOutputFile, hasGeneratedOutput, init, openOutputFile, savingOutputOnly, setName, setOutputEncoding

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CFG_EXTRA_TEXT

public static final java.lang.String CFG_EXTRA_TEXT

Configuration variable: extra text

See Also:

Constant Field Values

CFG_TITLE

public static final java.lang.String CFG_TITLE

Configuration variable: title

See Also:

Constant Field Values

CFG_TOC_ITEM_THRESHOLD

public static final java.lang.String CFG_TOC_ITEM_THRESHOLD

Configuration variable: table-of-contents item threshold

See Also:

Constant Field Values

CFG_TEMPLATE_FILE

public static final java.lang.String CFG_TEMPLATE_FILE

Configuration variable: template file

See Also:

Constant Field Values

CFG_TEMPLATE_LOAD_BUILTIN

public static final java.lang.String CFG_TEMPLATE_LOAD_BUILTIN

Configuration keyword for built-in template

See Also:

Constant Field Values

CFG_BUILTIN_HTML_TEMPLATE

public static final java.lang.String CFG_BUILTIN_HTML_TEMPLATE

Configuration keyword: Built-in HTML template

See Also:

Constant Field Values

CFG_BUILTIN_TEXT_TEMPLATE

public static final java.lang.String CFG_BUILTIN_TEXT_TEMPLATE

Configuration keyword: Built-in text template

See Also:

Constant Field Values

CFG_BUILTIN_SUMMARY_TEMPLATE

public static final java.lang.String CFG_BUILTIN_SUMMARY_TEMPLATE

Configuration keyword: Built-in summary template

See Also:

Constant Field Values

CFG_TEMPLATE_LOAD_FROM_CLASSPATH

public static final java.lang.String CFG_TEMPLATE_LOAD_FROM_CLASSPATH

Configuration keyword for template loading from classpath

See Also:

Constant Field Values

CFG_TEMPLATE_LOAD_FROM_URL

public static final java.lang.String CFG_TEMPLATE_LOAD_FROM_URL

Configuration keyword for template loading from URL

See Also:

Constant Field Values

CFG_TEMPLATE_LOAD_FROM_FILE

public static final java.lang.String CFG_TEMPLATE_LOAD_FROM_FILE

Configuration keyword for template loading from file

See Also:

Constant Field Values

BUILTIN_HTML_TEMPLATE

public static final TemplateLocation BUILTIN_HTML_TEMPLATE

Built-in HTML template.

BUILTIN_TEXT_TEMPLATE

public static final TemplateLocation BUILTIN_TEXT_TEMPLATE

Built-in text template

BUILTIN_SUMMARY_TEMPLATE

public static final TemplateLocation BUILTIN_SUMMARY_TEMPLATE

Built-in summary template

Constructor Detail

FreeMarkerOutputHandler

public FreeMarkerOutputHandler()

Construct a new FreeMarkerOutputHandler.

Method Detail

initOutputHandler

public void initOutputHandler(CurnConfig config,
                              ConfiguredOutputHandler cfgHandler)
                       throws org.clapper.util.config.ConfigurationException,
                              CurnException

Initializes the output handler for another set of RSS channels.

Specified by:

initOutputHandler in class FileOutputHandler

Parameters:

config - the parsed curn configuration data

cfgHandler - the ConfiguredOutputHandler wrapper containing this object; the wrapper has some useful metadata, such as the object's configuration section name and extra variables.

Throws:

org.clapper.util.config.ConfigurationException - configuration error

CurnException - some other initialization error

displayChannel

public void displayChannel(RSSChannel channel,
                           FeedInfo feedInfo)
                    throws CurnException

Display the list of RSSItem news items to whatever output is defined for the underlying class. This handler simply buffers up the channel, so that flush() can pass all the channels to the script.

Specified by:

displayChannel in interface OutputHandler

Specified by:

displayChannel in class FileOutputHandler

Parameters:

channel - The channel containing the items to emit. curn will pass a copy of the actual RSSChannel object, so the output handler can edit its contents, if necessary, without affecting other output handlers.

feedInfo - Information about the feed, from the configuration

Throws:

CurnException - unable to write output

flush

public void flush()
           throws CurnException

Flush any buffered-up output.

Specified by:

flush in interface OutputHandler

Specified by:

flush in class FileOutputHandler

Throws:

CurnException - unable to write output

getContentType

public java.lang.String getContentType()

Get the content (i.e., MIME) type for output produced by this output handler.

Specified by:

getContentType in interface OutputHandler

Specified by:

getContentType in class FileOutputHandler

Returns:

the content type

See Also:

OutputHandler.hasGeneratedOutput(), OutputHandler.getGeneratedOutput()