This is part of the Development Documentation Project, please help document Colloquy if you know anything that would be relevant here for other users to know about.
AppleScript PlugIns
- Getting Started
- Compatibility with scripts written for Colloquy 2C11 and before
- About AppleScript PlugIns
- Installing PlugIns
- Utility Script to Open the Colloquy PlugIns folder
- Loading PlugIns
- Example AppleScript Plugin for greeting friends
- Running AppleScript PlugIns
- Notification that a plugin has been loaded or unloaded
- File Format
- Some Example PlugIns
See also AppleScripting Colloquy in the Documentation
Attention: This page may contain old or outdated information and needs to be updated. If you have any question, feel free to visit us in the Colloquy chat room.
Getting Started
Download the latest version of Colloquy, so your plug-in won't be outdated as soon as you release it!
First you will need the AppleScript Script Editor.app (comes pre-installed with MacOS X) located in the folder "AppleScript" in your "Applications" folder. If you're using Mac OS X version 10.3 or later, click here to automatically launch the Script Editor application.
Now you want to open the AppleScript Dictionary for Colloquy by selecting "Open Dictionary…" from the Script Editor's File menu or by clicking the Add Application ("+") button in the Library Palette and select your Colloquy application (most likely located in your "Applications" folder; you may need to browse your file system to get there).
In the Dictionary Browser you just opened, select the "Chat Plug-In Suite". This describes the functions, your Plug-In can implement; they will be called by Colloquy when the corresponding event occurs. The other suites ("Standard", "Colloquy", "Chat Core" and "Text Suite") contain functions your Plug-In can call to perform actions in response to the events described before.
To understand how to use these commands it's probably a good idea to look at the examples below, or download existing AppleScript Plug-Ins from the Extras page.
To test your new Plug-In you need to install it like you would do with one you've downloaded.
Congratulations, you just wrote your first Colloquy Plug-In!
Compatibility with scripts written for Colloquy 2C11 and before
In order to provide enhanced scripting support, Colloquy’s AppleScript terminology has been completely re-written. Due to the extensive nature of the scripting enhancements, scripts written to work with previous versions of Colloquy are not guaranteed to be compatible with the 2D9 release. All scripts should be validated against the AppleScript dictionary in Colloquy 2D9.
About AppleScript PlugIns
AppleScript PlugIns are just AppleScripts which run in a very specific context. When Colloquy launches, it loads all the PlugIns found in one of three expected locations. PlugIns can contain code to handle events such as
- Connecting or disconnecting from a server
- Joining or leaving a channel, or getting kicked
- Sending or receiving a message
- Idling (a regularly called event which allows a plugin to update regularly)
- Someone else joining, leaving or getting kicked from a channel
- A channel topic being changed
- Getting a reply from a server following a 'raw code' command
In addition, the user interface itself can produce events which can be sent to PlugIns, such as
- ctrl-clicking (or right-clicking) on a user-interface item (producing a contextual menu),
- selecting a plugin-created item from a contextual menu.
- clicking a URL in the chat text
Finally, plugins may contain handlers which are called when the plugin itself is loaded or unloaded. This gives the plugin an opportunity to perform any initialization or cleanup procedures.
If you are editing a loaded plugin in script editor, save it, and then switch to Colloquy, you will be given the opportunity to unload the old instance and replace it with the new one that you have just saved. In most cases this is desirable. (Click on the 'reload' button). When this happens, the unload handler of the old instance will be called, and then subsequently the load handler of the new instance will be called. Only those plugins whose script file on disk have changed will be reloaded.
See below for an example using the load and unload handlers.
Installing PlugIns
PlugIns can be installed in one of the following places:
In the user domain (applies to only one user):
~/Library/Application Support/Colloquy/PlugIns
In the system domain (applies to all those that have user accounts):
/Library/Application Support/Colloquy/PlugIns
In the network domain (becoming available to remotely connected users with ):
/Network/Library/Application Support/Colloquy/PlugIns
Utility Script to Open the Colloquy PlugIns folder
This script will open ~/Library/Application Support/Colloquy/PlugIns (i.e. the user domain)
set appSupportFolder to (path to application support from user domain) as string set colloquyPluginsFolder to appSupportFolder & "Colloquy:Plugins:" as alias tell application "Finder" open colloquyPluginsFolder activate end tell
Click here to open the script in Script Editor
If you wish to use one of the other plugins folders, change user domain to system domain or network domain.
Save this script in ~/Library/Scripts/Colloquy/ or ~/Library/Scripts/Applications/Colloquy/ so that you can call it from the script menu.
Loading PlugIns
AppleScripts saved in the plugins folder can and will be loaded with
/reload plugins
after which time the various events they 'trap' will be invoked at the appropriate moment. If you update your scripts, be sure to save them and /reload plugins again to get the latest instances loaded. (The newest nightly builds include commands for loading plugins on an individual basis. They will also offer to automatically reload any new versions of already-loaded plugins when you switch to the colloquy application from -say- Finder or Script Editor).
For example, if your script has a handler for member joined, then whenever a new member joins the chat room, that handler will be called, and your script can take appropriate action, such as automatically greeting anyone from a list of friends. (See below for an example of this).
AppleScript PlugIns are just AppleScripts which run in a very specific context. The default 'tell target' for these scripts when invoked is application "Colloquy".
AppleScript requires the application providing the scripting terminology used in a given script to be specified either with 'tell application X' or 'using terms from application X'. Without this, it would be impossible for the AppleScript compiler to construct the proper Apple Events.
You will therefore need to reference the application so that the script compiles with the correct terminology. For this reason, AppleScript PlugIns will almost always have the following line at the start of the script.
using terms from application "Colloquy"
If you omit this, your script will probably not compile, unless you use absolutely no Colloquy terminology, which is rather unlikely. Similarly at the end of your plugin script you will need to have
end using terms from
n.b. You could also use tell application "Colloquy" but this would represent a tautology at runtime because the script will already be invoked in that context. No harm will be done, but 'using terms from' is more 'correct'.
Example AppleScript Plugin for greeting friends
Here's an example plugin which will greet certain 'known' people when they join a 'watched' room:
property friends : {"bill", "ben", "weed", "the_gardener"}
property watchedChatRoomz : {"watchWithMother"}
using terms from application "Colloquy"
on member joined whoArrived in whichChatRoom
if watchedChatRoomz contains (whichChatRoom's name) then
set n to (whoArrived's name)
if friends contains n then
tell whichChatRoom
send message ("Hi there " & n & " great to see you!")
end tell
end if
end if
end member joined
end using terms from
Click here to open the script in Script Editor
Running AppleScript PlugIns
AppleScript PlugIns are not usually designed to be 'run'. You can certainly include a run handler if you wish, but you must then take care of invoking it yourself, either by running it in script editor, or sending the run event to it in some other way. (AppleScript code not included in any handler is treated as 'run' handler code).
In other words Colloquy does not call the run handler. As a reminder, you may wish to add the following run handler to every Colloquy plugin script:
on run display dialog "Don't run me, move me to ~/Library/Application Support/Colloquy/PlugIns/ and type /reload plugins in Colloquy." end run
A more sensible initialisation choice than 'run' for initialisation routines may be the 'load' handler.
Notification that a plugin has been loaded or unloaded
The following plugin script contains some generally useful code which will notify the user that a plugin has been loaded or unloaded. The (short) name of the script is stored in a property variable so that it can be recalled when unloading. (The unload handler does not currently receive a parameter for where the script file came from, which makes some sense, because by the time unload is being called, the file on disk may well have changed).
property loadedScriptName : "" using terms from application "Colloquy" on load from scriptPath set scriptAlias to (POSIX file scriptPath) as alias set loadedScriptName to (name of (info for scriptAlias)) set msg to (loadedScriptName & " Loaded") as string set evt to (loadedScriptName & "loaded") as string tell active panel of front window add event message msg with name evt end tell end load on unload set msg to (loadedScriptName & " Unloaded") as string set evt to (loadedScriptName & "unloaded") as string tell active panel of front window add event message msg with name evt end tell set loadedScriptName to "" end unload end using terms from
Click here to open the script in Script Editor
File Format
When saving your scripts, if you are in any doubt, use the 'script' format, rather than Application, Text or a bundle format. More advanced AppleScripters will know when and how to use these other formats.
Some Example PlugIns
- A translation script : AppleScriptTranslation
- A hardware config/info script (using the System Profiler) : AppleScriptHardwareConfig
- Speak messages: AppleScriptSpeakAllMessages
- Colloquy Extras: PlugIns & Scripts
