Extension:ImageMap (Alternate)

Choosing an ImageMap Extension
There are at least three ImageMap extensions for Mediawiki. How do you decide which to use?


 * The oldest one is Shannon McNaught's version, which uses image map information supplied in a text file. It may no longer be supported and is not compatible with the version on Wikipedia.
 * The "official" version - that is, the one used by Wikipedia - is Tim Starling's version. It works for MW 1.9 and newer.  This one includes image map information inline between the

Syntax description
The contents of an &lt;imagemap&gt; tag consists of blank lines, comments (starting with #) and logical lines.

The first logical line specifies the image to be displayed. It is in the following format:

Image: imagename.ext | options

where:
 * imagename: is the name of an image that has been uploaded to the wiki.
 * ext: is a valid image extension (e.g. jpg, png etc)
 * options: Options are specified as per thumbnails, separated by the pipe ( "|" ). For details on thumbnail options, see Wikipedia extended image syntax.  Note that if you provide a default line (see below) the text of the default will override a caption provided as an option.

Further lines are split into information separated by blank spaces. The function of each line is determined by the first token in the line. The tokens are not case sensitive. The order of the lines is not important. Each line is in one of the following forms: The tokens are defined as follows:
 * # :A comment. The token is followed by any text.  A comment is a single line.  For multiple line comments, each line should be preceded by a #.
 * desc:Specifies the location of the image description link. May be either top-right, bottom-right, bottom-left, top-left or none. This puts a blue "i" icon in the specified corner, linking to the image description page. The default is bottom-right.
 * poly:polygon. A shape made of several line segments. The coordinates of the vertices are specified in as x1 y1 x2 y2... xn yx.  The coordinates do not have to close the polygon; the last vertex is assumed to connect to the first.
 * circle:A circle. The first two parameters that follow are the coordinates of the centre, the third is the radius.
 * rect:A rectangle. The coordinates specified are for the top-left and bottom-right corners of the rectangle.
 * default:This gives the default link, where no other regions are specified. If only a default link is provided, the entire image will link to the page specified.

If only a default parameter and link are provided, the entire image can be clicked to go to the link.

All coordinates are according to the full-size image, not the visible image. Coordinates are delimited by whitespace not commas. The image can be scaled using thumbnail syntax, in which case the image map coordinates will be automatically scaled as well.

Links can be either internal or external.


 * Internal Links:Internal links are given in either of the following forms:
 * Page title
 * description.
 * In the latter case, the part after the pipe ( "|" ) becomes the title attribute of the link. In most browsers, it will pop up as a tooltip when the user hovers over it. If no explicit link description is given, the page title will be used.


 * External Links:External links are given in either of the following forms:
 * 
 * description, may have many words.
 * In the latter case, the description after the first blank (" ") becomes the description of the link. In most browsers, it will pop up as a tooltip when the user hovers over it. If no explicit link description is given, the link will be used.

Variant 2 - File-based image map
File-based image maps are an alternative to the inline image map approach.

This section describes the usage of the extension as it implements the version originally created by Shannon McNaught. It provides the following enhancements over McNaught's version:
 * This version works with single wikis and Wiki Families that use a common or pool resource wiki for images and files.
 * This version processes the input file and screens out any HTML that is not specific to image maps. This reduces the risk of someone slipping malicious HTML into the wiki via a file upload.

Syntax example
The format of the input is as follows: where
 * imagename:the name of image file
 * ext:a valid image extension (e.g. jpg, png etc.)
 * mapfile.mpi:the name of the file containing HTML format map information. The extension that is used is decided by the wiki administrator.

Note that the type of file must be Media: for both the image and the map data file.

File format
The content of the mapfile.mpi is standard HTML map definition statements. This page will only provide an overview of the subject. For a full understanding of HTML image maps, please consult an HTML primer, textbook or web page.

Specify the image map with a data block. The map block starts with a statement and ends with a statement. The content consists of one or more or  statements that define the areas that are active in the image. Note that in HTML, these two statements are mutually exclusive - all must be tags or all must be  tags. If both are included in HTML, the statements are ignored. However, if you put both and  tags in the same map definition, as in the example below, both types will be processed by the imagemap extension. If you copy the map information from a regular HTML web page, this will result in different behaviour on the wiki than in the HTML web page. You should either delete one type of area specification or convert them to all be the same type statement.

  Go!!!! 

The first line in the example above shows the statement where the name tag identifies the name of the map. This name is important as it is used as the name for the usemap identifier of the image.

The lines following the map statement record the active image areas. Both types of statement identify the link with an href tag, the area shape with a shape tag and the coordinates with a coords tag. The alt text is identified with an alt tag in the former statement and is listed between the  and the  HTML tags in the latter statement.

Coords must be a comma-delimited list of vertex coordinates (x1,y1,x2,y2,...,xn,yn) for polygons, a comma-delimited list of the top-left and bottom right corners (left-x, top-y, right-x, bottom-y) for rectangles and a comma-delimited list of the centre and radius (center-x, center-y, radius) for circles.

Note that if a shape of default is specified with a link and no coordinates, the entire image outside of the other areas is indicated. If a default is supplied alone, clicking anywhere on the image activates the link.

Example
To repeat the example from the inline Imagemap above, the following is the input:

In this case, the map file, foomap.mpi, contains the following:

    

Imagemap Extension
1. To install the Imagemap extension, download the files. 2. Create a folder in the wiki heirarchy under the /extensions/ folder:
 * ..../yourwiki/extensions/ImageMap

3. Place all the files in the ImageMap folder. 4. Update LocalSettings.php, adding the following line to the bottom: require_once( "$IP/extensions/ImageMap/ImageMap.php" );
 * If you enable image map file usage (see $ImageMapEnableFileInput below), then decide what extension you will allow for map files (e.g. .map, .mpi, .dat and so on) Any extension is permitted.  Then add the extension to the $wgFileExtensions array.  If you do not have this parameter in LocalSettings.php, copy it from DefaultSettings.php (in your wiki's includes directory).  It will contain a list of acceptable image extensions - add your chosen map file extension.  For example, if you choose "mpi", then the variable will look like:

$wgFileExtensions = array( 'png', 'gif', 'jpg', 'jpeg', 'mpi' );


 * In addition, you should ensure that the file upload parameters in PHP.INI (in your PHP directory) are set:


 * file_uploads        should be set to "On" and
 * upload_max_filesize should be adaquate to allow the largest map file or image you will allow.


 * As well, a warning value can be set in LocalSettings.php

$wgUploadSizeWarning = a value less than upload_max_filesize.

5. Update ImgMapSettings.php if required.


 * This settings file contains several variables used to control the operation of this extension. Two of them control the input formats permitted for users.  The default settings are:

$ImageMapEnableFileInput  = true; $ImageMapEnableInlineInput = true;
 * If the former is true, then users will be able to use uploaded files to generate image maps. If you do not want to enable this feature, then set this parameter to false.
 * If the latter is true, then inline map definitions are permitted. To disable this feature, set this parameter to false.


 * In addition, if you set $ImageMapEnableFileInput to true, and $wgUseSharedUploads in LocalSettings.php is set to false (or not set and is defaulted to false in DefaultSettings.php) then you must ensure that the parameter $ImageMapWikiPath is set correctly. This parameter is used to determine the location of image map files.  It should work correctly with the default setting:

$ImageMapWikiPath = $IP;
 * However, if your configuration is not typical and you have moved your images directory to a different location, then you may have to change this parameter. $ImageMapWikiPath is the path to the wiki root - the location of index.php and LocalSettings.php for the wiki.  Normal configurations have the images directory as an immediate subdirectory of this wiki root.  If yours is different, set it to the directory that has images as an immediate subdirectory.  It should NOT end in a slash or backslash (/ or \).

Changes to LocalSettings.php
Add the following line to the end of your LocalSettings.php file:

require_once("$IP/extensions/Imagemap/Imagemap.php");

Download
While the extension is in beta, please get the files from my web site. The link will take you to my Subversion page for the file. If you right-click on a file name, Firefox will open a context-menu - select Save Link As... to initiate a download. Other browsers will act similarly.


 * Imagemap (Alternate) extension files

Utilities for file-based image maps
There are utilities available that will generate the map and area statements with the coordinate data. You can specify the image and select points on the image to define a shape. The utility with calculate the coordinates of these points and write out the appropriate statements. This makes it easy to generate the map files. Here are a few examples - none of these are specifically sanctioned and are only offered as suggestions. You can use a search engine to find others.


 * Clickable Image Map Maker. This web page allows the user to select an image file on his own local hard drive, then creates a second page using that image, and allows the user to very quickly generate the HTML code for an imagemap to be used in his own files. It also offers some handy pop-up menus to speed the process of coding the actual href. Complicated maps can be created in less than a minute (no kidding). Requires a Javascript and frames capable browser, designed and tested on a Mac using Netscape Navigator.
 * Mapedit is a WYSIWYG editor for imagemaps, available for Microsoft Windows and the X Window System. Use Mapedit to generate, or convert to, NCSA, CERN, or client-side map files.
 * Meracl ImageMap Generator is a free map Imagemap generator.
 * GIMP - The GNU Image Manipulation Program

Utilities for inline image maps
A similar tool to those above for inline image maps:


 * A graphical tool to determine the coordinates. Author: mw:User:Dapete. This directly generates inline format image map data.


 * The Image Map Conversion special page is used to convert HTML format image map information into inline Imagemap format. This can be used to convert the output from the utilities for file-based image maps as listed above.