Kit

Kit, a suite of page tools for Radio UserLand

Download Kit 1.2.1 (28 January 2003, zip)

Kit is a suite of "page tools" for Radio UserLand 8, including Weblog search, an improved News Aggregator page, a web Quick Script, "Radio to the Past" for changing weblog items' dates, a web outline editor, a per-category weblog index, a subscribed feeds lister, file uploader, and the Kit dashboard. Kit is published under a BSD license.

Installing Kit

1. Unzip Kit20030128.zip to your Radio Tools directory.

2. In the Radio application, select Tools->Kit->"Install pages to..." and enter the directory to which to publish Kit's pages. For example, if you enter system, your Kit pages will be at http://127.0.0.1:5335/system/ . Installing to system\pages (or system:pages) will overwrite some of Radio's default system pages with Kit's enhanced versions; this is suggested, but if you want to leave Radio's pages alone, feel free. (If the Tools->Kit menu isn't present, you may need to restart Radio.)

If you have problems with install, find a bug, or have any comments or questions, email me at kit@markpasc.org with a description of your situation.

Using Kit

After installation, open your browser and point it at http://127.0.0.1:5335/Kit/. Radio will forward you to the Kit Dashboard. The dashboard has links and basic forms for Kit's other pages, and your Radio Status Center (just like on the Home Page).

Some features will only be enabled after checking them on the Kit Preferences page. The HTTPS news aggregation feature requires the free Macrobyte TLS for Radio client software.

Using News Aggregator

This is an enhanced version of Radio's own News Aggregator page. At the bottom is a form for controlling what news items are shown. By default, the page shows all items scanned in the last hour.

You can assign feeds to categories on the News Preferences page. The dropdown at the bottom of the News Aggregator page will let you view the feeds in a particular category. You can also set background colors for particular feeds on the News Preferences page.

Kit's News Aggregator can fix broken HTML in your scanned news items. Check the "Repair improper HTML in news items" box in the Kit Preferences page, and Kit will do its best.

By default, News has a simple CSS layout that resembles the stock News Aggregator's. If you want, you can hack at the strings at the top of the file to put the news items in a different (even table-based) format. Look for the script at the top that sets the preText, postText, channelText, and itemText variables.

Using TrackBack

After enabling TrackBack in the Kit Preferences page, it will show in the weblog post form. Paste the TrackBack URL into the box, and when your post is posted, the URL will be pinged with TrackBack.

Using Do

Do is a web-based Quick Script. Enter the UserTalk script you want to execute and click "Do." To repeat a recently executed script, click the corresponding "Do:" button.

If the expression returns a table, outline, or script, Do will "pretty-print" the result. That means Do is also (somewhat) useful as a table browser.

Be aware that Do can do unsafe things like print your passwords to the screen, which is bad if done remotely and in plaintext.

Using Search weblog

Enter your search query and options. Search weblog will show the results, rendered in your #itemTemplate. If your #itemTemplate includes the <%editButton%> macro, it will be shown so you can easily edit those items. Permalinks rendered as relative links will not point at the actual item.

Using Edit outline

Edit outline is a web-based outline and script editor, using the JavaScript and CSS code from Joshua Allen's XSLT for OPML. I wrote bits that tie the JavaScript into Radio, and modified the JavaScript to use the standard DOM and different key sequences.

Enter the address of your outline or script--such as workspace.blog.outlines.todo or StaplerSuite.tools.stripHtml--in the form field, and click "Edit." The page will reload with the outline in it.

If you don't see the outline, or it's qualitatively different from the screenshot, your browser may not support the CSS, DOM, DHTML type stuff the outline editor requires. The editor also may not work in Internet Explorer, since I can't easily debug JavaScript for it.

Click the arrows to collapse and expand trees. Click a line's text to select it, then operate on it with these keys:

Keys for the outline editor

Key	Function
ctrl-K	Edit the link
ctrl-\	Toggle comment
F2	Edit the text
ctrl-Enter
Insert	Add new line
Delete	Delete selected
ctrl-Up	Move the selected line around, like in Radio's outline editor
ctrl-Down
ctrl-Left
ctrl-Right

Edit outline has callbacks for when an outline is saved. These callbacks should be in the KitData.callbacks.edit.save table, and have the signature scriptName (adrOutline).

Feeds

feeds.txt generates a list of your subscribed feeds; the file is suitable for moving to a published directory for upstreaming. It's like Jon Udell's, but is intended as its own page (I have a lot of feeds). It also strips out passwords in feed URLs, and yields for local (http://127.0.0.1:5335/...) feed URLs.

Tweak it in a text editor if you like.

Category Index

Category Index (categoryIndex.txt) provides navigation for your (possibly topical) categories for which you don't want a full HTML rendering. Copy the categoryIndex.txt as index.txt to your categories' directories. Check the "Update category indices" checkbox on the Kit Preferences page to automatically upload these indices when you post to their categories.

Put file

Put file lets you upload a file directly in your browser. Select the file to upload, where to put it, and hit "Put." Easy.

Where to put the file can be a folder or a full filename. If you specify a folder, Put file will use the same filename the browser tells Radio the file had on the uploading system. If you specify a full filename, any folders that must be created to put the file there are created--so don't inadvertently transpose two directories in the path!

There's currently a bug in which Put file doesn't understand the filename IE says the file had on the local system; if you use IE, specify full filenames.

Radio to the Past (and Future)

Radio to the Past is the colloquial name the Radio discussion group gave being able to change the date on a weblog item. This tool allows you to change the date of an item you posted to the weblog. Enter the post ID (look for the itemToEdit argument in the "Edit" link on the Home Page), set the date, and go.

A Radio to the Past date selector also appears on the weblog post page, if you select the "Toggle Radio to the Past" option in Radio's Tools->Kit menu.

NOTE: Radio to the Past is fairly experimental. You probably shouldn't use it yet if you find parts of Radio bewildering.

Radio to the Past is also Radio to the Future: if you specify a time in the future, the post will be held in reserve (or cryonic suspension if you prefer) until the time you posted it (or up to a minute after). Then Radio to the Past will post (thaw) it to your weblog like any other item.

Another gotcha: unless you've done massive customization, moving items around in the past breaks Radio's permalinks. (Insert space-time continuum joke here.) If you plan to use Radio to the Past a lot, you may want to use an alternative set of IDs for your permalinks; Radio to the Past provides three functions for this:

KitSuite.past.itemnum

Returns just the numerical tag for the item. Use in a comment URL or anywhere you need just a number. (I know YACCS has problems with non-numerical item IDs.)

KitSuite.past.permalinkID

Returns the anchor name; HTML anchor names can't start with a numeral, so this is "i" followed by the itemnum above. Use in an <a name/> or as a container ID.

KitSuite.past.permalinkUrl

Returns the permalink URL with the permalinkID for its #anchor. Use this in an <a href/>.

Each function takes the item's real itemnum as the argument. For example, you'd call KitSuite.past.permalinkUrl with something like:

<a href="<% KitSuite.past.permalinkUrl ("<%itemnum%>") %>">#</a>

Also, Radio to the Past's mechanism is exposed enough for other program authors writing weblog import tools to use. Call KitSuite.past.toPast (adritem, when, touch:false) and Kit will put the weblog item table at adritem in the right place in weblogData.root. when is the UserTalk date value at which to place the item. If touch is true, toPast will mark the affected weblog archive pages for upstreaming (so if you're importing a bunch of items, pass false).

Version history

1.2.1, 28 January 2003: Error when setting Kit preferences with HTTPS subscriptions enabled fixed. Error in News page when fixing HTML nesting was disabled fixed.

1.2.0, 19 January 2003: The just-links category index page displays item titles correctly. News Preferences can now clear colors and categories. View all items of a particular feed (the "hourglass" view) like on Radio's news page. Kit's link on the Tools page forwards to your Kit Dashboard. Weblog search will search both titles and bodies. News has a "Show all aggregated news" option (mainly for searching). News repairs broken HTML (unclosed tags and attributes) in news items. Publish RSS using your item template (your permalinks, comments links) including with expanded shortcuts (I think). Ping TrackBack URLs when entering a weblog item. Subscribe to news feeds over SSL (HTTPS); requires Macrobyte's SSL client software.

1.2.1, 28 January 2003: Error when setting Kit preferences with HTTPS subscriptions enabled fixed. Error in News page when fixing HTML nesting was disabled fixed.

1.2.0, 19 January 2003: The just-links category index page displays item titles correctly. News Preferences can now clear colors and categories. View all items of a particular feed (the "hourglass" view) like on Radio's news page. Kit's link on the Tools page forwards to your Kit Dashboard. Weblog search will search both titles and bodies. News has a "Show all aggregated news" option (mainly for searching). News repairs broken HTML (unclosed tags and attributes) in news items. Publish RSS using your item template (your permalinks, comments links) including with expanded shortcuts (I think). Ping TrackBack URLs when entering a weblog item. Subscribe to news feeds over SSL (HTTPS); requires Macrobyte's SSL client software.

1.1.7, 26 July 2002: Search results' permalinks now point to the published item. Clicking the time data fields on the News Aggregator page in Mozilla doesn't put the focus on the radio button, merely selects it.

1.1.6, 16 June 2002: A Radio to the Past date selector optionally appears on the weblog item post page.

1.1.5, 25 May 2002: The News page has a link to the subscriptions page. When removing its files from the system\pages or system:pages directories, Kit replaces the original files.

1.1.4, 23 May 2002: Radio to the Past had problems when categories were disabled; this is fixed. Radio to the Past's code for discerning the item number one entered was improved, so "Edit" link URLs should in fact work now.

1.1.3, 22 May 2002: Radio to the Past flat-out didn't work. This is fixed.

1.1.2, 14 May 2002: Radio to the Past wouldn't really move items, just copy them. Also, sometimes Radio would present the Radio to the Past CSS file rather than the HTML file. These are fixed.

1.1.1, 13 May 2002: Radio to the Past can now place items before item #1; the year option correctly reflects the selected item's year; the table-moving crasher bug mentioned in the announcement should no longer occur. (Thanks, Jeremy Bowers and Jake Savin.) The Feeds page handles malicious services with blank channel titles (such as Geeknews.net) more correctly. The Dashboard page is now automatically generated when Kit's pages are written out.

1.1.0, 12 May 2002: The Radio to the Past (and Future) tool was added. The Search page can search in either item bodies or titles. The Search page would error when the "Automatically generate item links" feature was enabled. (Thanks, Mark Woods.)

1.0.1, 2 May 2002: News' form's category selector was ill-behaved. Clicking in time-selection fields selects the correct time mode now. If a script in Do returns a table or outline, they are printed with renderObject and appropriate renderers (the previous table display code is factored into a renderer script).

1.0, 29 April 2002: News' form is redesigned. Showing by time limits now supplements rather than replaces showing by duration and offset. Viewing by category works. Not unsurprisingly, my patience ran out before the 0.9.x version numbers did. Kit is now self-proclaimed shareware.

0.9.6, 18 April 2002: Search now understands the new <%commentLink%> and <%itemTitle%> macros. (Thanks, Phil Wolff and Rob Jorgensen.) An HTML typo in News prevented the post link from working in browsers that didn't DWIM; no longer. (Thanks, Jim McGee.) A "News Preferences" page for specifying colors and categories for feeds was added; the pseudomacro <%color%> in the channel and item templates are replaced with the empty string, or background-color: color; if a color is defined for that channel.

0.9.5, 24 March 2002: "Put file" correctly handles specifying a filename as where to put; it still incorrectly interprets the filename given by IE. "Edit outline" has outline-saved callbacks. "Do" handles returned tables more usefully.

0.9.4, 17 March 2002: "Put file" page and "Toggle category index updates" menu option added. Search results are displayed most recent first. Edit outline correctly no longer errors on only a GET parameter. "Install pages to..." doesn't delete pages if installing to the same directory, which previously resulted in uninstalling the pages.

0.9.3, 9 March 2002: Feeds list doesn't show "user:pass" logins anymore. Feeds list shows the upstream URL if a service URL starts with http://127.0.0.1:5335/. Feeds list alphabetizes by channel name instead of XML URL. Outline editor uses real owner data for its interim OPML, instead of claiming you're Bob Vila. Outline editor correctly changes outlines when submitting one in the form but one is already specified in the URL, handles scripts, and escapes HTML in outline text. Do abbreviates long scripts, and correctly deletes old scripts to make room for new ones. Category index looks each minute for new items so it can update categories' index pages. Kit remembers where you installed its pages, and keeps them there; if you change where you installed them, they are deleted from the old directory.

0.9.2, 4 March 2002: Fixed News Aggregator's "post" buttons. Added Feeds list and category index page. History for Do still doesn't bump after filling.

0.9.1, 25 February 2002: Added outline editor, 7-item history for Do. HTML in News page exposed for easier editing. The "Install pages to..." menu option always writes the pages, overwriting any changes to the files in the filesystem.

0.9, 23 February 2002: First public release. Contained do, search, and news pages.