LinkList (blogroll) plugin for blojsom

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:

4. Why isn't it just called the "blogroll plugin"
5. How it works (in brief)
6. Features (overview)
7. Suggested uses
8. Requirements and dependencies
9. Installation, how to
10. LL4blojsom files and Javadocs
11. Creating a linklist, how to
12. Using linklists in your templates, how to
13. Advanced template examples, including FOAF
14. Linklist properties files, how to
15. WTF, the linklist source (e.g., linklist.txt) format
16. Why the linklist source format isn't XML / OPML / RDF, etc.
17. Default Base (WTFBase) and fallback linklist sources
18. Roadmap, to-do's and known limitations
19. Releases / changelist
20. Credits and thank you's
21. 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 icite-LL4blojsom-x.x.zip (more info)
2. unzip icite-LL4blojsom-x.x.zip 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 plugin.properties, WEB-INF/plugin.properties, add a line referencing the plugin: linklist=net.icite.blojsom.plugin.LinkListPlugin
7. * in the blog-level plugin.properties file, WEB-INF/blog/plugin.properties, 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 SourceForge.net. Please download the latest release of the "LinkList for blojsom" package on the project's file download page.

The download you need is the icite-LL4blojsom-x.x.zip 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 linklist.properties 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):

• simple "minimal configuration" by default
• advanced configuration options on install and per user basis
• support multiple list sources globally and per user
• access list sources individually or merged
• access list sources via file, web, or ftp
• * use blojsom to publish list sources on the web
• share list source between users
• * globally prepend and append list sources to user sources
• global fallback list for users with no list
• * global user groups, different prepends / appends / fallbacks per group
• * admin controls on sources to assign read and write permissions (write-to-sources mechanism not implemented, but could be integrated with the blojsom web admin interface in the future)
• * shuffle and random access to lists for playlists, webrings, rotating ads., etc.
• basic sorting and filtering of list sources
• * advanced sorting and filtering of list sources
• * ability to eliminate duplicate listings in merged list sources
• uses blojsom template flavors to produce output in HTML, FOAF, OPML, etc.
• built-in support to use XFN tags and convert to FOAF
• built-in support for categorized lists (e.g., blogrolls with categories), where each listing can appear in zero or more categories

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:

• Blogroll
• Blogroll with categories
• Blogroll with categories that match (or map to) your blog categories (i.e., display a different blogroll in each category, e.g., in category1 display "other sites about category1")
• Faceroll—list image files in your blogroll, and display a faceroll or a random faceroll (see Joi Ito's random faceroll for an example)
• Web ring / random site linker (web-wide, blojsom-install-wide, etc.)
• Next-blog menu bar that works off a shared list
• Common menu across blogs
• Link blog—alternative to using blojsom entries
• Site ads (use list to store ads, grab at random) and cross-site ads
• Music / podcast playlist (use it to generate RSS with enclosures, m3u, XSPF)

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 icite-LL4blojsom-x.x.zip 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 plugin.properties, i.e., WEB-INF/plugin.properties, add a line referencing the plugin:

linklist=net.icite.blojsom.plugin.LinkListPlugin

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

html.blojsom-plugin-chain=linklist

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:

• /javadoc - Javadocs for the LinkList and WTF components
• /lib - jar files to copy to the blojsom install WEB-INF directory
• /ll_blog_level - linklist source and properties files to copy into blog-level WEB-INF/blog directories
• /ll_global_level - linklist source and properties files to copy into the blojsom install WEB-INF directory
• /src - Java source code for the LinkList and WTF components
• /templates - Velocity templates to copy into blog-level WEB-INF/blog/templates directories
• LICENSE - a text copy of the license (below)
• NOTICE - a text copy of the Apache portion of the license (below)
• index.html - this document (HTML)

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/flavor.properties (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/plugin.properties (or, via blojsom web admin) as:

opml.blojsom-plugin-chain=linklist
foaf.blojsom-plugin-chain=linklist

Note: for individual flavor templates like OPML and FOAF, for best performance, in your main WEB-INF/blojsom.properties 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.:

http://mysite/blojsom/myblog?flavor=opml
http://mysite/blojsom/myblog?flavor=foaf

back to top

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

The linklist.properties 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:

• use more than one linklist source file (per blog)
• keep linklist source files in non-default locations
• allow multiple blogs to share the same (non-global) source(s)
• access sources via absolute file path or URL
• use names other than linklist.txt for the default filename
• make use of other, more advanced, features of LL4blojsom

The linklist.properties 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 linklist.properties in the ll_global_level directory of the LL4blojsom download, and the example blog-level linklist.properties 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
url: http://example.com/1

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

=key1
title: A site to see
url: http://example.com/2

or, like this:

:key2
name: Tom X. Ample
email: t.x.ample@example.com

name: Ned X. Ample
email: n.x.ample@example.com

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 linklist.properties 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 linklist.properties 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 linklist.properties 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 linklist.properties file can also set an explicit global fallback file. Please see the example global linklist.properties in the ll_global_level directory of the LL4blojsom download.

The use of linklist.properties 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 linklist.properties file must be in UTF-8, but user level linklist.properties 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.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.