River2 Blog News and updates about the River2 aggregator.

Donovan Watts asks: “Can you tell me how to export my River2 feeds? Installing River2 on my Mini & can’t figure out how to transfer feeds from laptop.”

1. From the River2 home page, click on FEEDS in the menu at the top of the screen. Scroll to the bottom of the page, where you should see a link that says: “View the OPML subscription list.” Click the link.

2. The OPML file appears in your web browser. Then choose Save Page As from the File menu of your browser (I use Firefox or Chrome, the command might have a different name in other browsers). Enter the name of a file and click Save.

3. Then, to import the OPML file into your installation, bring the OPML app to the front and choose Import OPML from the River2 sub-menu of the Tools menu. Locate the file you exported in step 2.

Note: I like to answer questions in blog posts instead of on Twitter because I get more than 140 characters to explain what’s going on. Also it’s easier for people to find an answer using a search engine, in the future. It often works better if you can ask the question in an environment which doesn’t have a 140-character limit. People often omit an essential piece of info in their request for info, and it’s even worse with the 140-character limit. If you can’t find a blog to post your question on, just post a comment here.

Matt Diaz is an incoming Studio 20 student and has been using River2. He had some questions — which I am answering here on the blog in case these come up for others.

1. He’d like to be able to organize the feed he’s subscribed to into separate streams that River2 saves into separate HTML files and pushed to Dropbox.

There is a way to do this, it works, but there’s no user interface to set it up. I use the feature on the east-village.org server, I have a stream for the East Village blogs, one for nyblogs.org and another for my own personal aggregator with the news feeds I’m interested in.

I think it’s a little too difficult right now to hack it in yourself. I need to create a UI that makes it possible to create new users for a River2 installation. Just know that it’s not too far from being real, and if you really want it, bring your laptop to the next meetup and I’ll see if I can get it to work manually.

2. He’d like to get rid of the small notice of news that right now is advertising nyblogs.org.

That’s totally cool. I could add a pref to turn it off, but in the meantime you could change the CSS for the site to shrink it down to 0 pixels. Open river.css in the River2 sub-folder of the OPML folder, and look for “caption.” That’s where you go to change the style of the caption. Just save it, and the next time the page is rendered it’ll use the new stylesheet.

3. He writes: “I was hoping you could clarify how items are organized on the River2 main page. The way I think it works is that items are displayed with the newest ones closest to the top. Then, if River2 pulls an item from a feed that has published another item recently, River2 lumps all of them together (with the newest item at the bottom), and puts the lump at the top of the main page. Does this sound right?”

That’s pretty close. Every hour River2 does a scan. For each feed it reads, it pushes all the new items from that feed onto the home page, at the top of the page. Then it checks the next feed, until it’s read all of them. It groups them this way so it’s easy to see what’s new, and then easy to associate each new item with the feed it came from.

See the earlier piece for a tutorial on what JavaScript includes are and how they work.

Today there’s a new feature in River2. If you have the Dropbox feature turned on, in addition of generating a static HTML page, River2 will also generate a JavaScript include file (index.js) and an OPML subscription list (index.opml) in the same folder as the HTML file. The screen shot below illustrates:

The OPML subscription list, index.opml, is of obvious value — it makes it possible to share your list with other users. It also backs up your list in a place that’s automatically synched with your other computers.

The JavaScript include file, index.js, file lets you include the result of the aggregator in another website. We’re going to use it as part of the nyblogs.org project to include the news in a WordPress weblog.

For an example of how it works, do a View Source on this page:

http://scripting.com/misc/includeDemo/

There are basically two moving parts — the stylesheet and the <script> that includes the .js file.

If you look in the stylesheet, you’ll see it defines styles specifically for River2. You can either copy the contents of the stylesheet, or if you have CSS skills, you can customize the look of the river when it appears in your site.

I’ve long felt that HTML should have an “include file” mechanism similar to the one that many programming languages have. When I lobbied for it in the early days of the web, the people at Netscape and Microsoft said they feared it would we abused. I didn’t think that was much of an argument because people were copying HTML anyway. View-source was one of the best things about the web. If you wanted to understand how something worked, it was always just a matter of looking to see how they did it.

Finally they relented, or maybe it was just an accident, a door they forgot to close, because with JavaScript they gave us the ability to incude a script within a page. And a script can generate text. So you just have to come up with a way to turn your HTML text into a script. It’s a very simple thing, even though it seems like an unnecessary step — you can automate it so it’s not a big deal.

I wanted to show the members of the Thursday evening group how this works, because we’re going to use this technique in nyblogs.org, to allow us to include the result of the aggregator inside a WordPress blog. But first a simpler example.

Create a text file on your hard disk, and call it test.html. Add this code to the file:

<html><body><script type="text/javascript" src="http://static.newsriver.org/afp/js/randomThumb.js"></script></body></html>

Save it, then drag the file’s icon onto Firefox (or whatever browser you use) and you should see an image on the page. If you click the image it’ll take you to the full version of the page. And if you wait a few minutes and refresh the page, the image will be different.

This is how the random image in the right margin on scripting.com is implemented.

I have a process on one of my servers that generates the randomThumb.js file and puts it in the same place every time. Try entering the URL of the script into the address bar of your browser.

http://static.newsriver.org/afp/js/randomThumb.js

And do a View Source.

You’ll see a “document.write” statement, and inside it — a bit of HTML. That’s the extra step I had to do to make this work. Instead of HTML code, the file contains JavaScript code, and it in turn generates the HTML we want to appear in the page. Convoluted, but it works. (This is what programmers call a klooge.)

My main River2 installation stopped finding new stuff a couple of days ago, and in the rush of iPad mania, I didn’t get to look into it right away.

The problem was caused by an update I released on March 30 that was part of a major overhaul that makes River2 a multi-user product. (There’s still more work to do on this.)

River2 should automatically update overnight, so if you leave it running, the fix that I just released should take care of any problems. However if you’re not leaving it running, or if you want the fix immediately, here’s what you can do.

1. Bring the OPML app to the front.

2. Choose river2.root from the Window menu.

3. Choose Update front tool from the Tools menu.

4. Click OK to confirm.

If you needed the update you should get one new or updated part.

Elasticthreads, the guy who asked for both Instapaper support and Dropbox support in River2, now asks that the two features be combined. An obvious desirable thing. And if you update river2.root, you can have the feature now.

Demo

Here’s my Dropbox-based river, with Instapaper icons.

How to update

1. Launch the OPML Editor.

2. Bring river2.root to the front.

3. Choose Update Front Tool from the Tools menu.

4. Click OK to the confirmation.

How to use

First, be sure that the Dropbox feature is enabled.

Second, be sure the Instapaper feature is also enabled.

Then if you view your River you’ll see that there are now Instapaper icons next to most items. If you click an icon, you are transported to the Instapaper site, where it confirms your username and password. Click on OK and then the story is added to your list of unread items. Click the Back button in your browser a couple of times to get back to reading your river.

If for some reason you believe you haven’t got a fully up-to-date copy of River2, here’s how you can be sure you’re fully updated.

1. Launch the OPML editor.

2. Choose Update opml.root from the File menu. Click OK to confirm.

3. Choose Tool Catalog from the Misc menu. Click on the Install link (shown in the screen shot below).

4. Click OK to confirm you want to install river2.root.

Released today: A new preference that allows you to quickly send any story from River2 to Instapaper so you can read it later on an iPhone or web browser. Once you have it set up, each item on your River2 home page will have an Instapaper icon. When you click it, the item is routed to Instapaper for later viewing on the web or in its iPhone app.

How to set up

1. Launch the OPML Editor.

2. Bring river2.root to the front and choose Update Front Tool from the Tools menu.

3. Choose Update opml.root from the File menu. (There are a couple of updates to make this feature work.)

4. Visit the River2 Prefs page. Near the bottom is a new set of prefs for Instapaper. Here’s a screen shot:

5. Click the checkbox to enable the feature. You must enter a username, but the password is optional. If you’ve set a password on Instapaper, you must enter that password here.

6. Click Submit.

Personal note`

I wasn’t an Instapaper user before adding this feature, thanks to elasticthreads for suggesting it. Now I love it. It’s very useful way to save stuff to read later.

I made a design mistake a long time ago in how Prefs outlines are included in Tools, and to make up for the mistake I added a feature, that sometimes I forget how to use. By leaving this note here, for the future, when I look it up in a search engine, I’ll be reminded how to do it. So unless you’re a maintainer of River2 or another OPML Editor or Frontier tool, you can skip this post.

The design mistake was naming the top-level table #installer. It should have been named river2Installer. That way the prefs outline would have a unique address and could be updated using the normal RSS-based updating mechanism. But I didn’t do that, so you have to do something special to update the various pieces of the #installer table.

Luckily this usually isn’t a problem because the code in the #installer table is meant to run once, when the tool installs, and the installer code in system.verbs.builtins.opmlEditor has no trouble finding it. The one exception is the prefs outline, which probably should not have been in this table.

So I added the option of indirection. If ["#installer"].prefs is a string (it’s important that it not be an address) then it’s interpreted as an address. So I have it pointing to river2suite.data.prefsOutline. That part can be updated using the normal RSS-based updating mechanism.

So that’s how you update the prefs outline, simply by updating river2suite.data.prefsOutline.

Voila!

This brings together a bunch of different threads, using one of my favorite software products in a new, almost surprising way. The idea was suggested by a user named elasticthreads in a very simple comment on the Frontier News blog.

Is it possible to serve up my NewsRiver via Dropbox?

I didn’t understand what he was asking at first, but then I thought about it and it all of a sudden made sense.

1. Suppose you want to have your river accessible anywhere, but you don’t want to invest in a server somewhere, but you have a desktop computer at home that isn’t doing much during the day. Why not have it create a river for you and publish it via Dropbox?

2. And Dropbox has a very cool feature for this kind of app. If you store a file in the Public folder at the top level of your dropbox, you can get a public URL for the file by right-clicking it and choosing Copy Public Link from the popup menu, as illustrated in this screen shot.

It works!

Just to show that it works, here’s my public river. (It’s a subset of the river I depend on every day, which contains some feeds I don’t want to show publicly, which illustrates an important point — be careful using this feature.)

How to set up

0. If you don’t already have river2.root, follow the instructions on this page.

1. In the OPML Editor, bring river2.root to the front and choose Update Front Tool from the Tools menu. Click OK when the confirmation dialog appears. (It’s possible your copy of River2 has already updated.)

2. You must have Dropbox running on your system. Locate your Dropbox folder. Create a sub-folder of your Public folder called River2. If you accepted the defaults, this is where your folder will be, first on Mac, second on Windows.

Macintosh HD:Users:yourname:Dropbox:Public:River2:

C:\Documents and Settings\yourname\My Documents\My Dropbox\Public\River2\

Replace “yourname” with your name. On my Mac my name is davewiner and on Windows it’s Dave Winer.

3. Visit the Prefs page for River2 (you can locate it in the Menu at the top of every page on the River2 site).

4. About 3/4 the way down the page you’ll see a section called “Dropbox”. Check the box to enable the feature. It’s turned off by default. Then carefully enter the path to your Dropbox folder. Scroll to the bottom of the page and click on Submit.

5. Bring the OPML Editor app to the front. From the River2 sub-menu of the Tools menu, choose Scan Now. This will read all your news, podcast and photo feeds, looking for new items. When it’s complete, if all goes well, you should see a file called index.html in the River2 sub-folder of the Public folder in your Dropbox.

5. Because it’s in the Public folder this file is publicly accessible. To determine its address, right-click on the index.html file name, and choose Copy Public Link from the Dropbox sub-menu in the popup. Paste the link into the address bar of your browser. You might want to bookmark it.

index.html will be re-built every time River2 does a scan. By default that happens once per hour, but you can change that using the Prefs command in River2. The images folder contains images that are needed to view the page. They are all synchronized through the normal Dropbox process.

If you have any questions, please post a comment below. If you want to share the address of your river, please do so. It’s always interesting to see how people are using the software.

Caveats

If you run River2 on more than one machine, you can only turn this feature on on one of them, otherwise they will write over each other.