LinkList (blogroll) plugin for blojsom
created by: Jay Fienberg, updated: May 11, 2005
table of contents:
getting started—it's pretty easy:
- Intro: what it is
- Simple blogroll, quickest install how-to
- Where to download it
- Upgrading to the latest version
almost everything you'd ever want to know about it:
- Why isn't it just called the "blogroll plugin"
- How it works (in brief)
- Features (overview)
- Suggested uses
- Requirements and dependencies
- Installation, how to
- LL4blojsom files and Javadocs
- Creating a linklist, how to
- Using linklists in your templates, how to
- Advanced template examples, including FOAF
- Linklist properties files, how to
- WTF, the linklist source (e.g., linklist.txt) format
- Why the linklist source format isn't XML / OPML / RDF, etc.
- Default Base (WTFBase) and fallback linklist sources
- Roadmap, to-do's and known limitations
- Releases / changelist
- Credits and thank you's
- 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.
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.
- Download the current
icite-LL4blojsom-x.x.zipinto an easy to find directory
- copy the
lib/*.jarfiles to your blojsom
- copy the
ll_blog_level/linklist.txtfile to your blojsom blog-level
- copy the
templates/ll_html.vmfile to your blojsom blog-level
- in the blojsom install plugin.properties,
WEB-INF/plugin.properties, add a line referencing the plugin:
- * in the blog-level plugin.properties file,
WEB-INF/blog/plugin.properties, add a linklist to the HTML flavor template:
- * in the place where you'd like your blogroll, add this "include" line to your
html.vm(in the same templates directory) :
- **restart blojsom
- if everything looks good, you can edit that
linklist.txtfile 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
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).
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:
- delete the old
icite-WTF-x.x.jarfiles from your
- 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.txtfiles that you want to keep!
- restart blojsom
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.
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.)
- 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.
- 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)
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.
Installation, how to:
First see the new quick install instructions above. What follows are more details.
icite-LL4blojsom-x.x.zip contains a /lib directory with four jars, the
icite-WTF-x.x.jar, and the Apache Jakarta
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:
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:
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.
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
/ll_blog_level- linklist source and properties files to copy into blog-level
/ll_global_level- linklist source and properties files to copy into the blojsom install
/src- Java source code for the LinkList and WTF components
/templates- Velocity templates to copy into blog-level
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)
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.,
All global linklist sources should be placed in the main blojsom install directory, i.e.,
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
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.,
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
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))
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.,
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:
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/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:
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.:
Linklist properties files, how to:
Please first see the new quick install instructions above. What follows are more details.
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.txtfor the default filename
- make use of other, more advanced, features of LL4blojsom
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.
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
=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).
: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:
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.
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!
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.
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.)
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.
Releases / changelist:
version 1.1 - May 11, 2005
null return value issue with the
multiToArray method of
* 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
TextBaseComparator changed to
* added new sections and extensively cleaned-up this documentation
* added useful functions in the
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
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.
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.
License and copyright info:
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.
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.
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.