Install How do I use this?

 

Credits & Intro

I got the idea to do this after seeing Buzzy's update checker. There are many other script updaters out there, but his was the one that inspired me to give it a try. Thanks to all those that came before and all of their efforts.

Thanks to the following people for helping me clean up and/or improve the code (listed in alphabetical order):
IRoll11!~s, JoeSimmons, sizzlemctwizzle

Usage

To see this thing in action, check out a Demo of this Script Updater

Step 1:

To use the script this updater in your scripts, simply include the following line within your meta data block:

// @require http://userscripts.org/scripts/source/57756.user.js

Note: this scripts will only be downloaded when you install your script. Just adding the line above without re-installing your script will do nothing. For more information, read about the @require meta tag.

Step 2:

To activate the check, just call the line of code below, substituting scriptId with the ID of your script on userscripts.org

ScriptUpdater.check(scriptId)       or      ScriptUpdater.check(scriptId, currentVersion)

Using the second option above (providing the current version) will tell the user what version they have installed as in the screen shot.

Showing Version History

In order to have the upgrade notice display the latest version history of your scripts, just include the @history meta tag as follows:

// @history [version] [change made to version]

For example:

// @history	1.01 Removed requirement for current version
// @history	1.01 Cleaned up code
// @history	1.01 Simplified metadata retrieval
// @history	1.01 Updated license
// @history	1.00 Initial release

Advanced Methods

Call the following methods somewhere near the top of your script or wherever appropriate to use the script updater tools.

ScriptUpdater.check(scriptId, currentVersion, callback)

• Checks to see if no update check has been made in a while (default 6 hours) and performs a new check if necessairy. If a new version is available, a notice pops up allowing the user to easily install the update of your script. This is useful for passively checking for new versions every now and then and should be included near the top of your script.
• Parameters
  • scriptId - The userscripts.org ID of your script (e.g. http://userscripts.org/scripts/show/56817)
  • currentVersion - A string representing the current version you are publishing.
  • callback - An optional function to which the latest version will be returned. See below for more information.

ScriptUpdater.forceCheck(scriptId, currentVersion, callback)

• Checks to see if a new version is available regardless of how long it has been since the last check. If a new version is available, a notice pops up allowing the user to easily install the update of your script. This is useful as a way of letting your users manually checking for updates.
• Parameters
  • scriptId - The userscripts.org ID of your script (e.g. http://userscripts.org/scripts/show/56817)
  • currentVersion - A string representing the current version you are publishing.
  • callback - An optional function to which the latest version will be returned. See below for more information.
• Usage Example
  • var myButton = document.createElement('input');<br> myButton.type = "button";<br> myButton.value = "Check for Updates";<br> myButton.addEventListener('click', function() {<br> &nbsp; &nbsp; ScriptUpdater.forceCheck(56817, "0.011");<br> }, true);<br> document.body.appendChild(myButton);

ScriptUpdater.forceNotice(scriptId, currentVersion, callback)

• Displays a notice allowing the user to easily install the update of your script. This happens regardless of how long ago a check was made, whether or not there is actually a new version available, or if the user has already installed it. This is useful for displaying version history or allowing easy re-installation of your script.
• Parameters
  • scriptId - The userscripts.org ID of your script (e.g. http://userscripts.org/scripts/show/57377)
  • currentVersion - A string representing the current version you are publishing.
  • callback - An optional function to which the latest version will be returned. See below for more information.
• Usage Example
  • var myButton = document.createElement('input');<br> myButton.type = "button";<br> myButton.value = "Show Latest Version";<br> myButton.addEventListener('click', function() {<br> &nbsp; &nbsp; ScriptUpdater.forceNotice(56817, "0.011");<br> }, true);<br> document.body.appendChild(myButton);

Callback Function

All of the methods for ScriptUpdater can take a callback function to which the latest version on userscripts.org will be returned. If you are not familiar with the concept of callbacks, think of it this way: We first create a function that takes one argument (the version), then we feed that version to the ScriptUpdater method that we want to use.

For example:

function handleReturnedVersion(v) {
     // do something amazing here with the v variable (version)
     // you could store this somewhere or display it within your interface
}
ScriptUpdater.check(56817, "0.011", handleReturnedVersion);

In the example above, we've created our function to handle the version and given it to ScriptUpdater. When the ScriptUpdater is finished getting the version number from userscripts.org, it passes it back to the function we gave it, and everything within handleReturnedVersion happens.

Styling the Upgrade Notice

If you want to change the style of the upgrade notice in any way, it's fairly simple with the use of a little CSS. Just include the following code in your script somewhere near the top and customize it as desired.

GM_addStyle(
	"#ScriptUpdaterMask { position:absolute; width:100%; top:0; left:0; height:100%; background-color:#000; opacity:.7; z-index:9000; } \
	#ScriptUpdaterBody * { border:none; font-size:12px; color:#333; font-weight:normal; margin:0; padding:0; background:none; text-decoration:none; font-family:Helvetica Neue,Arial,Helvetica,sans-serif; } \
	#ScriptUpdaterBody { width:500px; margin:auto; margin-top:125px; text-align:left; background:#f9f9f9; border:1px outset #333; padding:0; font-family:Arial; font-size:14px; -moz-border-radius:5px; cursor:default; z-index:9010; color:#333; padding-bottom:1em ; } \
	#ScriptUpdaterBody a { margin:0 .5em; text-decoration:underline; color:#000099; font-weight:bold; } \
	#ScriptUpdaterBody strong { font-weight:bold; } \
	#ScriptUpdaterBody h1 { font-size:13px; font-weight:bold; padding:.5em; border-bottom:1px solid #333; background-color:#999; margin-bottom:.75em; } \
	#ScriptUpdaterBody h2 { font-weight:bold; margin:.5em 1em; } \
	#ScriptUpdaterBody h1 a { font-size:13px; font-weight:bold; color:#fff; text-decoration:none; cursor:help; } \
	#ScriptUpdaterBody h1 a:hover { text-decoration:underline; } \
	#ScriptUpdaterBody table { width:auto; margin:0 1em; } \
	#ScriptUpdaterBody table tr th { padding-left:2em; text-align:right; padding-right:.5em; line-height:2em; } \
	#ScriptUpdaterBody table tr td { line-height:2em; font-weight:bold; } \
	#ScriptUpdaterBody li { list-style-type:circle; } \
	#ScriptUpdaterBody p { font-size:12px; font-weight:normal; margin:1em; } \
	#ScriptUpdaterHistory { margin:0 1em 1em 1em; max-height:150px; overflow-y:auto; border:1px inset #999; padding:0 1em 1em; width:448px; } \
	#ScriptUpdaterHistory ul { margin-left:2em; } \
	#ScriptUpdaterClose { float:right; cursor:pointer; height:14px; opacity:.5; } \
	#ScriptUpdaterClose:hover { opacity:.9; } \
	#ScriptUpdaterFooter { margin:.75em 1em; } \
	#ScriptUpdaterFooter input { border:1px outset #666; padding:3px 5px 5px 20px; background:no-repeat 4px center #eee; -moz-border-radius:3px; cursor:pointer; width:70px; float:right; margin-left:.5em; } \
	#ScriptUpdaterFooter input:hover { background-color:#f9f9f9; } \
	#ScriptUpdaterFooter select { border:1px inset #666; }"
);

Version History

• Fixed mis-handling of DOM elements on XML pages

• Screen mask now fills entire document height as intended
• Notice is now centered and fixed regardless of scrolling
• Fixed minor wording error
• Fixed implementation of ScriptUpdater.forceNotce()
• Fixed implementation of callback functions

• Improved code performance based on community feedback

• Removed requirement for current version
• Cleaned up code
• Simplified metadata retrieval
• Updated license

Share

Tags

• automatic
• history
• phasma
• script
• updater
• updator
• userscripts
• userscripts.org
• version

Other Scripts by Author

• Ikariam Script Tools for Developers
• Ikariam Auto Build & Upgrade
• Ikariam Sexy Theme
• Ikariam Pillage Helper
• Growl Tools
• Ikariam Empire Overview
• Ikariam Notifier (email & more)
• Ikariam Military Cargo
• Ikariam Resource Links
• Ikariam Library Tools

and 18 more