Extension:ImageMap (Alternate)

This extension is designed to be a drop-in replacement for the existing

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:
 * [http:\\valid.url\page.html]
 * [http:\\valid.url\page.html 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-base 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 not important as it will be replaced by the imagemap extension to be the same as a generated usemap identifier used for 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:

    

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 by KayakWiki 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.

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.

In addition, there is a utility Map Conversion Utility that can be used to convert HTML format image map information to inline format.

Map Conversion Utility
The Map Conversion Utility is used to convert HTML format image map information into inline Imagemap format. The input to this utility can be:
 * HTML code containing image map information
 * Files created by image map utilities (listed above) containing image map HTML code
 * Files compatible for input to file-based image maps or to Shannon McNaught's extension

The output can be used in:
 * Inline image map input as described above
 * Tim Starling's extension - however:
 * it will not force poly specifications to come before other shape specs.

Usage
When you open the page, you will see an text input line for a local file under the header Source filename:. Input a valid path and file name for a file containing image map HTML statements. Alternatively, click the Browse button and use the local computer's file dialog to select a local file.

If the file contains both and  HTML statements, you can select Allow mixed  and <AREA> tags to be converted if you wish both sets to be converted. If you do not select this option, area atatements will be ignored and only  statements will be converted.

When you have input the required file path and name and checked or unchecked the selection, click on Submit. The text area below the input area will display either an error message or the converted output.

In order to use the output, mark the converted text and copy the content. Paste the content onto the page you are creating and add the remaining information.

Note:
 * You can specify an entire web page HTML file. Only the first set of map statements will be processed.  If more than one set of map statements exist and you wish to convert them all, you will have to split the file into parts with one set of map statements in each.
 * All statements outside of and are ignored.
 * All statements between and that are not map related statements will be converted to comments preceded by a #.
 * Links in an HTML file are either relative or absolute URLs. You will likely have to change these to either local page links or to absolute URLs to be used in the imagemap extension.
 * Some image map utilities will put a default area statement in the HTML file. It will look something like  <AREA shape=default nohref>   If this default area statement has no href, you will get an error.  Either change the file so it has a valid href or delete the unusable default area statement.

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
require_once("$IP/extensions/Imagemap/Imagemap.php");

Map File Conversion Program
This is not an extension, it is a stand-alone php program that generates a web page. I intend to look into converting it to a Special page in the future.


 * 1) Create a folder in the wiki heirarchy under the /extensions/ folder:
 * ..../yourwiki/extensions/MapFileCvt


 * 1) Place all the files in the MapFileCvt folder.
 * 2) Update your web server configuration to allow users to access php files in the new folder
 * 3) Point your browser to MapFileConvert.php and execute it.

You can put a link URL to this program on your wiki so users can access the utility.

Download
While the extension is in beta, please get the files from my Wiki. Both links will take you to my wiki page for the file. If you click on the file name on the wiki page, Firefox will initiate a download. Other browsers will act similarly or will require a right-click to bring up a context menu and selection of "download file" or similar.


 * Imagemap extension files in a single zip file
 * Map File Conversion files in a single zip file