Feeds configuration
Files
All files, from which feed definitions will be read, should be located in the <portal-name>/feeds directory, and should have a name ending with -feeds.xml. One feeds xml file defines one feeds group, as it later appears in the portlet. Feeds from one file can reference feeds from other files. All files should follow this schema:
<?xml version="1.0" encoding="iso-8859-1"?> <feeds display-name="Name"> Feed definitions </feeds>
The display-name attribute is the name of the group as it will appear in the portlet (group heading).
Each feed has a name and a type. For now, supported types are: rss2, atom, rdf. Each feed can be accessed in the same way, using this address: /feeds/<feed-name>/<feed-type>. Note that <feed-name> can contain /.
There are 3 types of feeds, all desribed below.
1. Remote feeds
Remote feeds are feeds which are downloaded from a given location and made available by the portlet/ servlet.
The definition should look like this:
<remote-feed name="<feed-name>" display-name="display name" address="feed address" project-level="project level" type="rss2,atom,rdf" />
Meaning of the attributes is (all are required, unless marked):
name - name of the feed, can contain $The specified item was not found. .
display-name - name of the feed as it will be displayed in the portlet, can contain $The specified item was not found. , ${project-name} .
address - address from which this feed can be downloaded. Can contain special strings: $ and $The specified item was not found. , which will be replaced by the feed type and project id (the latter only if project-level is specified).
project-level - optional. Allows you to generate feeds for all projects that have the given level. If this is equal to , then all projects ids, that are available without logging in, will be subsituted for it.
type - types of the feed that are available. Can be single, multiple (comma-separated), or equal to , which means - all types.
So, as you can see, with one definition you can define in fact many feeds - with multiple types and for multiple projects.
2. Aggregated feeds
Aggreagated feeds are feeds composed of entries taken from several other feeds, which must also be defined in the feeds servlet.
Again, schema first:
<aggregated-feed name="<feed-name>" display-name="display name" title="feed title" description="feed description" author="feed author"> <include name="feed-name 1" ></include> <include name="feed-name 2" ></include> ... </aggregated-feed>
Attributes:
name, display-name - as before
title, description, author - these are parameters of the feed, which will be put in the resulting xml.
Tag body:
<include name="feed-name x" /> - this includes a feed to the constructed feed. Any feed can be included - also an aggregated one.
Entries in the resulting feed will be sorted descendingly by date. The resulting feed will be available in types, in which all of the included feeds are available (so there is no conversion between types - a feed of type x is constructed only from other feeds of type x).
3. Shotoku feeds
Shotoku feeds are feeds generated basing on a node list, which is generated by a specified node search.
Schema:
<shotoku-feed name="<feed-name>" display-name="display-name" type="rss2" prefix="content manager prefix" template="velocity template" author="feed author" title="feed title" description="feed description" link-base="address"> <search> <directory path="test" ></directory> <property-sort name="sort" ></property-sort> <limit limit="3" ></limit> </search> </shotoku-feed>
Attributes:
name, display-name - as before.
type - type of the resulting feed. Can be single, multiple or .
prefix - prefix, which will be prepended to template and each path in the main feed definition. As both the template and the nodes and directories which are later referenced in feed description are located in shotoku, you can think of this as a prefix of a backing ContentManager. Optionally, you can also set the id attribute.
template - template, which will be used to generate the feed. Available fields are described below. The template should be corresponding to the set feed type. The template will be first searched for in shotoku, later in other defined resource loaders. Can contain $.
dateFormat - optional, will be used to initialize the dateFormat object which is passed to velocity. Defaults to MM/dd/yy.
project-level - if the feed is to be generated iteratively for all projects on the given level.
title, description, author, link-base - custom attributes, which are passed to the velocity template. All of these are optional. You can also add any other attributes, which will be later available as variables in velocity's template. Can contain $The specified item was not found. , ${project-name} .
Tag body:
The tag body should consist of one or more <search> tags. Each of them will generate a list of nodes, according to the content of its body. Also, each such top-level <search> tag should have a name attribute (it can be ommited for one tag, then the defualt name="nodes" is assumed). This attribute is the name of the variable under which the list resulting from the search will be visible. In a <search> tag, each child tag is a directive, telling what should be done with a list that was generated by the previous tags. All attributes of child tags can contain $The specified item was not found. . These tags are:
<directory path="path/to/directory" /> - includes, to the result list, all nodes from the given directory.
<history path="path/to/node" /> - includes history of the given nodes (history is, of course, represented by nodes also).
<limit limit="10" /> - limits the size of the result list to the given number.
<property-sort name="property name" descending="true" /> - sorts the result list by the given property (taking its value). The descending parameter is optional.
<date-sort /> - sorts the result list by date, descending (newest first).
<search> - a sub-search, the list resulting from it will be appended to the current result list. Can contain any of the tags mentioned here as children.
<property-value name="property-name" value="property-value" /> - in the result list, leaves only the nodes, which have the given property set to the given value.
<and>, <or> - logical operators, with which <property-value ... /> tags can be grouped, with an obvious semantics.
Velocity template variables:
$link - a link to the feed, auto-generated.
$dateFormat - a custom date format to format dates.
$rssDateFormat - a date format conforming to RFC 822, used for ex. in rss 0.9x, 2.0 feeds.
$rdfDateFormat - a date format conforming to RFC 3339, used for ex. in atom and rdf feeds.
$now - current date (java.util.Date object).
$baseServerAddress - base address of the server on which this feed is generated (http://www.server.com).
all additional attributes of the <shotoku-feed> tag.
lists of nodes, which are the result of the search defined in the tag's body, visible under the names as defined in the tag's attribute. These nodes are instances of the org.jboss.shotoku.Node interface.
an $escape object, with two methods:
$escape.all(text) - escapes /, //, &, <, >, "
$escape.tags(text) - escapes <, >
Example search and its meaning:
A search:
<directory path="test1" ></directory> <property-sort name="sort" ></property-sort> <directory path="test2" ></directory> <date-sort ></date-sort> <limit limit="20" ></limit>
Means the following:
Take all nodes from directory test1
Sort them by their values of property sort
Add all nodes from directory test2
Sort everything wrt last modification date
Leave first 20 nodes (in the case, 20 newest ones)
Example velocity template (for rss2):
<?xml version="1.0"?>
<rss version="2.0">
<channel>
<title>$title</title>
<link>$link</link>
<description>$description</description>
<language>en</language>
<docs>http://blogs.law.harvard.edu/tech/rss</docs>
<generator>Shotoku</generator>
<managingEditor></managingEditor>
<webMaster></webMaster>
<pubDate>$dateFormat.format($now)</pubDate>
</channel>
#foreach($node in $nodes)
<item>
<title>$node.getProperty("title")</title>
<link>${link-base}$prefix/$node.getName()</link>
<description>$node.getContent()</description>
<guid>${link-base}$prefix/$node.getName()</guid>
<pubDate>$dateFormat.format($node.getLastModificationDate())</pubDate>
</item>
#end
</rss>
Comments