Extension:ImageMap (Alternate)

From MediaWiki.org

Jump to: navigation, search

           

Manual on MediaWiki Extensions
List of MediaWiki Extensions
Crystal Clear action run.png
ImageMap (Alternate)

Release status: unknown
Implementation  Tag
Description Implements Image map as a superset of existing imagemap extensions
Author(s)  Michael Daly
Last Version  0.0 (2008-11-07)
MediaWiki  1.9
License GPLv2
Download withdrawn
Example  See below

check usage (experimental)

Contents

[edit] This extension withdrawn

This extension has been withdrawn. I will leave this page for documentation purposes for a brief period.

The current version of Extension:ImageMap used by Wikipedia has improved and many of the objectionable errors that caused me to create this as an alternate have been fixed. For that reason, I encourage you to use the Wikipedia supported version.

I realize that those who prefer to use the file-oriented features of this extension will be required to use Shannon McNaught's version and with it, lose the extended invalid HTML blocking that my extension provides. I can only encourage you to use the Wikipedia version instead and stop using the file-based image maps.

[edit] Choosing an ImageMap Extension

There are at least two 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 <imagemap> tags rather than using uploaded files.

If you're installing an ImageMap extension for the first time, it is advisable to choose the official version. That one is supported by the Mediawiki crew and is frequently updated to fix bugs.

If you have been using McNaught's version for a while, consider switching to the official version. If you only have a couple of image map pages, you can easily convert the files to inline format and change the pages to work with the newer version.

[edit] What can this extension do?

The purpose of the Imagemap is to allow one to create a clickable image. Images can be provided with areas that have an associated link. By moving your cursor over the image, a floating text box will appear showing the text for an area. Clicking that area will result in the page for that location being opened.

[edit] Usage

[edit] Variant 1 - Inline image map

This section describes the usage of the extension as it implements the version originally created by Tim Starling. It provides the following enhancements over Starling's current version:

  • The parameters are not case sensitive. Poly, POLY, poly, PoLy etc are all equivalent.

The description text here is based on that on Starling's page, but for the changes in this version.

[edit] Syntax example

<imagemap>
Image:Foo.jpg|400px|picture of a foo
# Map Parameters follow
rect 15 95 94 176   [[User]]
poly 131 45 213 41 210 110 127 109 [http://en.wikipedia.org/wiki/Display_device Display]
poly 104 126 105 171 269 162 267 124 [[Keyboard]]
# A comment, this line is ignored
circle 57 57 20    [[Idea]]
default [http://en.wikipedia.org/wiki/Images Images]
desc bottom-left
</imagemap>

[edit] Syntax description

The contents of an <imagemap> 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:

Format

Tokens

token coordinates link

poly, rect, circle

token link

default

token text

#, desc

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]]
  • [[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.

[edit] 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.

[edit] Syntax example

The format of the input is as follows:

<imagemap>Image=[[Media:imagename.ext]] | Map=[[Media:mapfile.mpi]]</imagemap>

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.

[edit] 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 <map> data block. The map block starts with a <map> statement and ends with a </map> statement. The content consists of one or more <area> or <a> statements that define the areas that are active in the image. Note that in HTML, these two statements are mutually exclusive - all must be <area> tags or all must be <a> tags. If both are included in HTML, the <area> statements are ignored. However, if you put both <area> and <a> 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.

<MAP name="map2">
  <AREA href="guide.html"  shape="rect" coords="0,0,118,28"   alt="Access Guide">
  <A href="shortcut2.html" shape="rect" coords="118,0,184,28">Go!!!!</A>
</MAP>

The first line in the example above shows the <map> 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 <a> and the </a> 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.

[edit] Example

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

<imagemap>Image=[[Media:Foo.jpg]]|Map=[[foomap.mpi]]</imagemap>

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

<map name=map1>
<area href="http://www.mediawiki.org/index.php/Idea"     shape=circle coords="57,57,20"                        alt="Idea">
<area href="http://www.mediawiki.org/index.php/User"     shape=rect   coords="15,95,94,176"                    alt="User">
<area href="http://en.wikipedia.org/wiki/Display_device" shape=poly   coords="131,45,213,41,210,110,127,109"   alt="Display">
<area href="http://www.mediawiki.org/index.php/Keyboard" shape=poly   coords="104,126,105,171,269,162,267,124" alt="Keyboard">
<area href="http://http://en.wikipedia.org/wiki/Images"  shape=default                                         alt="Images">
</map>

[edit] Installation

[edit] 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 \).

[edit] Changes to LocalSettings.php

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

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

[edit] Download

This extension has been withdrawn.

[edit] Utilities and links

[edit] 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

[edit] Utilities for inline image maps

A similar tool to those above for inline image maps:

  • 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.
Retrieved from "http://www.mediawiki.org/wiki/Extension:ImageMap_(Alternate)"