Help:Gadget-ImageAnnotator/Installation

From Wikimedia Commons, the free media repository
Jump to navigation Jump to search

Commons is running

version 2.3b

of this gadget.

ImageAnnotator is a JavaScript extension of the MediaWiki user interface, allowing users to place comments onto images shown on file description pages, similar to the "photo notes" on Flickr. This works on all image files for which the MediaWiki software displays a preview image on the file description page, i.e., PNG, JPG, GIF, and SVG files.

Image notes are only visible when the ImageAnnotator gadget is installed and activated (either by default for all users, or the viewing user has the gadget enabled). This means that notes added here at the Commons are not visible at other Wikis unless the gadget is installed there, too.

To install ImageAnnotator on a wiki, you need to be an administrator at that wiki; non-admin users cannot add the gadget.

Installing from scratch[edit]

Note: if you want to upgrade an existing installation to the latest version, do not follow these steps. Follow the steps in the section "Upgrading an installation" below.
Note: If you are using an altered MediaWiki installation with a custom skin that does not serve wikibits.js, you are on your own. You will have to modify the scripts to use whatever environment your custom skin provides (in particular script loading and getElementsByClassName).
Note: the below instructions assume that you want to install ImageAnnotator on another WMF project, not a private MediaWiki system.

General prerequisites:

  • Your wiki must have the Gadgets extension installed, if you want to install ImageAnnotator as a gadget (step 5 below) or if you want to install the MediaWiki:Gadget-DisableImageAnnotator.js emergency switch-off (optional step 4 below).
  • Install the ParserFunctions extension on your wiki, if it isn't already installed. Without it, the templates used by ImageAnnotator will not work as they should.
  • Make sure that the read API is enabled. It is enabled by default in MediaWiki 1.9.0 or later. If needed, set $wgEnableAPI to true in LocalSettings.php. You do not need to enable the write API.
  • ImageAnnotator was developed on MW 1.16alpha-wmf. It is known to work on MW 1.15.2. I do not know whether it works with older versions. It certainly won't work with MediaWiki versions lower than MW 1.12.

To install the gadget on another Wiki, follow these steps:

  1. Copy the following files from the Commons onto your own Wiki:
  2. Change the variable LAPI_file_store at the beginning of MediaWiki:LAPI.js on your wiki to match the image URLs served by your Wiki. For WMF wikis, no change should be necessary. Beware: if your wiki generates local URLs for images (not starting with a protocol/server part, but just containing the path, e.g. "/some/directory/images/b/bd/Test.jpg"), then make sure that the protocol/server part in that variable is optional, like this: "(https?://my\\.server\\.org)?/some/directory/images".
  3. Adapt the configuration MediaWiki:ImageAnnotatorConfig.js on your wiki as needed.
  4. (Optional) Set up MediaWiki:Gadget-DisableImageAnnotator.js as a gadget on your Wiki: copy MediaWiki:Gadget-DisableImageAnnotator to your Wiki and add the line "DisableImageAnnotator|DisableImageAnnotator.js" to MediaWiki:Gadgets-definition on your Wiki. This step is optional; it you enable the gadget for everyone (step 6 below), this gives people a way to switch if off for themselves if they experience any problems. If you instead choose step 5 below and set up ImageAnnotator itself as a gadget, you may safely skip this step; people will have to explicitly enable the ImageAnnotator gadget, and if they experience any problems, they can just disable it again.
  5. To set up ImageAnnotator as a gadget, write a description of it at MediaWiki:Gadget-ImageAnnotator on your Wiki, and add the line "ImageAnnotator|ImageAnnotator.js" to MediaWiki:Gadgets-definition (also on your Wiki).
  6. To enable the gadget for everyone, you may skip the previous step and instead add the line "if (wgNamespaceNumber != -1) importScript ('MediaWiki:Gadget-ImageAnnotator.js');" to MediaWiki:Common.js on your Wiki. (Or take a look at our MediaWiki:Common.js to see how we do this and copy that code over to your Wiki.)
  7. Copy the templates Template:ImageNote, Template:ImageNoteEnd, and Template:ImageWithNotes to your Wiki and protect them. Don't forget to adapt the category and the namespace selector (replace "File" as appropriate) in Template:ImageNote.
  8. Copy the templates Template:ImageAnnotations, Template:InlineImageAnnotations, Template:ImageNoteControl, and Template:ImageNoteColors to your Wiki.
  9. Copy the templates MediaWiki:ImageAnnotatorTexts, MediaWiki:ImageAnnotatorUITexts, and MediaWiki:ImageAnnotatorEditSummaries to your Wiki.
  10. Modify MediaWiki:ImageAnnotatorTexts to adapt it to your Wiki's default language. Replace the string lang="en" (one occurrence) as appropriate; e.g. at the Arabic Wikipedia, use lang="ar".
  11. Translate the texts in the edit summaries into the content language of your wiki.
  12. If you want, also create user interface texts in your language in the MediaWiki-messages noted on the help page. The messages in the default language of the Wiki always go into the pages without suffix. For other languages, use suffixes. On the Arabic Wikipedia, for instance, you'd put Arabic text at MediaWiki:ImageAnnotatorEditorLabel and the English text at MediaWiki:ImageAnnotatorEditorLabel/en.

The gadget will work for files uploaded locally on your Wiki exactly as it does for files here at the Commons. For non-local files (files hosted here at the Commons, but viewed on your Wiki), the script will enable viewing of the notes (if there are any), but will not allow modifying them. Modification of notes is possible only if the user views the file at the Wiki where the file actually resides.

Implement only one of either steps 5 or step 6. Don't do both. Step 5 installs ImageAnnotator as a gadget: logged-in users will have to explicitly enable the gadget to activate it for them; and it is unavailable for non-logged-in users. Step 6 instead activates ImageAnnotator for everyone, and you'd use the site-wide configuration (step 3) to define which classes of users may do what.

Upgrading an installation[edit]

If you want to upgrade an existing installation, some care has to be taken to make sure that the script doesn't break for some users but keeps working all the time. In particular, you have to account for client-side caching of scripts. The WMF projects are configured to make clients (i.e., the browsers of our users) cache scripts for 30 days). If your Wiki sets a different client-side cache timeout for scripts, adapt the instructions below accordingly.

Upgrading from version 1 to version 2[edit]

In version 1, the file MediaWiki:Gadget-ImageAnnotator.js had no version information. In version 2, there is a line saying "THIS IS ImageAnnotator VERSION 2" at the top of the file.

  1. Copy MediaWiki:Tooltips.js, MediaWiki:TextCleaner.js, and MediaWiki:LAPI.js to your Wiki. Make sure that in LAPI, the variable LAPI_file_store (near the top of the file) is set correctly. (The new versions of these libraries are backwards-compatible and will work fine with an old installation of ImageAnnotator.)
  2. Add <span class="wpImageAnnotatorOwnPageLink"> around the "fullurl" links in all subpages of MediaWiki:ImageAnnotatorSaveError on your Wiki.
  3. Create new messages on your Wiki:
  4. Copy MediaWiki:ImageAnnotatorEditSummaries to your wiki
  5. Copy the templates Template:ImageAnnotations, Template:InlineImageAnnotations, and Template:ImageNoteColors to your Wiki.
  6. Update MediaWiki:ImageAnnotatorUITexts and MediaWiki:ImageAnnotatorTexts. See this diff and this diff for the changes needed.

At that point, you'll have an ImageAnnotator version 1 running with version 2 libraries, and you'll have prepared the new interface texts. 31 days later you can be sure that everyone has got the new libraries, and you can roll out version 2 of ImageAnnotator. You must wait for the client-side cache interval to expire, otherwise ImageAnnotator may break for some users, who would then have to explicitly refresh their browser's cache to get it to work again.

  1. Copy MediaWiki:ImageAnnotatorConfig.js to your wiki. Adapt it as needed.
  2. Copy MediaWiki:Gadget-ImageAnnotator.js to your wiki.

At that point, the installation of version 2 is complete. Optionally, you may after another 31 days delete the message MediaWiki:ImageAnnotatorDeleteConfirm and all its translations, and remove it from MediaWiki:ImageAnnotatorUITexts.

Upgrading from version 2 to version 2.1[edit]

In version 2.1, there is a line saying "THIS IS ImageAnnotator VERSION 2.1" at the top of MediaWiki:Gadget-ImageAnnotator.js.

  1. Get the newest MediaWiki:TextCleaner.js. It contains a localization improvement; the change is transparent.
  2. Get the newest MediaWiki:LAPI.js — it should have a function called loadImage in LAPI.DOM. This version or any younger version will do.
  3. Copy the new interface text MediaWiki:ImageAnnotatorCannotEditMsg (plus its translations, if you want), and include it in MediaWiki:ImageAnnotatorUITexts.
  4. Copy Template:ImageNoteControl to your wiki and protect it.
  5. Wait until 31 days after the last change to your copy of MediaWiki:LAPI.js on your wiki.
  6. Copy the new MediaWiki:ImageAnnotatorConfig.js, and adapt it to your wiki as needed.
  7. Wait for at least 4 hours.
  8. Copy the new MediaWiki:Gadget-ImageAnnotator.js.

The waiting (31 days, 4 hours) is again to let client-side cache times expire naturally, so that users can have uninterrupted service. Otherwise, some people will have new versions of MediaWiki:Gadget-ImageAnnotator.js but still an old version of MediaWiki:LAPI.js in their cache, which won't work.

Upgrading from version 2 or 2.1 to version 2.2[edit]

In version 2.2, there is a line saying "THIS IS ImageAnnotator VERSION 2.2" at the top of MediaWiki:Gadget-ImageAnnotator.js.

If starting from version 2, follow the steps above, but make sure you get a MediaWiki:LAPI.js from March 5, 2010, or younger. This version or any younger version will do.

If upgrading from V2.1:

  1. Copy MediaWiki:LAPI.js, version from March 5, 2010 or younger; this version or any younger version. You do not have to wait 31 days before continuing; the changes are minor and do not affect the function of ImageAnnotator on most sites. (There's a small bugfix for IE for loading images from wikis that do not automatically generate missing thumbnails via a 404 handler. If you didn't experience any problems loading the zoom images on IE until now, you don't need the fix.)
  2. Copy MediaWiki:ImageAnnotatorConfig.js (version from March 5, 2010 or younger; this version or any younger version).
  3. Wait at least four hours.
  4. Copy the new MediaWiki:Gadget-ImageAnnotator.js.

Upgrading from version 1 to version 2.1 or 2.2[edit]

Follow the steps for upgrading to version 2, but:

Then wait 31 days, then do the final two steps.

MediaWiki V1.17[edit]

If you're using MediaWiki 1.17 on your wiki, you must use ImageAnnotator 2.2b. Previous versions will fail upon modifying image notes: they'll report a "version inconsistency" after the edit. If upgrading from an ImageAnnotator < 2.2, follow the steps for upgrading to version 2.2, but make sure you get a MediaWiki:LAPI.js from February 16, 2011 or younger (this version or any younger) and a MediaWiki:Gadget-ImageAnnotator.js that says "VERSION 2.2b"at the top (this version or any younger).

Upgrading from version 2.2 to version 2.2b[edit]

This upgrade is mandatory if you plan to switch your wiki to MediaWiki 1.17.

  1. Get MediaWiki:LAPI.js from February 16, 2011 or younger (this version or any younger) and copy it to your wiki.
  2. Get a MediaWiki:Gadget-ImageAnnotator.js that says "VERSION 2.2b"at the top (this version or any younger) and copy it to your wiki.

Then wait 31 days (or whatever your client-side cache epoch for JavaScripts is) before upgrading your wiki to MW1.17. You don't need to wait 31 days between updating LAPI and the gadget; the changes are backwards compatible.

If your wiki is already running MW1.17, upgrade all the same, and instruct people to refresh their browsers' caches if they experience problems.

Upgrading to version 2.3a[edit]

Basically, follow the steps for upgrading to 2.2b, but use the 2.3a files instead of the 2.2b files:

  1. Get MediaWiki:LAPI.js from December 2011 or younger (this version or any younger) and copy it to your wiki.
  2. Get MediaWiki:ImageAnnotatorConfig.js from december 2011 or younger (this version or any younger), adapt as needed, and copy it to your wiki.

Then wait 31 days (or whatever your client-side cache epoch for JavaScripts is). Then get MediaWiki:Gadget-ImageAnnotator.js from January 2012 (this version or any younger) and copy it to your wiki.

Brief version history[edit]

Version 2.3a
January 2012: Fixes for rectangle colors. Includes the V2.3 changes. Note: between V2.2b and V2.3, ImageAnnotator was also made to handle protocol-relative URIs correctly (since September 2011). Users are strongly advised to upgrade to V2.3a.
Version 2.3
December 2011: some code-clean-up regarding launching the gadget; plus handling of images inside collapsed regions. Never released at the Commons.
Version 2.2b
February 2011: another fix for MediaWiki V1.17.
Version 2.2a
February 2011: minor fix for MediaWiki V1.17.
Version 2.2
March 2010: internal cleanup, fix a few minor bugs nobody had noticed yet, plus configurations for the deletion reason prompt.
Version 2.1
December 2009/January 2010: some minor improvements concerning zoom image loading; avoids ActiveX prompts on IE with some strange "security settings"; plus the things marked as of Version 2.1 on the help page.
Version 2
End of October 2009. Display of image notes also on images included anywhere in articles.
Version 1
Initial release (August 2009). Editing and display of image annotations on image description pages, as well as on other pages through {{ImageWithNotes}}.
Retrieved from "https://commons.wikimedia.org/w/index.php?title=Help:Gadget-ImageAnnotator/Installation&oldid=699406335"