greasemonkey options panel with jquery

Hi, this tutorial is also based on the mouse hunt script "facebook mousehunt improvements" created by me, and in this one i will explain how to create an options panel (only check boxes at this time) and save it.

Here is my final result with this script :

If you want to try this, remember to load jquery correctly as described in this post at number #4.

First of all, the data is saved in a cookie as JSON, i have an object where i save all my data and i save that object as JSON on a cookie. Because javascript does not know to convert an object to a json string i used a class which does that, the class is not created by me, I just use it as it is, here is the fie : json
I copied the content of the file inside my script so i don't have to load it remotely, anyway it's just a line , so you should also copy this at the beginning of your greasemonkey script.

As i said the data is saved as cookie, here is the functions which will create, and read a cookie :

function createCookie(name,value,days) {
	if (days) {
		var date = new Date();
		date.setTime(date.getTime()+(days*24*60*60*1000));
		var expires = "; expires="+date.toGMTString();
	}
	else var expires = "";
	document.cookie = name+"="+value+expires+"; path=/";
}
 
function readCookie(name) {
	var nameEQ = name + "=";
	var ca = document.cookie.split(';');
	for(var i=0;i < ca.length;i++) {
		var c = ca[i];
		while (c.charAt(0)==' ') c = c.substring(1,c.length);
		if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length,c.length);
	}
	return null;
}

Also in my program i read the cookie when the script starts so the data object "myData" in my case will be populated and available in the entire script :

var myData = new Object();
try {
	if(readCookie("gm_pl_data")!=null)
	{
		myData = JSON.parse(readCookie("gm_pl_data"));
	}
	else
	{
		//if there is no cookie we initialize it
		initCookie();
	}
}catch (err)
{
	initCookie();
}

In my case gm_pl_data is the name of the cookie in which i save the data. Here is the initCookie() function, this will just initialize the objects inside the myData object :

function initCookie ()
{
	myData = new Object();
	myData.allLogs = new Object();
	myData.allChese = new Object();
 
	savePersistentData();
}
 
//will be valid 1000000 days
function savePersistentData ()
{
	createCookie("gm_pl_data",JSON.stringify(myData),1000000);
}

I let in there all my init objects so io can see how to initialize them if you have more. You can also notice the savePersistentData function which will update the cookie and save the persistent data .

Until here we only had generic information about how data is saved and the functions which save the data. Now I'll go in more details for the actual options panel. The panel is actually a div in which you can enter any thing you want, but the values of the check boxes will be saved  and their status restored when the page reloads.

So here is how my panel looks like :

jQuery("#gm_pl_options_container").append("Show the timer
<input id="gm_pl_check_show_timer" type="checkbox" />
");
	jQuery("#gm_pl_options_container").append("Automaticaly sound the horn
<input id="gm_pl_check_sound_horn" type="checkbox" />
");
	jQuery("#gm_pl_options_container").append("<strong>Kings rewared options</strong>
");
	jQuery("#gm_pl_options_container").append("Play youtube on kings reward
<input id="gm_pl_play_sound_on_reward" type="checkbox" />
");
	jQuery("#gm_pl_options_container").append("Play midi on kings reward
<input id="gm_pl_play_sound_midi_on_reward" type="checkbox" />
");
	jQuery("#gm_pl_options_container").append("Show alert on kings rewared
<input id="gm_pl_show_alert_on_reward" type="checkbox" />
");
 
	setOptions();
 
jQuery("#gm_pl_options_container input").click(function () {saveOptions()});

in this case the id of the div inside which i enter the options is "gm_pl_options_container", and i you can see that setOptions() is called, this will set the default options for the check boxes based on the myData object, here's the code :

function setOptions ()
{
	if(typeof myData["options"] == "object")
	{
		for(i in myData["options"])
		{
			jQuery("#"+i).attr("checked",myData["options"][i]);
		}
	}
}

In my case the options are saved in myData["options"] the myData object is the main script object and all the scripts data is saved there, not just the options.

And after the setOptions function is called we also have an intresting line, this will add an onclick function to each input on that div, and in this function we call saveOptions(), this function will get all the inputs in that div, and save the values in myData['options'] object, and also write the cookie to make sure that the values are not lost on page refresh :

function saveOptions ()
{
	if(!(typeof myData["options"] == "object"))
	{
		myData["options"] = new Object();
	}
	jQuery.each(jQuery("#gm_pl_options_container input"),function () {
		if(this.checked == true)
		{
			myData["options"][this.id] = true;
		}
		else
		{
			myData["options"][this.id] = false;
		}
	});
	savePersistentData();
}

Every thing you have to do now is use those options, there are 2 ways to do this, you can check the status of the check box or you can get the value from the myData['options'] object, they are the same, i use the object :

if(myData["options"]['gm_pl_show_alert_on_reward'] == true)
		{
			alert("You have a king's reward!");
		}

And this is it, if you have any questions let me know, and remember, if you use mouse hunt don't forget to use my script : Facebook mousehunt improvements

Related posts:

1. GreaseMonkey, Jquery and the greatest mouse hunt script.
2. Autoupdate on greasemonkey script, example from “mousehunt improvements” script.
3. jQuery popups wizard, web 2.0 ideea and usability

The idea behind this is, that the user will install the script and most probably will never go back and check if there is an update to that script, so you, the developer, will have to fix this problem for the user. I didn't wanted to automatically install software or updates on a users PC so i'm notifying the user that there is an update available, so he can install it by hand (only click on the link).

There are 2 parts for this, the Javascript part (inside the greasemokney script) and the server part (php in my case). The principle is simple, we have a variable inside the gresemonkey script which will contain the version of that script :

var cVersion = "1.14b";

and we have a function which will call an url giving that version as a parameter :

//check if a new version is availble.
	GM_xmlhttpRequest({
method: 'GET',
url: 'http://path.to.your.script.php?version='+cVersion,
headers: {
'User-agent': 'Mozilla/4.0 (compatible) Greasemonkey',
'Accept': 'application/atom+xml,application/xml,text/xml',
},
onload: function(responseDetails) {
$("#gm_pl_version_container").html(responseDetails.responseText);
}
});
 

What this function does is pretty straight forward, will call an url (passing the script's version as a parameter) and put all the returning content (presumed html) inside a div.

Now, we have the server script, which we called earlier. This script also has a variable inside :

$local_version = "1.14b";

which contains the latest version of the script. This script is also pretty straight forward, will compare the latest version of the script, defined here, with the version provided as a parameter, and based on that will return an html, here is the entire script :

 
<?php
$local_version = "1.14b";
if($_GET['version']!= $local_version)
{
	print "
<div style='padding:3px'>
	A new version of this script is available.<br>
	Click <a href='http://userscripts.org/scripts/source/57446.user.js'>here to upgrade</a>
	</div>
 
	";
}
else
{
	print "your script is up to date ($local_version)";
}
?>
 

And this is it.
If you don't want to use Jquery, no problem you will have to replace this :

 $("#gm_pl_version_container").html(responseDetails.responseText);

with :

document.getElementById("gm_pl_version_container").innerHTML(responseDetails.responseText);

where gm_pl_version_container is the id of the element where you want to insert the content.

Related posts:

1. GreaseMonkey, Jquery and the greatest mouse hunt script.
2. Greasemonkey, create a options panel using jQuery
3. jQuery popups wizard, web 2.0 ideea and usability

I started working on ma spare time in this... was not easy because some things ware hard to test... bunt eventually i did it.

You can see the script here : http://userscripts.org/scripts/show/57446 the script has been around for about a month and already has 1200 installs and going up, and it's becoming "the mouse hunt script" .

Now i will explain some of the problems i encountered on creating the script.

1. Saving persistent data, grease monkey does not have a very good way for this, so i decided to create an object where i save all the data and then save the object as JSON in a cookie

2. Updates, i was thinking that it would be nice to notify users when an update is available, so i did this by creating a .php file in a server and store there the latest version number, the script checks that version with it's current version and if is different will show a message

3. Passing parameters on a function attached to an event, this was the most tricky one... was pretty complicated... here is the solution :

$.each($(".huntername"), function (i,o) {
 
			var id = 0;
			var childs = $(o).children("a");
			var link = $(childs[0]).attr("href");
			var name = $(childs[0]).html();
 
			id = link.substr(link.indexOf("=")+1);
 
			$(o).html($(o).html()+"<a id="gmpl_af_&quot;+i+&quot;" onclick="return false" href="#">(add to links)</a>");
			_e("gmpl_af_"+i+"").addEventListener("click",function () {gmpl_addFriend(id,name)},false);
		});

4. How to use jquery in a grese monkey script, actually for this i fond the solution somewhere on the internet... : http://joanpiedra.com/jquery/greasemonkey/

// Add jQuery
    var GM_JQ = document.createElement('script');
    GM_JQ.src = 'http://jquery.com/src/jquery-latest.js';
    GM_JQ.type = 'text/javascript';
    document.getElementsByTagName('head')[0].appendChild(GM_JQ);
 
// Check if jQuery's loaded
    function GM_wait() {
        if(typeof unsafeWindow.jQuery == 'undefined') { window.setTimeout(GM_wait,100); }
    else { $ = unsafeWindow.jQuery; letsJQuery(); }
    }
    GM_wait();
 
// All your GM code must be inside this function
    function letsJQuery() {
        alert($); // check if the dollar (jquery) function works
    }

And all your code should go where the alert($) is. Only if you have some functions you should put them outside that function.

Related posts:

1. Autoupdate on greasemonkey script, example from “mousehunt improvements” script.
2. Greasemonkey, create a options panel using jQuery
3. jQuery popups wizard, web 2.0 ideea and usability