Enabling Category-Specific Stories

By Mark Woods, February 22, 2002

Note: I revised this story on 2/27/2002. At Russ Lipton's suggestion I moved the macro in Step #5 into Radio as a generic macro for generating story indexes for any category. Revised again on 3/8/2002 to enable category-specific names and description in banner (see step #8).

I am running two separate websites through my copy of Radio. One site is public - my community site - intended for anybody to read and containing stuff not directly related to my employer. The other site is private to those within my employer's firewalls. It is work related stuff that few others would really care about or my employer does not allow me to share. Radio's categories feature works great for separating these two sites and allowing common content to flow from one source to both sites. I have hit a small stumbling block with stories, however. Most of the stories I write are for internal use, but every now and then I have one I want to share on my community site. I decided to take a crack at enabling stories that are category specific - with the goal of not modifying Radio to do it. I have achieved my goal (thanks to Radio's great flexibility).

Before doing all this work, let me state a caveat. Radio itself does not yet support category-specific stories in its user interface. That means that you will not be able to create stories that are specific to a category through the browser UI. You can do it from the file system and then work with them through the Folders page. Also, there is no way to share stories across multiple categories. You will need to copy them instead. Finally, I highly advise reading through all the steps before proceding. Here is how I set things up.

Step by Step

One: The first step is to plan what you want to achieve. If you already have public stories and just want to enable stories for a specific category, things are a bit easier. You can skip down to step Five. If, like me, you are currently upstreaming your stories folder to one site and your blog to another, then you need to move things around a bit first. Two: Turn off Radio. Radio is always looking for changes to files or new folders and files. Since you are going to be moving folders around, Radio will assume you want those "new" folders to be upstreamed. You do not want this to happen until you have everything put in place - especially the changes to the #upstream.xml files themselves. Three: Move the stories directory underneath the category you want those stories associated with. You could do this with multiple categories too; just create the appropriate stories subfolders (within a category) and move/copy your stories content into the subfolder. To the right you can see what my directory structure now looks like. Note the Stories directory underneath the "ict" category. Stupid name, I know. Four: Delete the #upstream.xml folder in your new stories subfolder. The stories folder will then be upstreamed to the same site as the category content, but into a subfolder named Stories - just the way you want it. Five: OK, we should all be back on the same path now. At this point we have the stories folders set up the way we want. Radio should be upstreaming everything to the proper location (don't start Radio just yet if you have it shut down already). However, the index for our new stories folder will not render correctly. The macro that is in the index.txt file (in the stories folder) assumes that all stories are located in the "normal" Radio stories subfolder. This is usually Radio Userland/www/stories, but you may have modified that setting. That means your category index of stories will show all of the stories from the main stories folder. Clearly not what we want. There are several ways to solve this problem. I decided to write a macro (viewCategoryStoryList) that will create a reverse chronological list of stories for a specified category. You can download and use the viewCategoryStoryList I created. This is not a Fat page, you will want to download it as a file. Some Mac users have reported problems with the file name being truncated on download as the file name is longer than 31 characters. If your system does not support long file names, rename the downloaded file to viewCategoryStoryList.ftsc . After downloading, open the file within Radio. Long Note: I created the macro to reside in user.radio.macros, a table that does not, by default, exist in Radio. You will need to create this table yourself if you want to store the macro there. To do so, use Ctrl-J (Jump Window), enter "user.radio". When the user.radio edit window is opened, use Radio's Table/New Sub-Table... menu to create a new subtable named "macros". End of Long Note. Radio will prompt you to load it into user.radio.macros. Feel free to change the location and the name, but do remember both. This is pretty much a copy of Radio's radio.macros.viewStoryList macro with a couple of modifications. First, I altered it to look in the appropriate category's story subfolder (the subfolder name must be passed as a parameter). Second, I modified the list of stories to be sorted in reverse chronological order (most recent first). Third, I filter out images or any files that have a directive named "flindex" set to false. Edit the #index.txt file for the category's stories subfolder. It should have a line of code that looks like: <%radio.macros.viewStoryList ()%> Change it to: <%user.radio.macros.viewCategoryStoryList ("put your category name here")%> If you changed the name or location of the macro, modify this line of code accordingly.

Six: Now we can fire up Radio again (if you happened to have it shut down. Warning - if you went through steps 1 - 4, moving your stories folder, there is a chance Radio will now be confused. Radio keeps track of all publishable files and folders in a special structure. By moving folders we have knocked that out of whack. I do not fully understand why, but when I went through this step Radio went nuts upstreaming - mostly deleting files from my community site on radio.weblogs. In fact, my whole site went dark for a bit because all of the files were deleted. If this happens to you, open up Radio and look for the Radio/Publish/Entire Website menu item and select it. This will clean up Rado's internal file structure and republish your whole website. This process can take several minutes.

Seven: This step requires a little programming in Radio, but it is not too hard to do. Radio is really smart about regenerating your stories index page whenever you add a new story or delete an old one or change an existing one. It does this using a callback. The actual callbacks performed can be found in radio.upstream.callbacks.upstream. Every script in that table is called whenever an upstreaming operation is performed. You will notice that one of them is named updateStoryList. That is the script that regenerates your story index. We want to perform something similar to regenerate our category's story index, but without modifying Userland's code in Radio. Userland, thankfully, has provided an elegant exit for us. Everytime these callbacks are invoked, Radio looks for a similar set of callbacks in user.radio.callbacks.upstream. You may already have an entry in here for the myPictures tool. We can add an entry, a modified version of updateStoryList, to this table. Download this file and open it up in Radio. Note: As in step 5, some Mac platforms do not support long file names. Rename the downloaded file accordingly by trimming off the "upstream" prefix. Allow it to be loaded to the default location (user.radio.callbacks.upstream). You can change the location if you want to view it before installing it. Just remember to eventually get it copied to that location so Radio can invoke it. Radio will invoke this callback every time an upstream operation takes place. I tried to make the modification generic enough to work for anybody, but you may want to look it over before copying it. I just extended the existing macro to check each category's stories table to see if it contains the file just rendered (thus indicating that the index itself should be updated).

Eight: Thanks to Eldon Brown for pointing out that while this works fine, the category-specific stories carry the name and description from the main weblog in their banner. If you want your category-specific stories to use a category-specific name and description in the banner, you need to make two small changes to the #prefs.txt and the #template.txt files. Start by editing your category's #prefs.txt file. There should be a #categoryName entry present. If not, add one (e.g. #categoryName "My Good Category"). Also add a categoryDescription directive (e.g. #categoryDescription "Everything You'll Ever Need"). Save #prefs.txt. Now edit the #template.txt file - you will probably need just one of these, shared across all of your categories (so plop it in the "category" directory, if you haven't already). Look for the <%siteName%> macro. Change it to <%categoryName%>. Close by you will find a <%description%> macro. Change it to <%categoryDescription%>. When Radio renders your story it will pick up the directives you placed in the #prefs.txt file and substitute them for the corresponding macros in the #template.txt file.

Finished!

That should do it. You should now have category-specific stories working - complete with an automatically updated index document whenever you add a story. Note: I did notice that story deletions do not cause the index to regenerate. I think this is true of Userland's story support in general, but I could be wrong. You could gain this support by copying the updateCategoryStoryList macro into user.radio.callbacks.upstreamFileWasDeleted, I think.