Thumb

GM_ScriptUpdater

By IzzySoft — Last update Nov 13, 2009 — Installed 3,306 times. Daily Installs: 28, 12, 49, 37, 20, 30, 20, 22, 25, 30, 23, 24, 19, 33, 23, 34, 31, 25, 30, 65, 103, 56, 83, 46, 75, 68, 54, 36, 51, 17, 60, 71
Script Summary:
GreaseMonkey Script Updater - informs user of updates for your script and installs it on demand. Multi-language, capable of showing change history, and more.
Version: 1.1.5
Copyright: IzzySoft
License: Creative Commons Attribution-Noncommercial 3.0 United States License
Recently Updated TopicsPosts
You might get a laugh out o...3
Bandwidth Consumption7

this script has 2 topics, 10 posts

Review Summary
5 stars
 0 reviews (0)
4 stars
 1 reviews (1)
3 stars
 0 reviews (0)
2 stars
 0 reviews (0)
1 star
 0 reviews (0)

this script has 1 review

Thumb Thumb Thumb Thumb Thumb

Description

The GreaseMonkey Script Updater (GMSU) is targeted at script developers - as one more "library" to provide update functionality for your user scripts. "Why another one?", you may ask - and right you are...

Most scripts I found here (see also the guide on USO updater scripts) are intended to be copy'n'pasted into your own scripts. Personally, I don't like this way: It makes my scripts less clear, and every time there are updates to the updater code, I had to make a new version of my script, too, to profit from the fixes. Furthermore, these updaters only care for the main script - and don't check the dependencies. So my intention was an updater script to be bound by @require.

One more issue was the required duplication of meta data: If you've got the same information (here: Script ID and version) at multiple places in your script, you tend to forget to update one of them. So I wanted the updater to find this information automatically.

Both targets are hopefully achieved with the GreaseMonkey Script Updater:

  • The script must not be copy'n'pasted into the main script, but appended via the @require statement
  • Version information must not be duplicated - instead we turn the scripts metadata block into a kind of "HERE document" which the updater parses
  • Since this way the updater can also look for @require dependencies, it can check them as well - provided they also turned their metadata into the mentioned HERE document

Quick start for the impatient

To save you from reading it in full length (for now), here's a quick start of what you have to do to utilize GMSU in your script. You only need to put a simple wrapper around your MetaData block, set the @require line, and add a call to the init function:

var GMSU_meta_12345 = <><![CDATA[
// ==UserScript==
...
// @version        1.0.3
// @require        http://userscripts.org/scripts/source/51513.user.js
// ==/UserScript==
]]></>;
GMSU.init(12345);

Make sure to replace "12345" with your scripts ID (the number the URL of your scripts page on USO ends with), and keep the @version tag in the MetaData block up to date. Nothing more to do - now the script is checking for updates at an interval of 7 days. You can configure more (just read on), but the minimum required is done by this.

Features

Update check for the script including it via @require
Well, that's what you may have expected already - all those updaters do.
Update check for other scripts included via @require (if they support it)
Right, that's an outstanding feature of this script: If an update for the main script is found (or if dependency check was enforced), it will also check dependencies!
Chosing actions depending on the results of the update check
When update(s) are available, the script will offer a set of suitable actions:
  • View the change log (if available)
  • Update
  • Visit script homepage
  • Do nothing (close the notifier)
The change log (aka history), if available, will be displayed (on demand - by clicking the corresponding link) inside the notifier layer. The other 3 options will (also) close it.
Scheduled update checks (configurable), and manually checks (on demand)
The API offers calls for both types - it's up to you to use them. On a "forced check" (the manual one), an alert will be generated to inform the user when no updates are available - otherwise it will be handled as described before.
New dependencies
GMSU also detects if new dependencies have been added to the main script. The user will be informed about this fact.
Multi-Language
As shipped, supported languages are English, German, French, and Dutch. You can easily add more/other translations via the GMSU.setTranslations() method (see below). If you send them to the developer, they may be included in future versions - or made available in some other way.

Usage

As already mentioned in the description, the code is "included" into your script using the @require statement - and the metadata needs to be turned into some HERE document. To ease the explanation, I will use an example:

var GMSU_meta_50318 = <><![CDATA[
// ==UserScript==
// @name           ImmonetFilter
// @namespace      http://projects.izzysoft.de/
// @description    Filter out unwanted objects on ImmoNet.DE
// @version        1.0.3
// @include        http://*.immonet.de/*
// @require        http://userscripts.org/scripts/source/49700.user.js
// @require        http://userscripts.org/scripts/source/50018.user.js
// @require        http://userscripts.org/scripts/source/51513.user.js
// @uso:script     50318
// @history        1.0.3 config screen now uses tabs to make things more clear
// @history        1.0.2 keeping track of the IDs configured to allow purging objects no longer available
// ==/UserScript==
]]></>;

This is how it could look like - and now I will explain the code:

  • The first line introduces the HERE document and, together with the last line, stores the complete block into the variable GMSU_meta_50318 - where "50318" is the script ID for GMSU to identify the variable
  • lines 2 to 9 and 12 are not to be explained here - it's the usual user script metadata as described in the wiki
  • line 10 includes GMSU
  • line 11 is optional (the wiki also describes it) and again gives the ID of your script
  • lines 12+13 (optionally) describe the changes made to the script - one line per version; the version must not include any white space, and must be separated from the description by a "blank" (space). Furthermore, you should keep this list ordered (best is descending). This information will, on available updates, be used by the notifier window to display a list of changes.

From the so defined variable, GMSU can derive all necessary information to check for updates - provided you change the version number on updates, which you probably do :-) Now all that's needed to regularly check for updates, is to tell GMSU to do so: GMSU.init(50318); - that's it!

Extended usage - Describing useful API functions

Above paragraph just describes the basic usage - i.e. what is really necessary to utilize GMSU. But there are some more things it provides - so here I want to describe some useful API functions:

void GMSU.init(int scriptID, optional boolean force, optional boolean depForce)
Initializes the script and makes it checking for updates in the defined interval (default: all 7 days) only. If you specify TRUE as second parameter, it ignores the interval and straight goes to the update check, no matter what. TRUE for the third parameter means to check the dependencies even if the main script was not updated.
void setCheckInterval(int days)
Defines the interval for the update check. If you never ran this, the default is 7 days.
void setDepForce(boolean force)
Whether to enforce dependency update checks even if the main script is up to date.
void GMSU.setLang(string lang)
Set the language for the user interface. lang must be the 2-char code for the language to be used. Right now, available languages include only 'de' (German), 'en' (English), 'nl' (Dutch), and 'fr' (French). If you want your language to be supported, simply copy the translation section from the script, make your version, and send it to me for inclusion. Until it's included then, you may use the following method to make it available immediately:
void GMSU.setTranslations(string lang, object trans)
Add a new language with translations (if lang was not available before), or update/add translations for lang. lang must be a 2-char language code like 'en' (English) or 'de" (German), while trans is an object like {'term1': 'translation for term1', 'term2': 'translation for term2'}

All other methods are intended for internal use only. If you have problems and want to see some debug code in the error console, you might switch debugging on with GMSU.debugMode = 1.

How it works

Just a basic description for that:

  1. Check whether an update is due (or was FORCED) - exit otherwise. Minimize overhead ;)
  2. Parse the metadata of the script specified by scriptID - which should be found in the variable GMSU_meta_{scriptID}. Results are stored into a variable (object).
  3. Parse the metadata stored for the given scriptID on USO.
  4. Compare the version property of the local and the USO metadata. If they are not identical (or user forced a dependency update check): Go on with the next step. Otherwise simply exit (on regular check), or tell the user there are no updates (on forced check). Again we try to minimize overhead.
  5. Still here? This means the main script was updated - or a dependency update check was forced. So we need to check dependencies: Get the @require dependencies and try to figure out their scriptIDs. This should work as long they are stored on USO.
  6. Try to obtain the dependencies local metadata (only works if they are also kept in the above described HERE document structure). If this failes, just increase the failed counter and continue with the next dependency.
  7. Verify update information for the dependencies, as described above.
  8. Last step: Offer the user actions to take:
    • Update the main script directly
    • Visit the script page on USO to check for update information.
    • Nothing

ToDo

If you feel there's something missing on this ToDo list, feel free to start a discussion on it.

  • find a way to check dependencies which do not provide GMSU_meta_* information
  • Probably more details on which dependencies failed (if any - only possible if we have a solution to the previous problem)

Scripts known to use/support GMSU

This list may be incomplete, and probably will not be regularly updated. If your script is missing here, please let me know to add it.

History of Changes

  • 1.1.5 (2009-11-13) - reload GUI on language change (i.e. immediately apply the change visibly)
  • 1.1.4 (2009-11-12) - offer user to chose the language
  • 1.1.3 (2009-11-11) - reworked notify window (straighter DOM usage) and implemented history view (main script only for now)
  • 1.1.2 (2009-11-10) - some code cleanup
  • 1.1.1 (2009-11-09) - added drop-down to select update check interval, and made the links some nicer buttons (button design admittedly taken from some other script)
  • 1.1.0 (2009-07-27) - BUGFIX: If only main script was updated (but no dependency), GMSU wrongly reported "No updates available"
  • 1.0.9 (2009-07-20) - Added French translations (tnx to full interest)
  • 1.0.8 (2009-07-09) - Fix: a self-defined function was used but not included (did not notice this before since it always was defined in the master scripts)
  • 1.0.7 (2009-07-01) - Fix: on forced check, GMSU always reported at least one update even if everything was up to date
  • 1.0.6 (2009-06-26) - Some minor fixes
  • 1.0.5 (2009-06-26) - Added possibility to force dependency check (even if the main script is up-to-date). Details about updated dependencies (name, old version, current version) are displayed.
  • 1.0.4 (2009-06-25) - Added Dutch localization (tnx to utimer)
  • 1.0.3 (2009-06-24) - Now also checks for newly added dependencies
  • 1.0.2 (2009-06-18) - Added possibility to easy setup translations
  • 1.0.1 (2009-06-17) - MultiLang user messages added (en+de). Debug log switched off by default now.
  • 1.0.0 (2009-06-17) - No more popup-open-warnings, no multiple popups. This version now should be really usable without too many nags. Though, if you find any: Please report. Positive feedback is welcome as well.
  • 0.5 (2009-06-15) - Dependency check is now run against the USO metadata (to make sure to satisfy the dependencies of the script to install, not the local versions)
  • 0.4 (2009-06-15) - Fix: Some more dependency issues. Script should be usable now.
  • 0.3 (2009-06-15) - Fix: Dependency check when no metadata available
  • 0.2 (2009-06-15) - Fix: Timestamp of last update could not be saved
  • 0.1 (2009-06-15) - USO create for testing purposes. Versions <1.x are "not full ready"
Discuss this script