LinkList (blogroll) plugin for blojsom

This document is released as part of the iCite net » software »
sub-projects for blojsom » LinkList for blojsom » version 1.1

created by: Jay Fienberg, updated: May 11, 2005

table of contents:

getting started—it's pretty easy:

  1. Intro: what it is
  2. Simple blogroll, quickest install how-to
  3. Where to download it
  4. Upgrading to the latest version

almost everything you'd ever want to know about it:

  1. Why isn't it just called the "blogroll plugin"
  2. How it works (in brief)
  3. Features (overview)
  4. Suggested uses
  5. Requirements and dependencies
  6. Installation, how to
  7. LL4blojsom files and Javadocs
  8. Creating a linklist, how to
  9. Using linklists in your templates, how to
  10. Advanced template examples, including FOAF
  11. Linklist properties files, how to
  12. WTF, the linklist source (e.g., linklist.txt) format
  13. Why the linklist source format isn't XML / OPML / RDF, etc.
  14. Default Base (WTFBase) and fallback linklist sources
  15. Roadmap, to-do's and known limitations
  16. Releases / changelist
  17. Credits and thank you's
  18. License and copyright info

Intro: what it is:
The LinkList plugin (aka LL4blojsom) adds a simple way for any blojsom blog to have one or more general purpose, easy to update, lists—typically useful for blogrolls. Many blogs have blogrolls, which are lists of links to other blogs. Usually, a blogger will link to other sites they regularly read and/or related sites and/or friends' sites.

Additionally, the LinkList plugin has a number of advanced configuration features that allow blogs to share lists (including over the web) and for administrators of multiuser blojsom installations (e.g., in an enterprise setting) to centrally manage lists used across all blogs or groups of blogs.

back to top

Simple blogroll, quickest install how-to:
At this time, in order to install the LL4blojsom plugin, you need to basically know your way around your blojsom WEB-INF directory and basically need to know how to edit your main blojsom HTML template.

  1. Download the current (more info)
  2. unzip into an easy to find directory
  3. copy the lib/*.jar files to your blojsom WEB-INF/lib/ directory
  4. copy the ll_blog_level/linklist.txt file to your blojsom blog-level WEB-INF/blog/ directory
  5. copy the templates/ll_html.vm file to your blojsom blog-level WEB-INF/blog/templates/ directory
  6. in the blojsom install, WEB-INF/, add a line referencing the plugin: linklist=net.icite.blojsom.plugin.LinkListPlugin
  7. * in the blog-level file, WEB-INF/blog/, add a linklist to the HTML flavor template: html.blojsom-plugin-chain=linklist
  8. * in the place where you'd like your blogroll, add this "include" line to your html.vm (in the same templates directory) : #parse("ll_html.vm")
  9. **restart blojsom
  10. if everything looks good, you can edit that linklist.txt file to add listings to your blogroll (a web admin interface is forthcoming)

* these steps alternately may be performed through the blojsom web admin interface, though you will need to restart blojsom to make the linklist plugin available to web admin

** if you are using blojsom web admin and have already restarted, you should not need to restart again

back to top

Where to download it:
LL4blojsom can be downloaded from the iCite net nuggets project on Please download the latest release of the "LinkList for blojsom" package on the project's file download page.

The download you need is the file (where x.x is the version number—the biggest number is most current).

back to top

Upgrading to the latest version
For a version 1.0 to 1.1 upgrade, you may simply delete the icite-LL4blojsom-1.0.jar in your WEB-INF/lib directory, download the single icite-LL4blojsom-1.1.jar, copy it to your WEB-INF/lib directory, and restart blojsom.

You may also essentially re-install LL4blojsom, as follows:

  1. delete the old icite-LL4blojsom-x.x.jar and icite-WTF-x.x.jar files from your WEB-INF/lib directory
  2. follow steps 1–5 of the quick install directions—be sure to not copy over any of your changed LL4blojsom template files or your linklist.txt files that you want to keep!
  3. restart blojsom

back to top

Why isn't it just called the "blogroll plugin":
The LinkList plugin is designed with blogrolls in mind, but it works with a pretty general idea of a list of links (and, even, a list in general). So, there are other types of lists of links that someone might want to have on a blog, including: a navigation menu, a list of contacts, a simple link blog, a music playlist, and others.

Because these lists are displayed using blojsom templates, more data-oriented templates like OPML, FOAF, RSS, ATOM, M3U, XOXO, and XSPF can be used to publish any list in one or more of these common data interchange formats.

back to top

How it works (in brief):
The LinkList plugin is to design to fit in with blojsom's approach to using simple text files as the foundation for all aspects of configuration and contents. So, the basic idea is: install the plugin in blojsom and create a linklist.txt file in the right format and right place, plus add a little code to your blojsom templates, and you are good to go.

The LinkList plugin can be activated on a per blog basis in blojsom, plus configured with global settings that work across all blogs. Globally and for each user, an optional file can be used to configure different features of the plugin and file name(s) and location(s) for the lists.

(Note: the LinkList Plugin is being designed so that the list storage mechanism can be pluggable. In future versions, it should be possible to store all lists in a database, or in different file formats, like XML.)

back to top

Features (overview):

Note: items marked with a * are only partially implemented at this time. Most everything is in place to turn on these features, but they don't work or are only partially functional at this time.

back to top

Suggested uses:

back to top

Requirements and dependencies:
The LinkList plugin for blojsom has been created and tested with blojsom 2.20. It should work with any more recent versions of blojsom with not problems. It may work with any blojsom versions that support multiple users (as far back as 2.0??), but it has not been tested with any of them.

The LinkList plugin makes use of the Apache Jakarta Commons Collections (version 3.1 or later) and Lang (version 2.0 later) libraries. See installation instructions for details.

back to top

Installation, how to:
First see the new quick install instructions above. What follows are more details.

The contains a /lib directory with four jars, the icite-LL4blojsom-x.x.jar, icite-WTF-x.x.jar, and the Apache Jakarta commons-lang-2.0.jar and commons-collections-31.jar. Place these three jars in the blojsom WEB-INF/lib directory.

In the blojsom install, i.e., WEB-INF/, add a line referencing the plugin:


Next, add linklist to each individual blog(s) plugin chain in the individual blog(s) file, i.e., in WEB-INF/blog/, to add a linklist to the HTML flavor template, add:


Note: the linklist plugin is not dependent on any other plugin, and it may appear anywhere in the plugin chain for any flavor.

Note: You will need to restart blojsom for these changes to take effect.

back to top

LL4blojsom files and Javadocs
The LL4blojsom download includes a number of required and/or useful files. These are:

back to top

Creating a linklist, how to:
Again, please first see the new quick install instructions above. What follows are more details.

All blog-level linklist sources should be placed in the main directory of each blog using the LL4blojsom plugin, i.e., WEB-INF/blog/.

At this point, please see the sample blog-level linklist sources (which are in the ll_blog_level directory of the LL4blojsom download): linklist.txt, linklist_cats.txt and linklist_xfn_foaf.txt.

All global linklist sources should be placed in the main blojsom install directory, i.e., WEB-INF.

There are example global linklist sources that do not show off any features of the source format, but which are useful in showing how LL4blojsom handles fallback to global sources when blog-level sources aren't available. These global linklist sources (which are in the ll_global_level directory of the LL4blojsom download) are: linklist.txt and ll_fallback.txt

back to top

Using linklists in your templates, how to:
Again, please first see the new quick install instructions above. What follows are more details.

All linklist templates should be placed in the templates directory of each blog using the LL4blojsom plugin, i.e., WEB-INF/blog/templates.

The linklist template examples (which are in the templates directory of the LL4blojsom download) have all been created using Velocity templates. You may "include" blogroll templates into your main templates (e.g., html.vm) like #parse("ll_html.vm").

At this point, please see the linklist HTML sample templates: ll_html.vm (simplest) and ll_examples.vm (shows a number of options).

You can add #parse("ll_examples.vm") to your html.vm to see how various options are displayed. Note that this requires that you also install all the linklist source examples and

As with other blojsom plugin template features, you also can use the linklist template features directly within other templates. But, the "include" method is a nice, modular, way to make use of the linklist plugin features in templates.

Note: all of LL4blojsom's ...FromSource() methods, that you might notice in the templates, are designed to make use of Velocity's means of creating an array, which is technically a Java ArrayList. So, these methods expect an ArrayList of sources as a parameter.

This shows up like #set($sourceList = ["xfnfoaf"]) in the templates, in this case, because only a single source is set. With multiple sources, it might look like: #set($sourceList = ["src1", "src2", "src3"]).

This then gets followed by some use of the $sourceList array, as in:

#foreach($listing in $l.getListingsFromSource($sourceList))

back to top

Advanced template examples, including FOAF:
The linklist template examples (which are in the templates directory of the LL4blojsom download) also include sample OPML and FOAF templates, which are ll_opml.vm and ll_foaf.vm. These are meant to be used as their own blojsom flavors.

As with the other templates, these linklist templates should be placed in the templates directory of each blog using the LL4blojsom plugin, i.e., WEB-INF/blog/templates.

You will want to then add new flavors for FOAF and OPML. These should be added to each blog's WEB-INF/blog/ (or, via blojsom web admin) as:

opml=opml.vm, text/xml;charset=UTF-8
foaf=foaf.vm, application/rdf+xml;charset=UTF-8

Note: if, for debugging or experimentation, you want to be able to visually see the output from these plugins in your web browser, change the mime-types to text/plain (though text/xml may be sufficient as well). But, to conform to web standards, be sure to change these back to the above types when you go live on the web.

For each new flavor, be sure to add the linklist plugin to their plugin chains in each blog's WEB-INF/blog/ (or, via blojsom web admin) as:


Note: for individual flavor templates like OPML and FOAF, for best performance, in your main WEB-INF/ file, add the line:

ignore-flavors=admin foaf opml

This line tells blojsom not to process blog entries for these flavors, which can speed things up considerably. You can use this property to list any flavors that don't display any blog entries or entry-specific data. (If you use the RSD flavor, that's another one that you would include in this list.) You will have to restart blojsom for this to take effect.

Once you have these new flavors installed, they will be accessible just like other blojsom flavors, e.g.:


back to top

Linklist properties files, how to:
Please first see the new quick install instructions above. What follows are more details.

The files allow optional properties to be set for LL4blojsom. The use of these properties files is optional, which is why they are not described as part of the simple installation.

But, the properties files are required if you wish to:

The files can be used at the global level by being placed in the blojsom WEB-INF directory, and at the individual blog-level by being placed in the individual WEB-INF/blog directories. Please note that there are different properties that work at the global level and blog-level—these files are not interchangeable.

Please see the example global in the ll_global_level directory of the LL4blojsom download, and the example blog-level in the ll_blog_level directory of the LL4blojsom download.

These example properties files have the most detailed info to-date on the various optional properties that can be set and what are the values they can be set to.

back to top

WTF, the linklist source (e.g., linklist.txt) format:
This format (created for this plugin) is called WTF, which stands for Whoopdedoo Text Format. The simplest version of the format has a new value on each line, with each value prefixed with a field name, like:

name: Bob is an example

These field/value pairs can be grouped together under a key, which is indicated like this:

title: A site to see

or, like this:

name: Tom X. Ample

name: Ned X. Ample

The =key1 indicates that there is one set (or row) of fields and values (i.e., the same as a Java properties file). So, for example, if above there were two title fields, they would be treated as the same title (and, the values combined into an array).

The :key2 indicates that there are multiple sets (or rows) of fields and values. In this case, each set is separated by one or more blank lines. So, in the above example, there are two sets of name / email values.

Keys created with :key can have as zero or more sets of values, and the fields in each set need not match. But, the idea is that this is a way to group similar data sets together.

By default, if no key is specified, LL4blojsom assumes that they are under the key :LISTINGS. This allows for linklist source files to not have any keys, and be just a list of field/value pairs.

But, more elaborate source files can be created that use several keys, and LL4blojsom has special features for these keys: :LISTINGS, :CATEGORIES, and =MYINFO.

So, with WTF in general, you can create your own keys, but, currently, LL4blojsom only recognizes those above three keys.

For more details (by example), please see the sample blog-level linklist sources (which are in the ll_blog_level directory of the LL4blojsom download): linklist.txt, linklist_cats.txt and linklist_xfn_foaf.txt.

back to top

Why the linklist source format isn't XML / OPML / RDF, etc.:
One of the great features of blojsom is that creating blog entries is as simple as creating text files. The default list file format was designed with this in mind, i.e., that it should be very easy to create a list by hand in a text file, copy and paste from other lists, etc.

The original format planned was actually an XML format that was meant to be as simple as possible (so, as a point of reference, it was a little simpler than OPML). But, it just seemed too complicated/laborious to write by hand compared with everything else in blojsom. Besides, it was fun to create a new format—long live text files!

back to top

Default Base (WTFBase) and fallback linklist sources:
The default base (list storage system) of LL4blojsom is net.icite.datastore.WTFBase. This implements the net.icite.datastore.DatastoreBase interface, and the idea is that other ways to store lists (XML, RDF, RDBMS, persistent OO) can be supported through this interface. (However, the interface is still in development.)

In any case, the global file can indicate which class to use as the base, to keep this open for future alternatives.

The default base (WTFBase) uses files to store lists (see info above and examples for format info). LL4blojsom assumes the default filename to be linklist.txt. This can be changed in the at both the global and individual blog levels, and multiple files can be used in both cases (e.g., a displayed linklist can be defined by the union of multiple source files).

By default (i.e., with no installed), the global linklist.txt will be the list available to any blog (i.e., flavor with the linklist plugin in its chain). But, for each blog with a blog-level linklist.txt available, the local one will be used instead of the global one.

So, this means you can have a linklist.txt that acts as a fallback for the whole blojsom install, and then any individual user who has their own linklist.txt will use that one instead.

The global file can also set an explicit global fallback file. Please see the example global in the ll_global_level directory of the LL4blojsom download.

The use of allows the global blojsom admin and each user to set different sources (including multiple files) for their linklists. And, one effect of this is that files can be shared between users either via the blojsom admin hosting global lists available to everyone, and/or each user sharing their lists in a more peer-to-peer fashion. (Note: this is all done with files and paths, so I don't mean hosting and peer-to-peer in any kind of TCP/IP sense.)

Note: linklist source filenames can not have commas (i.e., ",") in them. Sorry! URLs can have commas, but they must be escaped, (i.e., "%2C"). [Need to test, but maybe file://namewithcomma%2Cetc can work]

Note: the install file must be in UTF-8, but user level files can be in other character sets. (NEED to test this more.)

back to top

Roadmap, to-do's and known limitations:

The general roadmap is to better integrate this plugin with blojsom by adding a web admin interface, and to continue to clean-up and refine features, plus add a few planned features not yet properly implemented.

Also, in the interest of producing a separate WTF release, the LinkList plugin and WTF will become a bit more more cleanly separated.

TODOs (besides the web admin interface, which is the big to-do!)

* reorganize the documentation so it's not so overwhelming
* document all the useful LinkList functions available to templates
* more work on supporting group sources vs user sources
* ensure that getListings(sourceList) works with global sources
* source permissions
* advanced sorting and filtering
* better auto and manual reloading of sources and properties
* auto reloading of global properties
* more testing of internationalization features, though: so far, so good!

As of the version 1.1 items on the feature list marked with a * are not yet fully implemented.

back to top

Releases / changelist:

version 1.1 - May 11, 2005

* fixed null return value issue with the multiToArray method of net.icite.blojsom.plugin.LinkListToTemplate

* added back a line that vanished from ll_html.vm in v1.0

* added a check to fix for different final separator results between Tomcat/JDK 1.5 and Resin/JDK 1.4 with servletConfig. getServletContext(). getRealPath(configResourcePath).

* use of the file path separator is now system sensitive

* added description of how to use arrays with the from ...FromSource() methods in the Velocity templates

* added upgrade instructions to this document

version 1.0 - April 30, 2005

* updated documents to reflect refactoring to official WTF name (in the net.icite.datastore package): TextBase changed to WTFBase and TextBaseComparator changed to WTFBaseComparator.

* added new sections and extensively cleaned-up this documentation

* added useful functions in the LinkListToTemplate class: secureHash, getListingsFromSource, getCategoriesFromSource, getListingsFromSourceSort, getCategoriesFromSourceSort, getListingsFromSourceFilterSort, getCategoriesFromSourceFilterSort, getMyInfo and getMyInfoFromSource.

* added credit to Sam Ruby (in this doc) for his example secureHash

version 1.0, preview - April 10, 2005
* updated this document with various clean-ups and first posted online

version 1.0, preview - February 6, 2005
* entered in the 2005 blojsom developers contest

back to top

Credits and thank you's:
Special thanks to David Czarnecki, the creator of blojsom, for encouragement, help, and for making blojsom open source and such a good system to code in and around.

The loading and storing code in the WTFBase used by LL4blojsom are significantly based on David's load and store methods in his BlojsomProperties class.

The secure hash function used in WTFBase utilizes Sam Ruby's Java example (more info) of SHA1.

Development of the foaf.vm template was made possible through studying the example of Morten Frederiksen's WordPress Plugin: FOAF Output. Special thanks to Morten and Danny Ayers for their feedback on LL4blojsom's FOAF output.

back to top

License and copyright info:

Creative Commons License
This documentation for the LinkList plugin for blojsom is licensed under a Creative Commons License. If you post this document someplace, please link back to its source on the web.


The LL4blojsom and WTF code itself is released under the following BSD-style license. Dual licensing is a possibility in the future (by adding the GPL license). So, if you are interested in using this code under GPL license, please email your request here.


Copyright (c) 2005 Jay Fienberg. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of the "Jay Fienberg" nor "iCite" nor "the iCite net" nor "LinkList for blojsom" nor "LL4blojsom" nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Products derived from this software may not be called "iCite" or "the iCite net" or "LinkList for blojsom" or "LL4blojsom" nor may "iCite", "the iCite net", "LinkList for blojsom", nor "LL4blojsom" appear in their name, without prior written permission of Jay Fienberg.



The LinkList for blojsom distribution contains a number of third-party software components.

The LinkList for blojsom distribution includes software developed by the Apache Software Foundation:

Copyright © 2004 The Apache Software Foundation. All rights reserved. Apache License, Version 2.0.

back to top