IRCmagic Plug-in API

Overview of IRCmagic Plug-ins

At the heart of IRCmagic is a fast, lean plug-in engine. IRCmagic's plug-in engine makes it possible to add and remove plug-ins on-the-fly, without disrupting other functions of IRCmagic. Plug-ins written for IRCmagic are able to respond to every event that Ircle sends. IRCmagic optionally saves plug-in settings whenever the plug-in is unloaded, and restored when the plug-in is loaded again. IRCmagic also automatically provides a user interface to allow users to enable, disable, and configure your plug-in. Lastly, IRCmagic plug-ins are very similar to stand-alone scripts - so it takes little effort to port an existing script to an IRCmagic plug-in.

A plug-in template named "PluginTemplate.as" is included in the Documentation folder of IRCmagic. The template contains the basic elements required by all IRCmagic plug-ins, and serves as a starting point for creating new plug-ins.

This section shows you how IRCmagic plug-ins are constructed, and provides a short tutorial on building your own plug-in.

The Anatomy of an IRCmagic Plug-in

IRCmagic plug-in scripts are simply normal Ircle scripts with some additional properties and handlers.

Certain properties and handlers must exist in a plug-in script in order for it to be compatible with IRCmagic's plug-in engine. These required properties and handlers allow IRCmagic to communicate and control plug-ins, and allow IRCmagic to provide support to all plug-ins in a standard way.

Five properties must exist in a plug-in for it to be compatible with IRCmagic's plug-in engine. These properties are described in detail below:

In addition to these properties, plug-ins may provide additional properties to enable optional plug-in support functions. These optional properties are listed below:

The IRCmagic plug-in template declares four additional properties for your convenience. These properties are also optional. In the plug-in template they are initialized in the InitPlugin() handler, and used in various handlers in the template:

Five handlers must exist in a plug-in for it to be compatible with IRCmagic's plug-in engine. These handlers are described in detail below:

The following handler is only required if your plug-in contains the pCustomStringTags property, and the property is not empty. If the pCustomStringTags property is not found in a plug-in whn the plug-in is loaded by IRCmagic, this handler will not be called by IRCmagic.

The following global properties and handlers are built into IRCmagic, and acessible to plug-ins. Plug-ins may call these handlers in the following manner: pMainScript's Handler(parameters)

(more handlers to come!)

Writing Your Own IRCmagic Plug-in - A Tutorial

This section steps you through building a simple plug-in using the IRCmagic plug-in template as a starting point. The plug-in we will build opens a query window whenever the end user sends or receives a private message or notice. We'll call this plug-in the "AutoQuery" plug-in.

1) Open the plug-in template file

Open the plug-in template file in your script editor. The plug-in template file is named PluginTemplate.as and is located in the Documentation folder in the IRCmagic folder.

2) Set Ircle handler list

We want this plug-in to receive the input, privmsg, and notice Ircle events. So the pIrcleHandlers property should be set like so:

property pIrcleHandlers : {"input", "privmsg", "notice"}

This property is located at the top of the plug-in template. IRCmagic will call these handlers in this plug-in whenever Ircle sends those events.

3) Set custom handler list

The only custom handler this plug-in supports is the "AutoQuery" handler, which can be used by the end user to enable or disable the plug-in, or access the plug-ins settings. The pCustomHandlers property should be set like so:

property pCustomHandlers : {"AutoQuery"}

This property is located at the top of the plug-in template. IRCmagic will call this handler in this plug-in whenever the end user types /autoquery.

Write Ircle handlers

Now we will write the Ircle handlers that we specified in the pIrcleHandlers property. Locate the section labeled -- IRCLE EVENT HANDLERS in the plug-in template. Write the following functions in this section:

on input(con, target, theString)
if (theString starts with "/msg") then
set saveDelim to AppleScript's text item delimiters
set AppleScript's text item delimiters to {" "}
if (the number of text items in theString > 1) then
set recipient to (item 2 of (text items of theString))
else
set recipient to ""
end if
set AppleScript's text item delimiters to saveDelim
tell application "ircle"
if not (exists window recipient) then type "/query " & recipient in connection (con as integer)
end tell
end if
return false
end input

on privmsg(con, theNick, theHost, theChan, theStr)
tell application "ircle"
if not (exists window theNick) then type "/query " & theNick in connection (con as integer)
end tell
return false
end privmsg

on notice(con, theNick, theHost, theChan, theStr)
tell application "ircle"
if not (exists window theNick) then type "/query " & theNick in connection (con as integer)
end tell
return false
end notice

These handlers are called by IRCmagic when the input, privmsg, and notice events are sent by Ircle, and open a query window when the end user sends or receives private messages or notices.

Write the custom handler

All plug-ins are required to support one custom command to allow users to enable or disable the plug-in and optionally allow access to the plug-in settings. This custom command handler should be named the same as the plug-in file. In this tutorial, the command handler is named AutoQuery().

Custom handlers are not called directly by IRCmagic. Instead, IRCmagic calls the DoCommand(theCommand) handler, passing in the theCommand parameter the name of the custom handler being called. Locate the DoCommand() handler. Change the contents of this handler like so:

on DoCommand(theCommand)
tell application "ircle" to set con to argument 1
tell application "ircle" to set target to argument 2
tell application "ircle" to set theString to argument 3

-- branch off to custom handlers
if theCommand is "AutoQuery" then
my AutoQuery(con, target, theString)
end if
end DoCommand

When the end user types /autoquery followed by any text, IRCmagic calls this handler. This handler in turn calls the AutoQuery() handler in the plug-in. Next, we will write the AutoQuery() handler.

Locate the section labeled -- CUSTOM EVENT HANDLERS in the plug-in template. Write the following function in this section:

on AutoQuery(con, target, theString)
-- an example custom handler
try
-- get argument
set arg to ""
if ((the number of words in theString) > 1) then
set saveDelim to AppleScript's text item delimiters
set AppleScript's text item delimiters to {" "}
set arg to (word 2 of theString) as string
set AppleScript's text item delimiters to saveDelim
end if

if (arg is "on") then
my SetEnabled(true)
ShowMessage(pMyName & " is now on.")

else if (arg is "off") then
my SetEnabled(false)
ShowMessage(pMyName & " is now off.")

else if (arg is "set") or (arg is "") then
my Settings()

else
ShowMessage("The syntax for this command is: /" & pMyName & " on | off | set")
end if

on error errmsg
ShowMessage("AutoQuery() failed: " & errmsg)
end try
end AutoQuery

This handler is called by the DoCommand() handler when the end user types /autoquery followed by any text.

Congratulations. You have just written your first IRCmagic plug-in. To use your new plug-in, save it as AutoQuery and drop the script file into the IRCmagic plug-ins folder. With the plug-in loaded and enabled, a query window will open any time you send or receive a private message.