wiki:Development/PlugIns/AppleScript

TracNav(Development)? 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

  1. Getting Started
  2. Compatibility with scripts written for Colloquy 2C11 and before
  3. About AppleScript PlugIns
  4. Installing PlugIns
  5. Utility Script to Open the Colloquy PlugIns folder
  6. Loading PlugIns
  7. Example AppleScript Plugin for greeting friends
  8. Running AppleScript PlugIns
  9. Notification that a plugin has been loaded or unloaded
  10. File Format
  11. 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 [applescript://com.apple.scripteditor 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

[applescript://com.apple.scripteditor?action=new&script=set%20appSupportFolder%20to%20%28path%20to%20application%20support%20from%20user%20domain%29%20as%20string%0Dset%20colloquyPluginsFolder%20to%20appSupportFolder%20%26%20%22Colloquy%3APlugins%3A%22%20as%20alias%0Dtell%20application%20%22Finder%22%0D%09open%20colloquyPluginsFolder%0D%09activate%0Dend%20tell 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

[applescript://com.apple.scripteditor?action=new&script=property%20friends%20%3A%20%7B%22bill%22%2C%20%22ben%22%2C%20%22weed%22%2C%20%22the_gardener%22%7D%0Dproperty%20watchedChatRoomz%20%3A%20%7B%22watchWithMother%22%7D%0D%0Dusing%20terms%20from%20application%20%22Colloquy%22%0D%09%0D%09on%20member%20joined%20whoArrived%20in%20whichChatRoom%0D%09%09if%20watchedChatRoomz%20contains%20%28whichChatRoom%27s%20name%29%20then%0D%09%09%09set%20n%20to%20%28whoArrived%27s%20name%29%0D%09%09%09if%20friends%20contains%20n%20then%0D%09%09%09%09tell%20whichChatRoom%0D%09%09%09%09%09send%20message%20%28%22Hi%20there%20%22%20%26%20n%20%26%20%22%20great%20to%20see%20you%21%22%29%0D%09%09%09%09end%20tell%0D%09%09%09end%20if%0D%09%09end%20if%0D%09end%20member%20joined%0D%09%0Dend%20using%20terms%20from 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

[applescript://com.apple.scripteditor?action=new&script=property%20loadedScriptName%20%3A%20%22%22%0D%0Dusing%20terms%20from%20application%20%22Colloquy%22%0D%09%0D%09on%20load%20from%20scriptPath%0D%09%09set%20scriptAlias%20to%20%28POSIX%20file%20scriptPath%29%20as%20alias%0D%09%09set%20loadedScriptName%20to%20%28name%20of%20%28info%20for%20scriptAlias%29%29%0D%09%09%0D%09%09set%20msg%20to%20%28loadedScriptName%20%26%20%22%20Loaded%22%29%20as%20string%0D%09%09set%20evt%20to%20%28loadedScriptName%20%26%20%22loaded%22%29%20as%20string%0D%09%09tell%20active%20panel%20of%20front%20window%0D%09%09%09add%20event%20message%20msg%20with%20name%20evt%0D%09%09end%20tell%0D%09end%20load%0D%09%0D%09on%20unload%0D%09%09set%20msg%20to%20%28loadedScriptName%20%26%20%22%20Unloaded%22%29%20as%20string%0D%09%09set%20evt%20to%20%28loadedScriptName%20%26%20%22unloaded%22%29%20as%20string%0D%09%09tell%20active%20panel%20of%20front%20window%0D%09%09%09add%20event%20message%20msg%20with%20name%20evt%0D%09%09end%20tell%0D%09%09set%20loadedScriptName%20to%20%22%22%0D%09end%20unload%0D%09%0Dend%20using%20terms%20from 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

Last modified 11 years ago Last modified on Sep 25, 2006 9:33:26 AM