Scripting in ChatZillaFirstly, I'll explain how to get ChatZilla to use your scripts, then go on to the details for writting your own ones. Mini-Table of Contents
Making ChatZilla use my Scripts
You should now see two lists, each with the ability to change the order and add/remove items. The one we're interested in is the top one, Autoload scripts.
That's it, your script is in the ChatZilla script list and will be loaded next time you start ChatZilla. It's important to remember this - ChatZilla won't load any new scripts, or unload removed ones, while it's running. So, How do I Write me One of These Here Scripts?Well, firstly, remember these are JavaScript scripts. Also note that it's JavaScript 1.5. Yes, that's right, 1.5. This means, for the uninitiated, that it rocks. :) The basic idea about ChatZilla scripts is that anything not inside a function (i.e. the basic code) is evaluated as it's loaded, just like on a web page. This is where you set up everything else, or if nothing else, you call the functions to do the setting up for you. The setup code usually involves calling some ChatZilla routines to add "hooks" into your code. So What's a 'hook' Then?In the context of ChatZilla, they are basically instructions telling ChatZilla which bits of your code to run, and when. They usually take the form of some stuff to identify when to run the code, the function (in your script) to run at the appropriate time, and a text name for the hook (useful if you want to remove the hook while ChatZilla is running). For example,
client.eventPump.addHook([{set:"network", type:"nick"}], jgr_onNickChange, "jgr-nick-change-hook"); would tell ChatZilla to call the function in my code called jgr_onNickChange whenever something of type "network" got a message of type "nick". Don't worry if this makes very little sense right now, it will be explained later. You don't have to call any ChatZilla routines in your setup code, for example,
timUpdater2 = setInterval(jgr_onShowLag, 15000); simply sets up the function jgr_onShowLag to be called once every 15 seconds. Once your setup code has run, that's it for now - your script sits and waits for ChatZilla to call it when the events you are interested in occur. What Can I do in a Hook?Anything. That's the short answer, anyway. Basically, the entire JavaScript object model for ChatZilla (since it's an Object Oriented program) is accessible through the client variable, which you can access from any part of your script. Displaying TextIf your script adds commands to ChatZilla, you'll probably use the display function to show text in the current view. There are two ways to use display:
display("Hello!"); The first simply displays the text in the current view in ChatZilla. The second also displays the text in the current view, but it does so in the style you specify (in the example, "ERROR" was used). Some of the useful styles are: HELP, ERROR, WARNING and INFO (the case is important). Don't over use this function, since it always displays in the current view in ChatZilla, anyone using your script might get annoyed at messages appearing repeatedly. I recommend only using this function if the user has done something that activated your script, otherwise you should use the functions below to display the message in the appropriate view. Getting Information About the EventIf you specify a hook using the client.eventPump stuff shown earlier (details on how to use this later) you should define your hook function as taking a single parameter which, by convention, is simply called e. For example:
function jgr_onNickChange(e) { The parameter e is simply an object representing the event that your script has been called in. It provides a property that is very useful - destObject. This returns an object representing the view or situation the event occurred in. So, if the event was a Private Message arriving, then e.destObject will be an object representing the user at the other end of the conversation. In most cases, it will be easier to use the following code at the start of your hook, rather than use the destObject item directly.
var evt = getObjectDetails(e.destObject);
The getObjectDetails function returns an object which is a little easier to use than e.destObject. However, there is one drawback The advantange of using getObjectDetails is that you can find out the current network (for example) without caring what the current view is. Say you were in a channel on a server, to get the network object from e.destObject you would need to do e.destObject.parent.parent. But if you were on the server view, it would just be e.destObject. Using evt, though, you could just use evt.network each time. The following properties are defined on evt for each view type:
Finding Out More About clientThe best way to find out how things work in ChatZilla is to use the "client" view, which evaluates it's input as JavaScript, and the dumpObject function. Just enter dumpObject (client) to get started. Some examples;
dumpObject(client.commands) (the last one only works if you're attached to the network "moznet" and are in at least one channel) You can use this for anything that is listed as [object Object], and if you want to find out about a "function" in the list, enter the same as you would for an object, but omit the dumpObject and brackets. Some examples;
client.commands.add This not only gives you the parameter list for the function, it also shows the source code (!) so you can (if you want) see how it all works. Powered by the Content Parser System, copyright 2002 - 2009 James G. Ross. |
