Search

Members Join Now Login

Tools

Tools bring together all of the major areas of Frontier and Radio UserLand functionality, in a single place.

This page documents the Tools functionality for Frontier and Radio UserLand.

What are Tools? 

The Tools menu shows which Tools are currently installed. To invoke the functionality of a Tool, choose a command from its sub-menu.

Tools are easy to install and un-install. There's a folder in the guest databases/apps sub-folder of your Frontier folder named Tools. For Radio UserLand, the Tools folder is a sub-folder of the Radio UserLand folder.

Each Tool is a separate object database in the Tools folder. To install a Tool, put it in the Tools folder. To un-install a tool remove it. Frontier and Radio watch the Tools folder -- if a new Tool has appeared or a Tool has been removed, it will installed or un-installed.

The last command in the Tools menu is the Update command. To get the latest changes to a tool, bring its window to the front using the Window menu, and choose the Update command in the Tools menu.

If you're a developer, it's easy to create new Tools for Frontier and Radio UserLand

What gets installed 

A Tool may have a responder, nodeTypes, XML-RPC and SOAP handlers, a thread, scheduled tasks, a website, callback scripts, and a menu. All are optional.

Tools do not have an install script. When a Tool is placed in the Tools folder, the pieces it needs order to function are automatically installed into your database. Most are installed as addresses pointing into the Tool's database.

When a Tool is un-installed, these pieces are removed automatically.

How to create a new Tool 

To create a new Tool, choose the New Tool... command from the Developers sub-menu of the Tools menu.

You're prompted for a place to save the Tool. If you save it in the Tools folder, it will be installed when it's created. If you don't want your tool to be installed immediately, save it in another folder.

What a new Tool looks like 

When you create a new Tool, several top-level items are created for you. Every item's name starts with the name of your Tool. You can delete any items that you don't need. For instance, if your Tool doesn't need a responder, delete it.

Tables in a new Tool 

Data: Your data goes here. There's a sub-table named prefs for storing user preferences.

NodeTypes: Your nodeTypes go in this table, along with associated icons.

Responder: If your Tool has a responder, it goes here.

RpcHandlers: XML-RPC handlers are stored here.

SoapHandlers: Scripts in this table are handlers which respond to SOAP RPC requests.

Suite: Place your Tool's scripts in this table. Most Tools store the majority of the code that implements their functionality in this table.

Suite.background: Scripts which run scheduled tasks at regular intervals are stored in the background subtable. They are called by the scheduler.

Suite.callbacks: This subtable contains scripts which extend or override default functionality.

Suite.menu: This menu is installed as a sub-menu in the Tools menu when a Tool is installed.

Thread: A thread is a script that runs in a loop until the application quits. Threads give you more flexibility than scheduled scripts (above). You should use a thread if your tool needs to do something that's repeated regularly while other tasks are running, for example: watching a folder, or making an HTTP request at a periodic interval.

Website: A Website Framework responder website. The home page of your Tool's website is at /[name of your tool]/index.wsf. Websites for Tools designed for Frontier may also be in the mainResponder website.

Radio callbacks 

Tools can install callbacks in any of the sub-tables of user.radio.callbacks. These callback scripts are stored in the radio sub-table of your Tool's callbacks sub-table.

For example, if your Tool needs to install an upstream callback, create a script at myToolSuite.callbacks.radio.upstream. When the Tool is installed, its upstream callback script will be registered as an address value in user.radio.callbacks.upstream.

File menu callbacks for Radio 

Tools can over-ride and extend Radio UserLand's File menu.

For instance, you can create a script that gets called when the user chooses the Save command. If your Tool should handle saving the frontmost window, then it can over-ride Radio UserLand's built-in behavior and save the window.

Or, perhaps instead of handling the Save command you want to keep a record of every URL you open via the Open URL command. Instead of completely over-riding the command, you let Radio UserLand do its normal thing -- but your script stores the URL in an outline, so you can have a record.

Example 

In your Tool create a script at myToolSuite.callbacks.fileMenu.openUrl.

The script should look like this:

on openUrl (url)
	dialog.notify (url)
	return (false)

Save your Tool, so your callback script will be installed. (The Tools folder is checked every 10 seconds, so it may take a few seconds.)

Then try the Open URL... command in the File menu. In the dialog box, type in a URL.

What will happen is that your callback script will run first. It will display the URL you typed in a dialog box. Then Radio UserLand will do the normal thing.

Over-riding 

In the above example, we extended the Open URL command. We added a function to it, but it still did the normal thing.

This is because your callback returned false at the end. Returning false tells Radio UserLand: "I didn't take over this command -- you go ahead and do what you were planning to do."

When you want over-ride a command, you return true at the end of the script. This tells Radio UserLand: "I handled it -- you don't need to do anything."

So modify your callback script -- make the last line return (true). Now try the Open URL command. This time your dialog box appears -- and that's it. Radio doesn't do anything more.

Obviously, when you get beyond just doing examples, you'll want to have some logic in your callback for deciding whether your callback should handle it or not. For instance, your callback might handle all Open URL commands where the URL ends with a .xyz suffix.

In that case, your callback returns true if the URL ends with .xyz; it returns false otherwise.

List of Radio's File menu callbacks 

Here are the callbacks you can place in myToolSuite.callbacks.fileMenu. This list also includes the parameters they take. Note that this applies only to Tools for Radio UserLand.

new -- no parameters.

open -- no parameters.

openUrl -- one parameter, a URL (string).

close -- one parameter, the address of the window the user wants to close.

save -- two parameters, the address of the window the user wants to save, and a boolean which is true if the window is being closed.

saveAs -- one parameter, the address of the window the user wants to save as.

revert -- one parameter, the address of the window the user wants to revert.

viewInBrowser -- one parameter, the address of the window the users wants to view in the browser.

Tips 

When you're editing a Tool's menu, changes to the menu won't appear in the Tools menu until you save the database containing the menu. Bring the root file to the front and choose Save from Radio's File menu.

If you want to use the responder that's created by the New Tool command, you have to enable it in your Tool's database. Change the value of the enabled boolean in your Tool's responder sub-table to true.