How callbacks work in River4

I'm working on callbacks in River4. This page describes how it works, while I'm doing the work. Ultimately there will be a page on the blog about this feature.

The callbacks folder

1. There's a new sub-folder in the River4 folder, the same folder as the river4.js app: callbacks. Each sub-folder of callbacks stores scripts that are called on a specific event. Only files with the extension .js are run.

2. The addToRiver sub-folder of callbacks contains scripts that are called when a new item has been added to the river.

3. Each script in the addToRiver sub-folder is called once for each new item.

4. There's no guarantee of the order in which they run.

5. The scripts have three variables that are in scope when they're called: urlfeed, itemFromParser and itemFromRiver. urlfeed is the HTTP address of the feed. itemFromParser is an object containing all the data we received from FeedParser. itemFromRiver is the actual object in the river for today. You can add data or modify data in this record, and it will be saved to the river. The items you add can be accessed in other callbacks.

6. To be clear, you can modify any of the three in-scope objects, but only itemFromRiver will be saved.

Your first callback

Here's the script I wrote to test the addToRiver callbacks. You should be able to run it on your River4 installation.

To do so, launch River4. It should create a callbacks folder and an addToRiver sub-folder when the first new item comes in.

2. Save a copy of this script in the addToRiver sub-folder.

3. Wait until some new items come in.

4. Look in localstorage.json (see next section). You should see some data. Here's an example from my server after I ran it for a few hours.

localStorage.json

1. There's a new file maintained in your data folder, localStorage.json.

2. It contains the data your callback scripts save in localStorage.

3. It's a place you can store persistent data that will be around next time River4 runs. Unlike browser-based localStorage, you can store any type of data, not just strings.

Notes

1. If you modified itemFromRiver in the addToRiver callback, call todaysRiverChanged (), which tells River4 to save the structure at the top of the minute.

2. We don't roll over the day until there's been 60 seconds with no new items added to the river. We assume all the addToRiver callbacks will complete in less than a minute.

3. We save localStorage once a minute, if there were changes.