BottomFeeder Home Page

BottomFeeder
Technology Guide

Version 4.4

July 1, 2007

 

Valid XHTML 1.0!

 

BottomFeeder on SourceForge

 

Cincom Smalltalk Home Page

 

© 2007, Richard A. Demers

 

Contents

 

BottomFeeder Home Page

Contents


 |- Introduction
 |   |- Notice
 |   |- Related Documents
 |   |- System Requirements
 |   |- BottomFeeder and Smalltalk
 |
 |- Concepts
 |   |- Feeds
 |   |   |- Feed Standards
 |   |   |- A Sample Feed
 |   |   |- Aggregating Feeds
 |   |   |- Updating Feeds

 |- Installing BottomFeeder
 |   |- Windows
 |   |- Apple
 |   |   |- Mac OS 8/9
 |   |   |- Mac X
 |   |   |- Mac X 10.2.x
 |
 |- BottomFeeder Initialization File
 |
 |- Blog Poster Initialization File
 |
 |- Running BottomFeeder
 |   |- Windows
 |   |   |- Command Line Arguments
 |   |   |- Windows Registry Keys
 |   |- UNIX
 |   |   |- Environment Variables

 |- Plugins
 |   |- What Are Plugins?
 |   |- Downloading Plugins
 |   |- BottomFeeder's Plugin API
 |   |- Creating Plugins
 |   |- Customizing Menus
 |   |- Getting Notified Of Events
 |   |- Object Messages

 

BottomFeeder Home Page

Introduction

Most users of the BottomFeeder RSS aggregator do not care to know the technical details of how it works, how to install it, how to customize it, or how to extend it with plugins. This document is for people who do.

Contents


Notice

BottomFeeder has been released as an Open Source program, under the Artistic License. When you download it, you agree to abide by this license.

Contents


Related Documents

The following documents are available to help you get the most benefit from BottomFeeder:

Contents


System Requirements

BottomFeeder can be installed and run on any system that meets the following minimum requirements:

Component Minimum Requirement
Operating System Windows, Linux86, Macintosh (OS8, OS9, OSX), HPUX (10, 11), SGI, AIX, Solaris, or Alpha Unix
RAM 128MB (~32Mb for BottomFeeder)
Free Hard Drive
(prior to installation)
32MB
Monitor 640x480 display, 256 colors (or higher)
Printer Optional.
Internet Connection Minimum of 28.8 Kbps connection speed, but broadband connection preferred.

Contents


BottomFeeder and Smalltalk

BottomFeeder was produced using the VisualWorks 7.5 Smalltalk software development system, which is why it is available on so many operating systems. At its core is a Virtual Machine (VM) that has been efficiently implemented on a wide variety of operating systems. The VM executes programs written in the Smalltalk programming language, providing them with many services, such as memory management.

But operating system independence is only one of the reasons why BottomFeeder was implemented using VisualWorks Smalltalk. The primary reason is that programming in Smalltalk is super-productive. Smalltalk makes it possible for small teams to quickly explore new ideas and build high quality products. While a number of programmers have contributed to BottomFeeder's development and many enhancements, it is essentially the work of one person. But even a hard-working and talented person can only do so much each day; using powerful tools makes a big difference.

Smalltalk is a powerful, dynamic, and elegant programming language that has a simple, easy-to-learn syntax and fully supports object-oriented programming. VisualWorks includes large libraries of predefined object classes that reduce the amount of new code that needs to be written; everything from mathematics to database access and Internet communications. It also includes a wide range of programming tools for organizing, browsing, creating and modifying programs, and for inspecting, debugging and optimizing programs. All together, programming with VisualWorks Smalltalk is not only efficient, it is fun.

BottomFeeder does not make the Smalltalk language or the VisualWorks development tools available to its users, but a free, non-commercial version of VisualWorks is available for download. However, the Smalltalk Workspace tool is available as a menu option. Users can key in and execute Smalltalk expressions, and create Smalltalk scripts that can be saved and executed at any time. Some downloadable examples of such scripts are available at the BottomFeeder Scripting wiki page. These scripts show how to extract information from webpages and format it as a feed that BottomFeeder can process.

Contents

BottomFeeder Home Page

Technical Concepts

You do not have to understand how BottomFeeder works in any great detail -- no more than the driver of a car needs to know how its engine works -- but you may find it helpful to understand a few basic concepts.

The most basic concept is object orientation -- also called action on an object. BottomFeeder is all about objects and commands to those objects. Folders, Feeds and Items are the kinds of objects you see in BottomFeeder. (More about them in the following sections.) Icons and text in BottomFeeder's windows represent each kind of object, so you always know what you are seeing.

But objects are more than just pretty pictures. Each object responds to your commands. All you have to do is select an object and choose a command from a menu or a toolbar. The main trick is knowing what kind of object to select to do what you want, but that will become clear when you know a bit more about each kind of object.

The really cool thing (if you're into technical stuff) is that BottomFeeder is itself made up of objects that send commands to each other. So there is a direct relation between your commands and the way that BottomFeeder performs those commands. But that's the beauty of programming in Smalltalk!

Contents


Feeds

A web page with a feed.

A feed is an object that represents a special kind of file in a website; one that specifies what has changed in the other files of the website. It is called a feed because it supplies, or feeds, information to whomever will consume it. The website does not have to send messages to individual subscribers to tell them about changes. It just updates its feed file. Anyone on the web can then ask for a copy of the feed file.

BottomFeeder does not care how a website creates a feed file and adds new items to it. In some cases, the website accumulates items in a change log, and on a periodic basis builds a new feed file, and replaces its old feed file. Other websites update their feed file every time there is a new item. And still other websites dynamically build feed files in response to query-style requests from their users. As a consumer of feed files, you really do not care.

If the website covers multiple topics, it may produce multiple feeds so that users can select which ones they want to monitor.

Contents


Feed Standards

A website creates its feed files according to the RSS standard. RSS stands for Really Simple Syndication. There have been several versions of this standard, with many differences among them as people have tried to make RSS feeds handle different things. As a user of BottomFeeder, you do not have to be concerned with this; BottomFeeder handles all of the common standards just fine, including:

Contents


A Sample Feed

Here's an example of a minimal RSS 0.91 feed (taken from a RSS Tutorial):


<?xml version="1.0"?>
<rss version="0.91">
  <channel>
    <title>Example Channel</title>
    <link>http://example.com/</link>
    <description>My example channel</description>
  </channel>
  <item>
     <title>News for September the Second</title>
     <link>http://example.com/2002/09/01</link>
     <description>other things happened today</description>
     <trackback:ping>
          http://foo.com/trackback/tb.cgi?tb_id=20020923
     </trackback:ping>
  </item>
  <item>
     <title>News for September the First</title>
     <link>http://example.com/2002/09/02</link>
     <trackback:ping>
          http://foo.com/trackback/tb.cgi?tb_id=20020924
     </trackback:ping>
  </item>
</rss>

Without going into all of its details, this is an XML encoded file consisting of tagged elements. The root element, <rss> to </rss>, encloses all other elements. Its first element is <channel>, which specifies the title, link and description of the feed's source website. This is followed by a series of <item> elements, each of which specifies the title, link and description of some aspect of the source website that is new or changed.

Each item can also include a trackback element. A trackback is an Internet message that specifies the URL of its sender and identifies a specific resource (such as a feed item). When your item links to other items (that have requested a trackback), your feed server sends a trackback message to each to tell them that your item is linked to them. Similarly, if your item requests trackbacks and an item in some other feed server links to your item, their feed server sends a trackback message to your server.

Contents


Aggregating Feeds

Aggregating feeds.

BottomFeeder is a program that aggregates -- a fancy word for "brings together" -- feeds from multiple websites. You tell BottomFeeder what feeds you are interested in by subscribing to them. BottomFeeder then checks for changes by getting the feed file, and telling you about each change. Just leave BottomFeeder running in the background; it checks for feed updates every N minutes, and let's you know when something is new.

But there's a catch; for BottomFeeder to do its thing, a website must publish a feed. An ever increasing number of websites publish feeds, and it's an idea that is quickly catching on. People tend to revisit sites that provide feeds - and that's a good thing, so more and more sites are coming on board. If you find an interesting website that doesn't publish a feed yet, send the web master a message to "get with the program."

Contents


Updating Feeds

The process by which BottomFeeder updates feeds from their source websites is straightforward, and worth a few minutes of time to understand.

  1. BottomFeeder keeps an internal object model that consists of a Feed object for every subscribed feed. And for every feed, there is a collection of Item objects that is sorted by timestamp. Each item also has an identifier that is unique within its feed.
  2. BottomFeeder saves a maximum of N items for any feed (default = 50). These are the N items with the most recent timestamps.
  3. Subscribed feeds are updated automatically by BottomFeeder every M minutes (default = 30 minutes). Feeds can also be updated on your command.
  4. When a feed is updated, BottomFeeder begins by asking the feed's website if the feed file has changed since the timestamp of the last received feed file. If the feed file has changed, BottomFeeder requests a copy of the entire feed file from the website.
  5. BottomFeeder examines the identifier of each incoming item and eliminates duplicates of items it already has.
  6. BottomFeeder determines if the item passes through any filters you created for incoming items. It adds the accepted items to the feed's collection -- in timestamp order.
  7. If the number of items saved for a feed's collection is greater than the maximum number allowed, items with the oldest timestamps are discarded.
  8. An exception to the last point is that you can tell BottomFeeder that an item is to persist. The number of items saved for a feed can then be greater than the maximum number allowed.
  9. You can also tell BottomFeeder to delete an item, but this just means you don't want BottomFeeder to show it to you again. A deleted item continues to hang around until the update process replaces it with a new item; meanwhile, you can ask to see deleted items, and even restore them to the normal item views.

Contents

BottomFeeder Home Page

Installing BottomFeeder

Installing BottomFeeder on Windows

Do the following to download and install BottomFeeder on Windows:

  1. Choose a convenient directory of your local hard disk to be the BottomFeeder Home Directory. For example, in Windows, the BottomFeeder Home Directory could be c:\Program Files\BottomFeeder\.
  2. Using an Internet browser, go to the BottomFeeder Downloads Page.
  3. Decide whether you want the currently released version of BottomFeeder or the latest version from the development team. The development version has the latest updates to the program, but it may not be as reliable as the released version.
  4. Select the Windows Installer version of BottomFeeder that is appropriate for your system. The installer will guide you through the rest of the installation process.
  5. You may also want to create a shortcut to BottomFeeder on your desktop. On Windows, right-drag the icon of bottomFeeder.exe to your desktop and select Create Shortcuts Here from the popup menu.

Contents


Installing BottomFeeder on Apple

Installing BottomFeeder on Mac OS 8/9

Do the following to download and install BottomFeeder on a Mac OS 8/9 system:

  1. Download BottomFeeder from the BottomFeeder Home Page, choosing the Mac OS OS 8/9 version.
  2. Uncompress the folder onto your desktop. The zipped package does not include a straightforward installer; it has, instead, the following files:
  3. Drop the icons for NetManage, StdLibC and bottomfeeder on Stuffit! Expander. You will end up with the NetManage and StdLibC icons looking like puzzle pieces and bottomfeeder will expand to an icon called "visual". Visual will have its creator already set to HPS7. To get the bottomfeeder.im icon to highlight the "visual" icon upon drag, run ResEdit 2.1.3 and change the creator for bottomfeeder.im to HPS7.
  4. A so-called hosts must be defined. To define a hosts file, open the TCP/IP control panel. Press the Select Hosts File button (if it is not visible, press Command-U to switch the User Mode from Basic to Advanced). Now locate the default Hosts file, which can be usually found in your System Folder's Preferences folder. If there's none, simply create an empty file using the SimpleText application, then select this as your new Hosts file. Finally, add this line to the file:
    localhost.      A                       127.0.0.1
    
  5. After that, BottomFeeder should run. Just drop bottomfeeder.im on bottomfeeder.
The above was provided by a Mac user on the Internet.

Contents


Installing BottomFeeder on Mac X

Do the following to download and install BottomFeeder on a Mac OS X system:

  1. Download BottomFeeder from the BottomFeeder Home Page, choosing the Mac OS X version.
  2. Uncompress the folder onto your desktop.
  3. The first time you run BottomFeeder, it will do everything else needed to install itself.

Contents


Installing BottomFeeder on Mac X 10.2.x

Apparently there is a special challenge to installing BottomFeeder on an Apple Mac X 1.2.x system. The following was adapted from a blog by James Savidge:

First you'll need to download and install Apple's X11 server. Ignore the fact that Apple's website says that you need 10.3. It works fine under 10.2.8.

Next make sure that you have the X11 version of the VisualWorks runtime engine installed. The readme.txt file in the macxx11 directory says the following:

  1. Set the DISPLAY environment variable to a sensible value.
    To use the graphical environment,
    • create the directory ~/.MacOSX
    • copy the file environment.plist to ~/.MacOSX
      The .plist file is included with 10.3 but not with 10.2. You can download it from here.
    • logout and login again

Once you have put the .plist file in the directory and logged in again, start up X11 by double clicking on X11 application in the Applications directory. Then, start VisualWorks by double clicking on the visual application in the macxx11 directory.

After downloading and installing BottomFeeder, move the following directories into one of the subdirectories in the Package contents of bottomFeeder.app:

And if you have already been using the BottomFeeder CST Blog Tool plugin, move the following, as well:

To get to the proper directory, select the BottomFeeder icon, pop-up the context menu, and select the Show Package Contents menu item. In the resulting window, open the Contents folder and then the Resources folder. Move the files selected or copied above, into the bottomFeeder.app/Contents/Resources/ directory.

To start BottomFeeder in X11 by double clicking the icon,

While running BottomFeeder under X11, there are a couple of reported bugs that can be worked-around if you set the User Interface setting to OSF Motif.

Contents

BottomFeeder Home Page

BottomFeeder Initialization File

When you start BottomFeeder, its operation is controlled by settings loaded from a file in your home directory. This type of file is called an initialization file, and its name has a suffix of .ini. The default initialization file installed with BottomFeeder is named btfSettings.ini.

You can temporarily override some of the settings in the initialization file, when BottomFeeder is started, by command line arguments, or by environment variables. These overrides persist only for the current run of BottomFeeder.

You can also change the current settings so they persist in subsequent uses of BottomFeeder. Select System > BottomFeeder settings... in the main menu, and make your changes in the BottomFeeder Settings window. When you exit from BottomFeeder, the current values of these settings are saved so they can be reloaded when you next start the program. The Settings window also allows you to return to the values in the .ini file.

The first line of the initialization file identifies the type of .ini file -- [Settings] -- which should not be changed under any circumstances. Each setting is then specified on a separate line as a key=value pair. String values are specified in single quotes. Boolean values must be specified as true or false. If you specify relative file paths for the file settings, they are relative to BottomFeeder's home directory.

Strong recommendation: Make a backup copy of file btfSettings.ini before making any changes to it.

Initialization File Line Description
[Settings] Do not change this line.
absoluteMemoryCeiling
=96000000
Specifies the maximum memory BottomFeeder should consume.
alwaysBrowseInline
=false
Specifies whether all requested Internet pages are to be displayed by a browser opened in the Item pane (true), or in an external browser (false).
alwaysSaveBackupXMLFile
=true
Specifies on exit whether BottomFeeder should save an XML file without items, but with all the rest of the tree structure. This file is used for automatic recovery if the file BottomFeeder normally saves is damaged.
autoBrowseNullDescriptions
=false
Specifies whether BottomFeeder should automatically open a browser when an item selected in the Item List pane contains only an Internet address (true), or display the URL of the address (false).
backgroundLoadPriority
=40
Specifies the processing priority (in a range of 0 to 100) to be used by BottomFeeder when loading upgrades as a background task.
bfTechGuideUrl
='http://www.cincomsmalltalk.com/
BottomFeeder/doc/
TechnologyGuide/TechnologyGuide.htm'
Specify the URL of the BottomFeeder Technology Guide.
browsingHistoryDepth
=10
Specifies the number of items to be kept in the history of items displayed in a tag page.
browserPixelSizeSetting
=nil
Specifies the scale of the text size (small, medium, etc) in the Item pane.
checkItemReferences
=true
Specifies that cached feed items should be checked for references to each other.
commentingName
=''
Specifies the Posting name used in the Comment window for the last comment sent on any item. This setting is initially empty; BottomFeeder updates it.
daysWithoutUpdates
ToMarkAFeedBad

=30
Specifies that a feed should be marked as bad if it has not been updated the specified number of days.
defaultHttpTimeout
=20000
Specifies how long BottomFeeder should wait for a response to an update request. The default is 20 seconds.
For some feeds, especially on slow (dialup) links, 20 seconds may not be enough.
delay
=30
Specifies the number of minutes between BottomFeeder updates (the update percent you see reflected in the Main window status bar).
deliciousBaseUrl
='http://del.icio.us/api/posts/'
Specifies the URL of the del.icio.us social bookmarking website.
deliciousUsername
=nil
Specifies the user name of an account in the del.icio.us social bookmarking website.
deliciousPassword
=nil
Specifies the password of an account in the del.icio.us social bookmarking website.
docUrl
='http://www.cincomsmalltalk.com/
BottomFeeder/doc/
UsersGuide/UsersGuide.htm'
Specify the URL of the BottomFeeder User's Guide.
dontLimitMemoryGrowth
=true
Specify whether BottomFeeder can increase the amount of memory it uses to the limits of the hosting system.
emailAddress
=''
The user's email address (from User Settings).
emailPassword
=''
The user's email server password (from User Settings).
emailServer
=''
The user's email server (from User Settings).
externalBrowser
=''
Specifies the Internet browser to open outside of the BottomFeeder Main window.
favoritesDirectory
=''
Obsolete.
feedFilename
='btfSave\rssFeeds.btf'
Specify the local file in which BottomFeeder should save feeds.
feedsterQueryString
='/search.php?hl=en&ie=UTF-8&q='
ISO-8859-1&q='
Specify the template of the Feedster query string.
feedsterURL
='http://www.feedster.com/'
Specify the URL of the Feedster website.
ftpHost
=''
The URL of the FTP host (from User Settings).
ftpPassword
=''
The user's password on the FTP host (from User Settings).
ftpUsername
=''
The user's Username on the FTP host (from User Settings).
googleKey
=nil
Specify the authorization key to use when performing a search on Google, an Internet search engine.
When BottomFeeder is installed, it has a default authorization key that allows it to perform up to 10,000 searches a day, but this one key is used for all BottomFeeder users. Users who perform many Google searches a day through BottomFeeder should get their own authorization key. This can be done by clicking the Get a Google Key button on the Search window.
ignoreTimeoutErrors
=false
Specifies that timeout errors detected during communication operations are to be ignored.
includeCommentsInNewspaper
=true
Specifies that comments should be included with their items in a newspaper view.
infoUrl
='http://www.cincomsmalltalk.com/
BottomFeeder/'
Specify the URL of the BottomFeeder information web page.
isOnline
=true
Specifies whether BottomFeeder is to be online (true), or offline (false). When offline, all network functions are turned off, and network menu items are disabled.
You can still add feeds to folders; but they are not updated until BottomFeeder is again online.
lastPlatform
=#win32
Specifies the last platform on which BottomFeeder was run. You can specify one of the following:
  • #win32 - Windows.
  • #unix - OS 8/9.
  • #mac - OS X.
launchNewBrowserOnWindows
=true
Specifies whether BottomFeeder should open a new browser for any action that requires one (true), or reuse an existing browser (false).
Opening a new browser is the default action on non-Windows platforms.
lookPolicy
=#AutoSelect
Specifies the appearance of BottomFeeder windows and controls. You can specify
  • #AutoSelect - the underlying system platform.
  • #DefaultLook - default Smalltalk look.
  • #Macintosh - Macintosh OS/8.
  • #MacOSXAqua - Macintosh X Aqua.
  • #MacOSXPollock - Macintosh X using VisualWorks Pollock widgets.
  • #OSFMotif - Motif.
  • #Win95NT - Windows 95/NT.
  • #Win982k - Windows 98/2000.
  • #WinXP - Windows XP.
numberOfItemsToCache
=50
Specifies the total number of items BottomFeeder should cache.
password
=''
Specifies the password BottomFeeder is to use in your proxy server. If you are concerned about password security, change this setting to password= and enter your proxy password into Network Settings so that BottomFeeder can encrypt it.
patchDirName
='btfPatch'
Specify the local directory in which BottomFeeder should save software patch files.
patchSiteFilename
='patches.xml'
Specifies the name of the patch definitions file in the patches website.
patchSiteUrl
='http://www.cincomsmalltalk.com/
BottomFeeder/patches/'
Specifies the URL of the website from which BottomFeeder can obtain software patches.
pluginSiteFilename
='plugins.xml'
Specify the local directory in which BottomFeeder should save plugin files.
pluginSiteURL
='http://www.cincomsmalltalk.com/
BottomFeeder/plugins/'
Specify the URL of the website from which BottomFeeder can obtain plugin files.
proxyDomain
='BOTTOMFEEDER'
Specifies the domain of the proxy server
proxyExceptions
=''
Specifies a comma separated list of Smalltalk exceptions from the proxy server to be ignored.
proxyPort
=80
Specifies the port to use on the proxy server
proxyServer
=''
Specifies the IP address of the proxy server.
Do not specify unless you cannot browse the Internet without proxy settings.
quickStartGuide
='http://www.cincomsmalltalk.com/
BottomFeeder/doc/
QuickStart/QuickStart.htm'
Specifies the IP address of the proxy server.
Do not specify unless you cannot browse the Internet without proxy settings.
runThreadedUpdates
=false
Specifies that BottomFeeder should updates in a separate processing thread, thereby allowing continued user interactions.
saveAfterUpdate
=true
Specifies that BottomFeeder should do a save of its application state after each update cycle.
saveFileDirectory
='btfSave'
Specify the local directory in which BottomFeeder should save feeds and window settings when File/Save All is requested.
File/Save All saves BottomFeeder settings in the directory containing the BottomFeeder program (bottomFeeder.exe).
searchFeedFile
='btfSave\searchFeeds.btf'
Specifies the save file for the search folders.
shouldCommentsFlagNew
=true
Specifies that the arrival of comments on an item should cause the item to be marked as new.
shouldDoItemCaching
=true
Specifies whether BottomFeeder should keep up to N total items after updates that contain new items (true), or always grab just what is in a feed after an update (false).
N is set by the numberOfItemsToCache setting. The intent here is to preserve some content from rapidly changing feeds - otherwise, you may not ever see an item from some of them.
shouldFollowComments
=false
Specifies that BottomFeeder should request item comments that are separately linked to their websites, and add them to the item.
shouldKeepCacheInMemory
=false
If true, Http protocol messages received from the Internet are cached in memory (besides being cached on disk). Caching them in memory can consume a lot of memory.
shouldKeepHTMLInMemory
=false
If true, HTML tagged feed texts are cached in memory; otherwise, they are cached on disk. Caching them in memory can consume a lot of memory.
shouldRunCompatibleServers
=true
Some website pages displayed by a browser contain button-icons of feed-reading tools other than BottomFeeder (not the BottomFeeder fish). You can click any of these buttons to add a BottomFeeder subscription to the website's feed. This setting specifies whether a running instance of BottomFeeder should add the subscription (true), or reject the subscription (false).
If true, BottomFeeder adds the subscription to the root Subscriptions folder of the Feeds tree.
shouldRunLocalServer
=true
Some website pages displayed by a browser contain a button-icon (the BottomFeeder fish). You can click this button to add a BottomFeeder subscription to the website's feed. This setting specifies whether a running instance of BottomFeeder should add the subscription (true), or reject the subscription (false).
If true, BottomFeeder adds the subscription to the root Subscriptions folder of the Feeds tree.
shouldSaveFileOnExit
=true
Specifies whether changes to BottomFeeder's initialization file should be automatically saved on exit from the program (true), or discarded (false).
shouldSetLocaltimeZone
=false
Specifies that BottomFeeder should set its internal clock to the local time zone on startup and adjust the timestamps of displayed items to the local timezone.
shouldSpreadUpdates
=false
If true, BottomFeeder should wait a short period of time between sending requests for feed updates. This spreads out the processing required for an update cycle, significantly reducing the amount of memory and processor resources consumed by BottomFeeder during the cycle.
shouldThrottleThreads
=false
When runThreadedUpdates=true and shouldThrottleThreads=true, BottomFeeder uses a separate processing thread per feed update; otherwise, it uses a thread from a pool of threads for each feed update.
shouldTrackNonUpdatingFeeds
=true
Specifies that BottomFeeder should continue to check feeds that have not updated.
shouldTruncateAllFeeds
OnEachUpdate

=true
Specifies whether BottomFeeder should truncate each feed to N items on each update of the feed's item from its source website.
N is set by the numberOfItemsToCache setting. The intent here is to limit the number of items saved from rapidly changing feeds - otherwise, you may see a rapidly growing number of them.
shouldTruncateAllFeeds
ToLimitOnSave

=false
Specifies whether BottomFeeder should truncate each feed to N items on saves (true), or save all items (false).
N is set by the numberOfItemsToCache setting. The intent here is to limit the number of items saved from rapidly changing feeds - otherwise, you may see a rapidly growing number of them.
showExtraInfoInDescription
=false
Specifies whether the name of the feed containing an item should be included with the item. This is particularly useful in a newspaper display.
showFeedsterResultsInline
=false
Specifies whether to show Feedster results in the Item pane of the Main window (true), or in a new browser (false).
showGridScrollbar
=true
Specifies whether a scrollbar should be shown in an Item List.
showNewViewInTree
=false
Specifies that BottomFeeder should present a Tree View of new items when the New Items view button is clicked. This tree view consists only of feeds with new items, plus their containing folders.
showTabularView
=true
Specifies whether BottomFeeder should display the Item List pane as a table with a date column and a title column for each item (true), or as a simple list of item titles (false).
softMemoryCeiling
=48000000
Specifies the soft limit on memory BottomFeeder should consume.
suppressImagesInBf
=false
Specifies that a feed's image should not be displayed when the feed is selected.
textSize
=#default
Specifies how text is to be rendered in BottomFeeder. The following can be specified:
  • #small - slightly smaller than "default", useful for small displays on the order of 640x480 pixels.
  • #default - the usual size, suitable for 1024x768 displays.
  • #large - slightly larger size, for 1600x1280 hi-res displays.
  • #fixed - similar to "default", but all characters are the same size. This is useful for presenting table-oriented data or in a terminal emulator.
tickerColorStyle
=light
Specify the background color style of the ticker.
tickerSpeed
=#medium
Specify the speed at which the ticker shows item titles.
tickerItemWidth
=#medium
Specify the width of the displayed ticker.
tutorial
='http://www.cincomsmalltalk.com/
BottomFeeder/doc/
Tutorial/Tutorial.htm'
Specify the URL of the BottomFeeder Tutorial document.
unixShellToUse
=sh
Specify the shell to use when BottomFeeder is installed in a Unix or Linux system.
updateLoopPriority
=#medium
Specify the priority (Low, Medium or High) at which BottomFeeder should perform updates relative to other system tasks.
upgradeFilename
='upgradeBtf.xml'
Specify the local directory in which BottomFeeder should save upgrade files.
upgradeURL
='http://www.cincomsmalltalk.com/
BottomFeeder/upgrades/'
Specify the URL of the website from which BottomFeeder can obtain upgrade files.
useLibTidy
=true
If true, BottomFeeder converts the items received from each feed into a form (XHTML) that can be more easily displayed.
  • BottomFeeder only includes TidyHTLM libraries for x86 Linux and Windows. Technically oriented users could build a shared library for their platform if they want to download the C sources. If the TidyHTML dll/shared library is not available, this setting is ignored.
useProxySettings
=false
Specifies whether BottomFeeder should use the proxy settings when establishing Internet communications.
username
=''
Specifies the user name BottomFeeder is to use in your proxy server.
userStyleSheet
=#Simple
Specifies the name of the user-defined stylesheet BottomFeeder is to use.
useTickerForSlimMode
=true
Specifies the user name BottomFeeder is to use in your proxy server.
useXHTMLEditorWhenCommenting
=true
If true, BottomFeeder uses its WYSIWYG editor in the Commenting window.
validationService
='http://www.feedvalidator.org/check?url='
Specifies the user name BottomFeeder is to use in your proxy server.
windowSettingsFilename
='btfSave\btfWinSettings.btf'
Specify the local file in which BottomFeeder should save window settings.

Contents

BottomFeeder Home Page

Blog Poster Initialization File

For the Blog Poster to be able to work with your blog, you need to provide it with some basic information. This is done in a special initialization file in your BottomFeeder home directory, called postingUrls.csb.

The first line of the initialization file identifies the type of file -- [SiteInformation] -- which should not be changed under any circumstances. Each setting is then specified on a separate line as a key=value pair. String values are specified in single quotes. Boolean values must be specified as true or false. If you specify relative file paths for the file settings, they are relative to BottomFeeder's home directory.

Strong recommendation: Make a backup copy of file postingUrls.csb before making any changes to it.

File Line Description
[SiteInformation] Do not change this line.
apiToUse
=#cstAPI
The API to use to communicate with your blog server. You can specify one of the following:
  • #cstAPI -- the Cincom Smalltalk blog server API
  • #metaAPI -- the MetaWebLog API
  • #mtAPI -- the Moveable Type API
  • #bloggerAPI -- the Blogger API
appkey
=''
An application key used by the Blogger API. Set it to the same value as logicalName.
bloggerUrl
=''
This is the URL for a blog that supports the Blogger API.
blogId
=''
The identifier of the blog within the blog server.
blogRollURL
=''
URL for the CST Blogroll servlet interface.
categoryURL
=''
URL for the CST Category servlet interface for this blog.
defaultImageDestination
=''
The blog server directory in which images are to be stored. This is a relative path; do not specify a leading /.
deleteURL
=''
URL for the CST Delete servlet interface for this blog.
doClientTransforms
=false
If true, BottomFeeder transforms certain wiki-style markups into HTML.
encryptionKey
=N
Key used to encrypt blog access.
fileUploadUrl
='.'
This is the URL for uploading files to a CST blog server.
getURL
=''
URL for the CST Get posts interface for this blog.
kickServlet
=''
Not used at this time.
logicalName
=''
This is the name of the blog that is displayed in the header of the Blog Poster window.
metaUrl
=''
This is the URL for a blog that supports the MetaWebLog API.
mtUrl
=''
This is the URL for a blog that supports the Movable Type API.
numberPostsToRetrieve
=25
This is the maximum number of items to retrieve when retrieving items from the blog server.
password
=''
This is the password to use when communicating with the blog server.
postURL
=''
URL for the CST POST interface for this blog.
updateURL
=''
URL for the CST Update interface for this blog.
username
=''
The username to use when communicating with the blog server.
useSpellchecker
=true
If true, BottomFeeder checks the spelling of items as they are entered or updated.
useServerMarkup
=false
If true, certain wiki-style markups are transformed into HTML by the blog server.
viewMode
=#XML
Specifies how items are to be edited by the Blog Poster. The values that can be specified are:
  • #XML -- use the WYSIWYG editor.
  • #plain -- use the plain text editor.

Contents

BottomFeeder Home Page

Running BottomFeeder

Running BottomFeeder On Windows

What you need to do to start BottomFeeder depends on the operating system you are using. For example, to run BottomFeeder under Windows, double-click the BottomFeeder shortcut on your desktop. Alternatively, select Run in the desktop Start menu, type

   [path\]bottomFeeder.exe [argument]... 

in the input field of the Run dialog, and click the OK button.

[path\] is the path to your BottomFeeder Home Directory.

[argument]... consists of optional arguments (see Command Line Arguments).

For example,

   c:\Program Files\BottomFeeder\bottomFeeder.exe -offline
BottomFeeder is a very flexible program. Use the Settings window to make it work in the way that suits you best, but when you are first getting started, it is best to use the program's default settings.

Contents


Command Line Arguments

To run BottomFeeder under Windows, double-click the BottomFeeder shortcut on your desktop.

Alternatively, select Run in the desktop Start menu, type

   [path\]bottomFeeder.exe [argument]... 

in the input field of the Run dialog, and click the OK button. For example,

   c:\Program Files\BottomFeeder\bottomFeeder.exe -online -ini myIni.ini

[path/] is the directory path to the bottomFeeder.exe program.

[argument]... consists of optional arguments, as specified in the following table:

Argument Description
-offline Start Bottom Feeder in offline mode. All network functions are turned off, and network menu items are disabled.
-online Start Bottom Feeder in online mode. All network functions are turned on, and network menu items are enabled.
-ini iniFilename Override the BottomFeeder initialization file. The default filename is btfSettings.ini. This file holds the initialization settings loaded at startup. It is an editable text file - see Initialization File for details.
-f feedsFilename Override the feed file specified in the initialization file (rssFeeds.btf) with the named file. This file holds everything saved under the 'Subscriptions' folder. It is a binary file and cannot be edited.
-w winSettingsFilename Override the windows settings file specified in the initialization file (btfWinSettings.btf) with the named file. This file holds the saved window position and size and the learning menu scores (if used). It is a binary file and cannot be edited.
-d directoryName Override the save directory specified in the initialization file (btfSave) with the named directory. This is the directory in which all other BottomFeeder files are saved.
-convert Convert the old (pre 2.6) settings to the new format and quit.
  1. It is not possible to edit the binary files listed above, but it is possible to load a binary file saved by a previous run of BottomFeeder.
  2. You could push the feed files between two systems (say Linux and Windows) and keep the window settings for each locally.

Contents


Windows Registry Keys

When operating under Windows, BottomFeeder sets the following registry keys:

Registry Key Description
BtfSaveFile Specifies the local directory in which BottomFeeder should save its initialization file after changes by the user.

The Registry path used is KEY_CURRENT_USER/Software/BottomFeeder.

Contents


Running BottomFeeder On UNIX

To run BottomFeeder on a UNIX system, do the following:

  1. Open a shell.
  2. cd to the directory in which you installed BottomFeeder.
  3. % cd bottomFeeder
  4. % ./bottomFeeder bottomFeeder.im

Contents


Environment Variables

In a Unix or Linux system, you can control the operation of BottomFeeder by setting environment variables. For example, you can do something like this:


   BtfSave=/home/auser/btf/btfSettings.ini
   export BtfSave

and then that environment variable is set for that run. If you want variables always set, you can add them to the startup script for the shell you use.

The environment variables for BottomFeeder are specified in the following table:

Environment Variable Description
$BtfSaveDir Override the save directory specified in the initialization file (btfSave) with the named directory. This is the directory in which all other BottomFeeder files are saved.
$BtfSave Override the BottomFeeder initialization file. The default filename is btfSettings.ini. This file holds the initialization settings loaded at startup. It is an editable text file - see Initialization File for details.
$BtfFeedsFile Override the feed file specified in the initialization file (rssFeeds.btf) with the named file. This file holds everything saved under the 'Subscriptions' folder. It is a binary file and cannot be edited.
$BtfWinSettingsFile Override the windows settings file specified in the initialization file (btfWinSettings.btf) with the named file. This file holds the saved window position and size and the learning menu scores (if used). It is a binary file and cannot be edited.
$BtfPatchDir Override the patch file directory specified in the initialization file (btfSave\patches) with the named directory.

Contents

BottomFeeder Home Page

Plugins

What Are Plugins?

Plugins are programs that plug into a host program to enhance it or change it in some way. The host program works well without any plugins, but if you install plugins, the host program becomes more useful to you in some way.

BottomFeeder is a host program to an open-ended set of plugins. BottomFeeder adds the names of the plugins you install to the Plugins menu of its Main window. When you click on a plugin name in that menu, BottomFeeder starts the selected plugin program. Depending on its function, the plugin may open additional windows or it may enhance BottomFeeder in some other way.

Contents


Downloading Plugins

One source for plugins is BottomFeeder, itself. Useful plugins have been created by the BottomFeeder development team. In other cases, other people have sent plugins to the development team. All of these plugins can be downloaded by using the System / Check for Upgrades... command.

Any file transfer program can be used to download plugins from other sources. Just put them into the plugins directory under the BottomFeeder Home Directory.

Contents


Creating Plugins

Creating plugins is best left to experienced VisualWorks Smalltalk programmers.

The plugins that BottomFeeder can install and start are VisualWorks Smalltalk programs that have been deployed as VisualWorks parcels. To create a plugin, use Cincom VisualWorks to create and test appropriate Smalltalk classes and methods, and export them as a .pcl file. Put this file into the BottomFeeder plugins directory so it can be loaded when BottomFeeder is started.

When BottomFeeder loads a plugin, the parcel loader evaluates the block specified by the parcel's Post-load Action property. Specify the following block so that it can initialize itself.


	[:parcel | ...plugin initialization code... ]

This block must send one of the following call-back messages to BottomFeeder to register itself as a plugin:

 
	#{RSS.RSSFeedViewer} ifDefinedDo: [:cls |
	   cls
	      registerPluginClass: PluginClassName
	      startupMessage: #startupMethodName
	      label: labelString].
 
	or
 
	#{RSS.RSSFeedViewer} ifDefinedDo: [:cls |
	   cls
	      registerPluginClass: PluginClassName
	      startupMessage: #startupMethodName
	      label: labelString
	      isForUI: false]
The #ifDefinedDo: message just ensures that RSS.RSSFeedViewer has been imported by the class of the plugin.

If a plugin has a user interface, BottomFeeder adds an entry to its Plugins menu. When clicked, this menu entry sends the startup message specified in plugin's registration to the registered plugin class. If the plugin does not have a user interface, the startup message is sent immediately after registration.

When BottomFeeder unloads a plugin, the parcel unloader evaluates the block specified by the parcel's Pre-unload Action property. Specify the following block:


	[:parcel | parcel unregisterPluginClass: PluginClassName]

Contents


BottomFeeder's Plugin API

Some plugins, such as the IRC Client, provide new capabilities that have little or nothing to do with the basic BottomFeeder application of aggregating feeds. For them, the basic plugin interface described above is all they need.

Other plugins, however, augment BottomFeeder's handling of feeds in some way. For example, the CST Blog Tool opens a tool for creating a blog entry about a selected item of a feed. They need a way to work with selected feeds or items, and users need a way to request their services. For them, BottomFeeder provides an Application Programming Interface (API) for customizing menus, and to be notified of BottomFeeder events.

Contents


Customizing BottomFeeder Menus

BottomFeeder's primary user interface is through menu actions that can be requested on a selected feed or item. A plugin can add an action to the Item List popup menu. When a feed is selected in the Tree pane, BottomFeeder sends the following message to the plugin's class (the one registered with BottomFeeder):

 
	PluginClassName
		customizeMenu: aMenu
		forItem: anItem
		andFeed: aFeed

Here is an example of such a plugin method:

 
	customizeMenu: aMenu forItem: anItem andFeed: aFeed
		"add a menu pick if appropriate"
		self isMyActionAvailableForItem: anItem andFeed: aFeed 
			ifTrue: [aMenu addItem: self myAction]

Contents


BottomFeeder Events

A variety of events occur when BottomFeeder processes user requests. In some cases, a plugin needs to take actions beyond what BottomFeeder has already done. To be notified of these events a plugin must register itself as a receiver of each event. Depending on whether or not the event includes an argument, register by sending one of the following messages:

 
RSS.RSSFeedViewer 
   when: #placeEventNameHere 
   send: #placeYourEventHandlerMethodNameHere 
   with: argument

or

RSS.RSSFeedViewer 
   when: #placeEventNameHere 
   send: #placeYourEventHandlerMethodNameHere


Event Argument Description
#addedFeed: aFeed Sent when a feed is successfully added.
#tgOffline aFeed Sent when BottomFeeder goes offline.
#tgOnline aFeed Sent when BottomFeeder goes online.
#bottomFeederStarting: RSSFeedViewer instance - the main BottomFeeder window Sent after BottomFeeder has started, but before it has updated any feeds. Plugins can perform additional startup operations for themselves.
#bottomFeederQuitting: RSSFeedViewer instance - the main BottomFeeder window Sent after the BottomFeeder feed viewer application model has terminated, but before the containing Smalltalk image has been terminated. Plugins can perform additional termination operations for themselves.
#newItemsFor: aFeed Sent when there are new items for a feed (after a manual update, or via the update loop).
#newItemsForAlert: aFeed Sent when there are new items for a feed which is set for alerts (after a manual update, or via the update loop).
#removedFeed: aUrl Sent when a feed is removed. The argument is the feed's URL; the removed feed is not available.
#quitting   Sent when the BottomFeeder image is going to quit. The image does not quit before the plugin method returns. (Sent by deployment image, only.)

A plugin only needs to register for the events it wants to handle; the others are ignored.

Contents


BottomFeeder Object Messages

BottomFeeder passes feed objects on some of the API's listed in the previous section. This makes it possible for the plugin to send messages to those objects to request various services. The obvious questions to ask are, "What services?" and "What messages?"

At this point in the development of BottomFeeder, these questions can only be answered by repeating that you have to be a VisualWorks Smalltalk programmer. If you are, download a VisualWorks development image from Cincom Smalltalk Downloads, and a copy of the current BottomFeeder bundle from the Public store. Look for class RSSFeed in the RSSViewer-Domain package.

Contents

BottomFeeder Home Page

The End