A plugin for Scripteur is officially called a Scriptibition, because official names should be humorous and fit into the thinly veiled and tenuous metaphor that Scripteur is based on. However, we shall refer to them simply as plugins in the documentation.
A plugin is a Bundle which contains an AppleScript. The AppleScript can implement two handlers; handleGET( urlRequest, headers ) and handlePOST( urlRequest, headers, parameters ). When Scripteur receives an HTTP request from an HTTP Client (aka, a web browser), it passes the request to the appropriate plugin as follows:
If the HTTP request is for a file, defined as a URI with no trailing slash (eg.: http://localhost:port/ituning/ituning.css), then Scripteur will simply look in the plugin's bundle for the requested file and either respond with that file or a 404.
If the HTTP request is for a folder, defined as a URL with a trailing slash (eg.: http://localhost:port/ituning/playlist/), then Scripteur will invoke the appropriate handler from the plugin's script. handlePOST will be invoked for HTTP POST requests; handleGET for HTTP GET requests.
The handler parameters are in the following form:
The default installation place for plugins is "/Library/Application Support/Scripteur/". They can also be installed in "~/Library/Application Support/Scripteur". You can open any of the default plugins by control-clicking on one in the Finder and selecting "Show Package Contents"
The Info.plist file must contain the following entries:
This file is not required, and is only useful if the script makes reference to it. If the plugin returns html from a handler as follows:
<html>
<head>
<title>MyFirstScriptibition</title>
<style>
@import "style.css";
</style>
</head>
<body>
FLASH
</body>
</html>
the client will make a subsequent request for the file "style.css" and Scripteur will automatically look for the file in the plugin's bundle.
This is the main script named in the Info.plist with the key ScripteurMainScript. This script should provide the handleGET and handlePOST handlers.
The AppleScript handlers have two choices for return values. The handler can return a value of type alias in which case Scripteur will send the file described by the alias. The handler can also return a string value which Scripteur will convert to UTF-8 and send to the client.
return a file:
on handleGET( urlRequest, headers )
tell application "Finder"
return (file "public_picture.jpg" of folder "Public" of home) as alias
end tell
end handleGET
return a string:
on handleGET( urlRequest, headers ) set theHTML to "<html><head><title>scriptibitionist</title>" set theHTML to theHTML & "<style>@import \"style.css\";</style></head>" set theHTML to theHTML & "<body>FLASH</body></html> return theHTML end handleGET
Scripteur will call this handler when it receives a GET request for a folder URI. The requested URL will be passed to the handler in it's relative form. The urlRequest parameter will be of the form "/pluginName/path/to/folder/" where pluginName is the value specified for ScripteurServiceName in the plugin's Info.plist.
The HTTP headers for the GET request will also be passed to the handler in the form of an AppleScript list. For example, the referer header can be obtained with the following snippet:
on handleGET( urlRequest, headers )
repeat with aHeader in headers
if aHeader contains "Referer" then
set i to (offset of ":" in aHeader) + 2
set n to length of aHeader
set theReferer to (characters i thru n of aHeader)
exit repeat
end if
end repeat
end handleGET
Similar to handleGET, but a parameters list is passed in as well. This allows your plugin to provide interactive forms for a client. Consider the following HTML form:
<form> <input type="hidden" name="method" value="flash" /> <input type="submit" name="button" value="flash" /> </form>
This form will trigger a handlePOST event when the client clicks on the button and the following AppleScript will extract the value of the method parameter:
on handlePOST( urlRequest, headers, parameters )
-- find the method parameter
repeat with aParameter in parameters
if item 1 of aParameter is "method" then
set theMethod to item 2 of aParameter
exit repeat
end if
end repeat
end handlePOST
Debugging plugins is not fun. You can't set breakpoints in AppleScripts, so you have to do some trial and error. If the script encounters an error while being run, the error message will be displayed in the browser.
There is one debugging feature so that you don't have to quit and restart each time you make a change to your plugin. Simply double-click your plugin to reload it or to temporarily install the plugin if it is not located in the plugin folder.
More help is available on the mailing list. Subscribe and ask away.
© 2003 Michael Robinette. part of the inkspotting family.