The West API

August 14th, 2010 Leave a comment Go to comments

In 1.28 we introduced a new The West API. It’s main purpose right now is to check versions of scripts so that incompatible updates are recognized and reported to the user. In case of updates we receive quite a few bug reports that can are later identified as user script errors. To prevent this, or at least to reduce the number of false reports, we kindly ask you to register your script using our API. This allows us to identify problems quicker and by saving some time here.

The code comes without warranty – please report us any bugs or problems you might run in. The version check is currently a bit flawed, but it’ll be ok for the next few releases at least.
Here is the complete source of that API class including comments:

/**
 * TheWestApi
 *
 * Can be used by script authors for getting the newest version or notice the player
 * that his version of the script is outdated.
 *
 * Example:
 *		TheWestApi.register('myscript', 'My Script', '1.27', '1.28', 'Myname', 'http://www.x32980482.com/');
 *
 * Greasemonkey Example:
 *		var RegisterScript  = document.createElement("script");
 *		RegisterScript.type = "text/javascript";
 *		RegisterScript.text = "TheWestApi.register('myscript', 'My Script', '1.27', '1.28', 'Myname', 'http://www.example.com/')";
 *		document.body.appendChild(RegisterScript);
 */
var TheWestApi = {
	/**
	 * Stores all registered Api's
	 *
	 * @var		{array}
	 */
	apis:			[],

	/**
	 * Gets the current version of the world, can be used by script authors
	 * to switch between versions files (compatibility).
	 *
	 * @var		{string}
	 */
	version:		'',

	/**
	 * Stores the redirect link, used for author website
	 *
	 * @var		{string}
	 */
	redirectLink:	'',

	/**
	 * Register a script, has to be done by the script author.
	 * Website and author parameters are optional, when given the user will see the webpage link.
	 * It will help the user to faster update (f.e the user forgot the link) or just for notice that his script is outdated.
	 *
	 * @param	{string}		key
	 * @param	{string}		name
	 * @param	{string}		minVersion
	 * @param	{string}		maxVersion
	 * @param	{string}		author				[optional]
	 * @param	{string}		website				[optional]
	 * @throws	{string}
	 * @return	{boolean}
	 */
	register: function(key, name, minVersion, maxVersion, author, website)
	{
		var checkParam = function(key, value) {
			if(!value) throw 'TheWestAPI: given parameter (\''+ key +'\') requires a value.';
		}
		checkParam('key',		 key);
		checkParam('name',		 name);
		checkParam('minVersion', minVersion);
		checkParam('maxVersion', maxVersion);
		this.checkRegistered(key);

		var api = {
			'key':			key.escapeHTML(),
			'name':			name.escapeHTML(),
			'minVersion':	minVersion.escapeHTML(),
			'maxVersion':	maxVersion.escapeHTML(),
			'author':		author  ? author.escapeHTML()  : '',
			'website':		website ? website.escapeHTML() : ''
		};
		api.isOutdated = this.isOutdated(api);
		this.apis.push(api);
		return true;
	},

	/**
	 * Checks if the given key is already registered.
	 *
	 * @param	{string}		newkey
	 * @throws	{string}
	 * @return	{void}
	 */
	checkRegistered: function(newkey) {
		for(var i = 0; i < this.apis.length; i++) {
			if(this.apis[i].key != newkey) continue;
			throw 'TheWestAPI: given parameter (\''+ this.apis[i].key +'\') is already registered!';
		}
	},

	/**
	 * Returns if the user script is outdated or not.
	 *
	 * @param	{object}		api
	 * @return	{boolean}
	 */
	isOutdated: function(api)
	{
		if(!api || 'object' !== $type(api)) throw 'TheWestAPI: method (\'isOutdated\') requires an valid parameter.';
		return (api.minVersion > this.version || api.maxVersion < this.version);
	},

	/**
	 * Displays the outdated scripts in a messagebox,
	 * with some informations about the user script name, author and website.
	 *
	 * @return	{boolean}
	 */
	displayOutdated: function()
	{
		if(0 == this.apis.length) return false;
		var i, outdated, title, html, currentVersionMsg, compatibleMsg, deactivateItMsg, followingMsg;

		// checks every registered script
		outdated = this.apis;
		for(i = 0; i < outdated.length; i++) {
			if(!outdated[i].isOutdated) outdated.pop(i);
		}
		if(0 == outdated.length) return false;

		// declaring the information strings
		compatibleMsg		= _('Die aktivierten Skripte sind mit der derzeitigen Version möglicherweise nicht kompatibel.') + '<br />';
		deactivateItMsg		= _('Falls es zu Probleme kommen sollte, deaktiviere oder aktualisiere die Skripte, falls dennoch Probleme auftreten, melde diese beim Support.') + '<br />';
		currentVersionMsg   = '<br />' + _('Derzeitige Version ist $1').replace('$1', '<strong>'+ this.version +'</strong>');
		followingMsg		= '<br />' + ngettext(
			_('Folgendes Skript ist davon betroffen:'),
			_('Folgende Skripte sind davon betroffen:'), outdated.length) + '<br />';

		// creates the html that will be displayed for a single script
		var scriptHtml = function(api) {
			return [
				'<div class="scriptInfo" id="'+ api.key +'">',
					'<div class="scriptInfoLeft">'+ api.name +'</div>',
					'<div class="scriptInfoRight">(',
						_('Mindestens für Version $1, maximum $2').replace('$1', '<strong>'+ api.minVersion +'</strong>')
																  .replace('$2', '<strong>'+ api.maxVersion +'</strong>'),
						(api.author ? ' | '+_('Author: $1').replace('$1', api.author) : ''),
						(api.website ?' | '+ (('<a href="'+ api.website +'">'+ _('Webseite') +'</a>')) : ''),
					')</div>',
					'<div style="clear:both;"></div>',
				'</div>'
			].join('');
		};

		// gets the html of each script
		var inHtml = '';
		for(i = 0; i < outdated.length; i++) {
			if(outdated[i].website) {
				outdated[i].website = this.redirectLink + outdated[i].website;
			}
			inHtml += scriptHtml(outdated[i]);
		}

		// general informations
		title = ngettext(
			_('Benutzer Skript nicht kompatibel!'),
			_('Mehrere Benutzer Skripte sind nicht kompatibel'),
			outdated.length
		);
		html  = [
			'<div id="outdatedScripts">',
				'<div id="outdatedInfo">',
					compatibleMsg,
					deactivateItMsg,
					currentVersionMsg,
					followingMsg,
				'</div>',
				inHtml,
			'</div>'
		].join('');

		// display the outdated scripts
		new MessageBox({
			title:					title,
			message:				html,
			width:					480,
			height:					undefined,
			options:				[ ['ok'] ],
			cancelOnOutsideClick:	false
		}).show();
		return true;
	}
}
  1. August 20th, 2010 at 08:48 | #1

    how can I download the code without line numbers?

  2. August 20th, 2010 at 09:48 | #2

    @Bomberzocker : There’s an green icon on the right top of the code (vi). Click on it to get a raw version.

  3. Knight
    August 20th, 2010 at 14:17 | #3

    So I’ve just to copy the source code into my GM script and create the register var? That’s easy. Thx zet 🙂

  4. foobar
    August 26th, 2010 at 14:50 | #4

    @Knight: No you don’t need to copy the source code, you need only to add

    “var RegisterScript = document.createElement(“script”);
    RegisterScript.type = “text/javascript”;
    RegisterScript.text = “TheWestApi.register(‘myscript’, ‘My Script’, ‘1.27’, ‘1.28’, ‘Myname’, ‘http://www.example.com/’)”;
    document.body.appendChild(RegisterScript);”

    to your greasemonkey script.

    This source code is part of the west javascript

  5. Bluep
    June 18th, 2013 at 01:54 | #5

    uhm… what about the promised (2013-01-25) update of this page..?

    And.. *prods this* is the DevBlog still alive?

  6. Tanais
    February 12th, 2015 at 15:10 | #6

    @Bluep

    Seems pretty dead here :'( Time to start sending letters to Innogames? 😉

  7. February 24th, 2016 at 21:24 | #7

    Would be nice to see this updated, along with docs on what methods we can call. TW-Friends is nice and I have been looking over the source but some real documentation on the api and methods would be great 🙂

  1. No trackbacks yet.