NOTE: Upgrading your sidekick before WM3 is released is suggested, but most users will not be able to communicate with your sidekick until WM3 is released, unless you also leave in the sendMessage call (as documented below).
This document details how to get a WM 2 sidekick primed for the WM3 sidekick handler. At any time you need a quick view of what I am talking about, feel free to view the updated tutorial script located at http://userscripts.org/scripts/review/106535.
WM Common Library
Changes have been made to the wmLibrary script (123889 on userscripts.org) which substantially upgrade the Sidekick object.
- Sidekick.receiveMessage(): This function handles a message from either a deeper iframe, or from the WM host script. When activated, a message from the host tells the sidekick which post the sidekick is processing. Alternately, when activated by a deeper iframe, and given that the host has made communication, the function passes information back to the host by joining its post id with the status received from the deeper iframe. This is a substantial upgrade over communication via the hacky and visible location.hash parameter.
- Sidekick.listen(): Activates a persistent listener on the current window which intercepts messages from the host script or from a deeper iframe.
- Sidekick.unlisten(): Deactivates the listener. This should be run onBeforeUnload of the page containing the listener.
- Sidekick.sendStatus(): Similar to the old sendMessage() function, but instead of using the location.hash parameter, this function sends a message to the host script via local storage listeners. This allows the message to be sent to the host from ANY window/iframe no matter which domain that object is running on. This was the key to Chrome support.
- Sidekick.openChannel(): This function is run when docking to the host on the host script's page. This listener actively waits for data from the calling sidekick and then reports it to the host.
Implement the Changes
There are really very very few changes a sidekick developer needs to make to fit in with the WM3 sidekick handler. For specific implementation, see the sidekick tutorial script: http://userscripts.org/scripts/review/106535
- Call Sidekick.openChannel() when you call Sidekick.dock(). Do not call Sidekick.openChannel() on repeat attempts at docking.
- Call Sidekick.listen() as soon as your script activates, but only if window==window.top, and not on the docking page.
- Call Sidekick.unlisten() using a listener on the "onBeforeUnload" event. This is not required, but its simple and clean and should be used. Implement it directly below the Sidekick.listen() call; location stipulations are the same.
- Replace the sendMessage(s) call with Sidekick.sendStatus(status,link). Change its parameters from a string like "status=3&link=string" to two parameters: an integer status and an optional string link. Passing a string as a status may cause the host script to fail, so check your code.
- Most importantly, you must include a new flag "postMessageCompatible:true" in your flags object. This flag tells WM3 that you will be using the postMessage variant of communication, EXCLUSIVELY. If postMessage communication somehow fails, WM3 will NOT revert to the old method for your sidekick if you use this flag. If you fail to provide this flag and intend to communicate via the Sidekick.sendStatus() function, every post will timeout.
- Optionally, you may choose to support those who do not upgrade to WM3 by running both Sidekick.sendStatus() and the old sendMessage() simultaneously. Without the sendMessage() call, WM2 users will get no status and every attempt will timeout. With the sendMessage() call, Chrome users may suffer memory leaks due to uncaptured errors. The choice is yours. Again, simply using sendMessage() with a "postMessageCompatible" flagged sidekick DOES NOT grant old style communication with WM3 if postMessage fails.
Because WM3 is not completely finished, this document may soon include many more features or clarifications.