User:Gaz Lloyd/chatnotifications

From the RuneScape Wiki, the wiki for all things RuneScape
Jump to: navigation, search

Gaz Lloyd
Talk
Level 99 Skills For Awesome People only
Calculator Guide Other Guides
More Links
Other Stuff: Header Name
Settings stuff: Common.css Common.js
Talk Page Archives: One Two Three Four Five Six Seven Eight Nine Ten
Not Subpages: All Subpages My Contributions My Editcount My Signature RfA Hiscores Ironman Hiscores Adventurer's Log Ironman Adventurer's Log


This is a guide to install Growl for Windows and Growl notifications for [[Special:Chat]].

In theory this should work for the original OSX version of Growl, but I cannot test. Unfortunately there doesn't appear to be a Linux port of Growl.

This script can work for IE, but not without edit. If you wish to use this script with IE, let me know and I can provide the changes.

About[edit | edit source]

Are you a person that frequents S:C but then forgets that you opened the tab? Are you frustrated because you aren't pinged when someone says your name, like and IRC client does? Would you just like a pony?

For the latter, see here. For the rest, read on!

Growl is a notification API for OSX and Windows. It sends fully customisable notifications in response to certain events, which you control.

Here's some examples:

Growl can hook in to many things, some of which I will mention later.

Step 1: Installing and Setting Up Growl[edit | edit source]

Installation is simple. Head over to Growl for Windows, click that big download link and follow the installation instructions from there.

Once installed, open the client (if it hasn't been already), and you can mess around with the settings as you like. The Displays tab is where you can set the look of the notifications (and install more). The Applications tab is where you can tune the settings for each of your registered applications - even the individual notifications of each application, if it has multiple registered.

There's only two changes to make for the purpose of this guide, however, and that's to make sure the Allow network notifications and Allow notifications from websites checkboxes are ticked in the Security tab. (There's no OK/Apply button, so once ticked you can close the client.)

Step 2: Test 1[edit | edit source]

As the first test, head over to Growl for Windows' Javascript test, and click the register button, followed by the notify button. If a notification pops up, success! Your Growl is configured correctly and you should be able to continue to the next step. [If you click notify w/ callback, you'll get another notification - but unlike the normal notification, if you click this one, the source window (and tab) will be focused and a message will pop up. This is a callback function, which can be used in the S:C script if you so wish.]

Didn't work? There's a few possible reasons:

  • You don't have Growl installed
  • Growl isn't running
  • The checkboxes in the Security tab are unchecked
  • Your browser has javascript disabled (or you have an extension which does so)
  • Your browser is blocking flash (or an extension is), or you are missing a flash plugin for your browser (get it here)

Check each of these, then run the test again. When it works, proceed to the next step. If you're having trouble, let me know.

Step 3: Installing the Chat Script[edit | edit source]

This bit's fairly easy. Head over to my chat.js, copy the contents, paste it into Special:MyPage/chat.js, save and force-refresh your browser (by following the instructions at the top of the page).

Now, you have two choices. You can test it right by going to step 4, or you can do some basic customisations first by going step 5 first.

Step 4: Test 2[edit | edit source]

To test right now, head over to [[w:c:runescape:Special:Chat|S:C on the RuneScape Wiki]]. You may need to force-refresh again. You should be able to test by saying gaz test or similar - anything including the words gaz, lloyd, gaz_lloyd, overlloyd - you should get a notification <yourname> pinged you! <whatyousaid>.

Similarly, if you open a private chat with someone - make sure they're ok with it - saying anything at all should notify you with <yourname> PMed you! <whatyousaid>. This should also apply to anything they say.

If you don't get notified, check the points in step 3. In addition, this version includes a lot of log messages, so you can track what the script is doing via the javascript console - see here for how do that in various browsers.

If you have an issues, or any errors you don't recognise, please let me know.

Step 5: Basic Customisation[edit | edit source]

There are many things to customise, both on a basic cosmetic level and on an advanced, add-more-functionality level. We'll start with basic, and cover advanced as part of the how it works section later.

There's a few basic customisations that can and should be applied.

Required[edit | edit source]

Your name

This is to prevent notifications appearing in private chat when you talk.

Find the line

var self = "Gaz Lloyd";  //my own name, to ignore when i type in pm

and change Gaz Lloyd to your username. Include spaces, not underscores.

Currently, this only ignores your own messages when chatting in private chat - I intentionally do not ignore pinging myself in public for testing purposes. If you want to ignore that as well, let me know (or add it yourself if you know javascript).

The chat room

This is the identifier of the chat room, and is what separates it from private chat. The script will automatically attempt to find the chatroom ID when it loads, but, if it fails, it falls back to a default. You need to set up the phrase that it uses to detect entering a chat room to whatever it is for your wiki, and the default ID to fall back to.

Find the lines

var chatentry = /^\s+Welcome to the RuneScape Wiki chat$/m;
var defaultchatid = "#Chat_21";

First stop is to check the entry message: enter chat and see what it says. For example, the RuneScape Wiki's is Welcome to the RuneScape Wiki chat. You can find this at [[MediaWiki:Chat-welcome-message]] on your wiki (where $1 is the name of the wiki), but it is much easier to just join chat and see what it is. You should be able to copy that and paste it in place of Welcome to the RuneScape Wiki chat above, leaving the symbols around it (you may or may not need the \s+).

Next, you need to find the chat ID for your wiki. The following instructions are for chrome, but are similar for other browsers with a developer console. Let me know if you need help.

  1. Open Special:Chat for the wiki
  2. Right-click a message and select Inspect element
  3. Scroll up to find the first <div> element containing what you clicked - you'll probably go up past many <li> elements and one <ul>
  4. In this <div> element, you'll see it has an id - this is what you are looking for. It should be like Chat_###.

Now, in your script, change "#Chat_21" to the ID you found, prepending it with #. Do not forget the #!

You do not need to keep this up to date, but it is worth checking it periodically to see if it has changed. You should set the default at whatever your wiki's chat is on most of the time.

Your pings

The words that cause a ping notification to occur. This is something you definitely should change, though won't break the script if you do not (you'll just get notifications when someone says 'gaz' instead of your own name).

Find the line

var pingon = /\b(gaz+|gaz_lloyd|lloyd|gareth|overlloyd)\b/i;  //ping keywords as regex

The right side of the equals sign is a list of words separated by a pipe which you will be pinged on. Make sure to not to delete /\b( or )\b/i;.

If you understand regular expressions, then you should have no issues setting this up. If you do not, or otherwise need help, please let me know.

Optional[edit | edit source]

The icon

The icon that appears in the notification. By default this is a cut-down version of the RuneScape Wiki Wordmark, made to look like the Favicon.

To change this, find the line

var rswimg = 'https://dl.dropboxusercontent.com/u/45182859/New%20folder/Wiki-wordmark.png';

and change the URL to the URL of the icon you want - make sure it is the direct link to the image if using a hosting site.

The icon is automatically squished down to a square if it is not, so it is a wise idea to make it a square to avoid weirdness.

Chat hilite

This is the hilite applied to the message of someone pinging you.

By default, when pinged, the message has the class gaz_hilite applied to it - you can change that in the script if you like. I just made sure it was something unique. To change what the hilite is, you'll need to add some CSS to any of Special:MyPage/wikia.css, Special:MyPage/common.css or Special:MyPage/chat.css. I went for the last.

Add

.gaz_hilite {
    color: red;
    font-weight: bold;
}

and save. Replace .gaz_hilite with whatever class you changed it to in your script, prepending with .. Do not forget the .!

Change the styles of the class as you like; default is red and bolded.

Callback

If you left-click the Growl notification, this fires the callback function which brings the chat tab to the foreground (and opens the relevant chat/PM tab). (Right-clicking closes the notification without firing the function.)

In Chrome, the normal function for changing focus is not properly supported (using it fires no error, it just does nothing). For this purpose, the workaround is to use the alert function, which pops up a box in front of the window you need to close manually. Unfortunately, I don't think there's a better way to bring the window into focus right now. However, if you are not using Chrome, you can change the line

    alert('ponies'); //because chrome pls

to

    window.focus(); //won't work in chrome

This should work in all other browsers, including IE! If it fails, let me know and I can help you out.

If you do not want the callback functionality, you need to delete 6 lines: In the notify() function

    notification.callback.context = "ping";
    notification.callback.type = "ping";

In the notifyPM() function

    notification.callback.context = user;
    notification.callback.type = "pm";

In the notifyTimeout() function

    notification.callback.context = "timeout";
    notification.callback.type = "timeout";

Each of those decouples the callback functionality from the type of notification.

Test[edit | edit source]

Make sure to test your changes!

Step 6: Done![edit | edit source]

And that's it! You should now have a working notification system for your chat.


Appendix A: Rest of my chat.js[edit | edit source]

For completeness, a short walkthrough of the other things in my chat.js, and how to implement them for yourself.

Add link to header[edit | edit source]

The simplest change, adds a link to my chat.js to the header. Just change the username to your own.

Force chat reload[edit | edit source]

This part forces the page to reload when there have been no messages for a period of time. This is an automatic, if crude, way of detecting if chat crashes and responding to it.

The main drawback is if chat is quiet, you may be forced to reload when there are no messages. Luckily people joining/quitting/etc also counts as a message, to reduce that, but it is still a risk in quieter chats. The only problem with reloading is you lose your scrollback and any PMs, but there is no other way of reconnecting to chat, so you lose them anyway when chat crashes.

There is little to change if you just copy the section over.

timeout
var timeout = 5*60*1000;//interval to force reload page on, in ms (5 mins)

How long the script waits before assuming you timed out, forcing a reload. Change the value to whatever, in milliseconds. I suggest doing as I did above, leaving multiplications in (i.e. using 5*60*1000 instead of 300000 for 5 minutes) for clarity. Too short will result in constant reloading, not a good thing.

interval
var interval = 10*1000;//interval to check if it has timed out, in ms (10 seconds)

How often the script checks if you have timed out, in milliseconds. You want to set this fairly low, but not so much to cause lag or overchecking. I settled on 10 seconds.

Growl usage
      notifyTimeout();

I added a Growl function further up in the script, and had it notify me when I timed out. If you didn't install growl, delete this line. You can also optionally change

      setTimeout(function(){window.location.reload(true)},3000);

to

      window.location.reload(true);

if you have no Growl.

How it works

Fairly simple really. Every time a new message arrives (via onNewMessage, see below), the time is saved to a variable. Every interval, this time is checked against the current time, and if the difference is more than timeout, the page is reloaded (and notification fired).

Add time to inline-alerts[edit | edit source]

By default, the time is not added to inline alerts (joins, quits, welcome, etc). This is 'fixed' by this section.

This should work out of the box and has no customisation needed, unless you have not added the Growl script (there is another way of doing it, so let me know if you want this and not Growl), or you messed around with the chat's CSS (in which case you may need help, if you just borrowed it from someone else without knowing CSS yourself).

How it works

When a new message arrives (again, using onNewMessage) it checks if it has the inline-alert class. If it does, it adds the time (using the same format the normal chat messages have).

An additional thing is adding the time to the welcome message - which doesn't trigger onNewMessage. This is done in the following

$(document).ready()

block. The same formatted time is added.

Appendix B: Other Growl Applications[edit | edit source]

Now that you have Growl installed, why not hook in additional applications?

IRC

IRC is an obvious choice, as another chat system. While I don't know much about mIRC, there appears to be a Growl plugin for it.

I use Hexchat, which has a Growl plugin, and I remember installing it being awkward. Let me know if you need help with it.

There's also a plugin for irssi.

Others

The Growl for Windows website has a nice long list of supported apps and bridges. Various examples:

  • Media: iTunes, Windows Media Player/Center, Winamp, Last.fm, Pandora, etc
  • Social: RSS, Gmail, Twitter, Outlook, Pidgin, Skype, etc
  • Others: µTorrent, Android, iOS, Firefox, etc

Another good way to find things is to google 'applications growl' and see what pops up.

Appendix C: How it Works and Advanced Customisation[edit | edit source]

Part one: Javascript-Growl bridge[edit | edit source]

Javascript cannot directly interact with outside applications. This is why, in the early part of the script, a flash element is embedded into the page.

Javascript and flash also do not interact if one is on HTTP and the other is HTTPS, which is why the top of the file has both versions in comments.

Anyway, the script runs as follows:

  1. When the document is ready, init runs
    1. Init sets up a config object and initialises Growl
    2. This sets the config in the Growl object, and embeds the flash
    3. When done, onready is run after a delay (so that the flash file is actually embedded when it runs)
    4. This calls in the flash element and sets it up for use.
    5. It then runs onready2, an optional function to be run if needed. By default, this is not used
  2. Next, after a delay, it runs register
    1. Register sets up the application and notification types (as seen in Growl client->Applications), and registers them to the Growl client
    2. The registration is run via the flash file, which interacts with the Growl client on behalf of the Javascript, since Javascript cannot directly interact with it
    3. The client is now ready to notify
  3. When notify or notifyPM is called, it creates the notification object, then passes it to the flash bridge which makes the notification appear

Its fairly easy to see how the various javascript definitions relate to what is visible in the client and in a notification. If you wish to see the inner workings of the flash file, use a decompiler such as JPEXS.

The chat notification trigger[edit | edit source]

This bit is thanks to functionality added by [[MediaWiki:Chat.js/newmessage.js]].

The onNewMessage array is a list of functions that fire when a new message is received. We add a function to it, with a timeout to make sure it applies after the element is added to the page (and not before).

The function added follows these steps:

  1. First, we check that the message is actually part of the page - the onNewMessage functions are also fired when a message is removed from the page (when the message scrollback is too large, earlier messages are removed), and then they are not within the public chat and so are treated as private [per later steps]. By making sure it is on the page, we prevent notifying when removed from the page.
  2. Next, we check if the message is an inline alert (a join/quit/kick message or similar). If it is, we ignore it.
  3. Next, we make sure it has a user and a message attached, both required components.
  4. Next we check if the element for the message is within the div for the chat, using the previously defined id
    • If the element is within the public chat
      1. We apply the previously defined regex search to check if it contains a ping
      2. If it does, we apply the hilite class, log the ping and trigger the notification
    • If the element is not within the public chat
      1. It must be private, so we check if the user speaking is us
      2. If it is not, we log the PM and trigger the PM notification

As you can see, its very easy to extend by adding more things.