Your First Script

Creating a new script is easy, even for a non-developer. All you have to do is go to the Scripts section in the Preferences and click on "Create New". The script's name will be used to create the new directory for the script as well as the first JScript file. Nothing else will be created as nothing else is necessary. So, start by creating a new script called "My First Script", click on "Create New", enter the name of the script and press OK. The file will be created, the new script automatically enabled and the editor window will popup with the following code:

function OnEvent_Initialize(MessengerStart)
{
}

function OnEvent_Uninitialize(MessengerExit)
{
}

Two empty functions are automatically added to every new script: OnEvent_Initialize and OnEvent_Uninitialize. These functions are event handlers known by Messenger Plus!, they are called in your script automatically when a specific event occurs. Those two are called when your script is started and when it's ended. They both have one parameter, specifying when the script was launched or stopped (you can check the documentation of these events later on for more information).

If the Script Debugging window is not visible, open it now (Plus! menu, check "Show Script Debugging". If you don't have this menu, please read Scripting Environment). Make sure the combo box in the Script Debugging window is set on "My First Script" then, in the editor window, click on "Save All" and "OK" for the confirmation message. Back in the Script Debugging window you'll notice the following entries:

Script has been stopped
Script is starting
Script is now loaded and ready
Function called: OnEvent_Initialize

Each time a script file is modified and saved, the script has to be stopped and restarted to apply the changes. Clicking on "Save All" stops the script, saves the files and displays a confirmation message. When the confirmation message is dismissed, the script is restarted, JScript files are loaded and if no major syntax error is detected, the "Script is now loaded and ready" message is displayed in the debugging window. Global variables and function calls are immediately executed during the loading procedure (your new script does not have any).

The first thing Messenger Plus! does once a script has been loaded is to call the OnEvent_Initialize function, if it exists. When an event is called, it is automatically mentioned in the debugging window. Depending on the kind of event your script is handling, it can be preferable to disable this behavior to avoid getting too many useless traces. To do so, click on the "Debug" menu of the script debugging window and uncheck "Trace Event Calls". The debugging window is the best place for developers to output diagnostic messages to keep track of what's going on in their scripts. Scripts that produce little or no diagnostic text at all are generally harder to debug, that's why you should always remember to send some kind of diagnostic information based on where you are in the script, variables that you are using, etc...

Because JScript alone wouldn't be enough to create scripts that interact well with Messenger, the Messenger Plus! Live scripting system comes with over 100 functions and properties as well as nearly 50 events, all specifically designed for your Messenger needs. Functions and properties are organized into two kinds of objects: global objects and instantiated objects.

• Global objects are available instantly from anywhere in your script. Global objects act as name spaces for functions of general interest through out the scripts. An example of such object is Debug which allows to send text to the script debugging window.
• Instantiated objects are returned by some functions of the API or passed as parameters in events. They refer to a particular instance of an object in Messenger that can exist more than once. An example of such object is ChatWnd which lets you interact with the various chat windows of Messenger.

Let's start with the this famous international example of what a good program should say to its creator when emerging from the cyber-void. Simply replace the empty OnEvent_Initialize function of your new script by this one:

function OnEvent_Initialize(MessengerStart)
{
        Debug.Trace("Hello World!");
}

Click on "Save All", dismiss the confirmation message and take a look as the debugging window. The last entry will say "Hello World!". That's because the OnEvent_Initialize function, which is called when the script starts, now calls the Trace function from the Debug object. If you look as the documentation for Trace, you'll see that it takes a single string parameter which is the text that's sent to the debugging window. You can experiment adding calls to Debug.Trace in OnEvent_Uninitialize, you'll see that they are executed when you click on "Save All", before dismissing the confirmation message (because the script has been stopped which triggered the Uninitialize event).

Of course, a script that just says hi to its developer is not very useful to anybody. Let's make it more interesting. Just copy paste the following code after the OnEvent_Uninitialize function, at the end of your script.

function OnEvent_Signin(Email)
{
  var Message = "Hello Master " + Messenger.MyName + "!";
        Message = MsgPlus.RemoveFormatCodes(Message);
        MsgPlus.DisplayToast("", Message);
}

Save the script, sign out from Messenger and sign back in. You'll see a "toast" (a popup window displayed in the corner of your screen) welcoming you personally to Messenger (if Messenger itself displayed a toast after you signed in, you may have to close it to see the one displayed by the script). To achieve this ego-boosting feature, we first needed to locate the proper event in the Events Reference. OnEvent_Initialize was not a good choice here as this event occurs as soon as the script starts, which is generally when Messenger starts and no user is signed in at that time. For that reason, OnEvent_Signin seemed to be the best choice for that feature.

Let's analyze each line of this script.

• The first line in the OnEvent_Signin function creates the message that will be displayed. A variable called "Message" is declared and is assigned a string composed of two static strings and a property: Messenger.MyName. This property returns a string equivalent to the name of the currently signed in user. The message is simply created by attaching the 3 strings to each others.
• The second line is something you'll have to remember to do when working with strings that contain contact names or personal messages. Names and personal messages can include control characters used by Messenger Plus! to display color or change various text attributes such as bold, italic, etc... For example, "[i][/i]" displays the text in italic in the contact list and in chat windows, however, these tags are not supported everywhere. That's why "Message" is sent to MsgPlus.RemoveFormatCodes: this function simply parses the string, removes eventual control characters from it and returns the result. Feel free to ignore it for now.
• The third line is the pièce de resistance, the function that actually displays the toast on screen. MsgPlus.DisplayToast can take several parameters but is used here in its simplest form. The first parameter is the title of the toast (if not specified like in this example, the default title is used) and the second parameter is the actual message to display.

Now, you may think "hey, I'm the only master on this computer, I don't want the script to welcome others in this way". You're right about that so let's change the OnEvent_Signin function to this:

function OnEvent_Signin(Email)
{
        if(Email == "your@email.com") //Change for your sign-in email
        {
          var Message = "Hello Master " + Messenger.MyName + "!";
                Message = MsgPlus.RemoveFormatCodes(Message);
                MsgPlus.DisplayToast("", Message);
        }
}

Just substitute "your@email.com" with your actual sign-in email (in lower case), sign out and sign back in. You'll get the message again however, if somebody else signs-in, the toast won't be displayed as the Email == "your@email.com" condition will be false. This last example demonstrates the user of the parameters sometimes sent along with events. Here, the "Email" parameter is obviously the Email of the user who just signed in, you can use it to adapt the script accordingly.

Your first script is now complete. It is important that you really understand what's been explained in this document before continuing further in the documentation. You should spend some time modifying your first script, try to experiment with some new events, new functions, new parameters, they are all listed in the Reference sections of this documentation.

See Also

Objects Reference, Events Reference.