View source for MyWiki:Wikipedia Signpost/2008-03-03/Tutorial

<noinclude>{{Tutorials}}</noinclude>
{{Wikipedia:Wikipedia Signpost/Templates/Signpost-article-header-v2  |{{{1|Tutorial:  How to use an ImageMap}}}|By [[User:Nihiltres|Nihiltres]]}}

This week's tutorial explains the syntax for the [[mw:Extension:ImageMap|ImageMap extension]] of the [[MediaWiki]] software, which allows images and sections thereof, of any shape and size, to link to any type of page link that can be linked to via text (any valid wikilink, interwiki link, or external link).

A basic understanding of [[Help:Images and other uploaded files|image syntax]] is assumed.

=== When to use ImageMap ===

An ImageMap does not behave the way a normal image does, where clicking anywhere on an image opens its image description page. Instead, with an ImageMap, clicking on the image is the equivalent of clicking on a link; different sections of the image may link to different pages, including external links.  ImageMap should generally only be used with free images (that is, those that do not fall under the [[WP:NFCC|non-free content criteria]]), because creating an ImageMap can be regarded as a substantial modification of an image. 

ImageMaps are generally used within templates, where it is desirable to have images or icons link to particular pages or sections of a page, and in portals, where it links icons for related portals to that portal and links the logos of various projects in the interwiki section to their respective projects. If ImageMap does not add to the presentation of a template, portal, or article, it should probably not be used, since the ideal behaviour—for transparency with image licensing—is to have the image link to the description page.

To summarize:
<div style="border-left: green solid 2px;">
:#If the image is [[WP:NFCC|non-free content]], it is advisable to not use ImageMap.
:#If ImageMap would not add significantly to the presentation of the page upon which it is used, one should probably not use ImageMap on that page.
</div>

=== Creating an ImageMap ===

To create an ImageMap, one can use either the tags <code><nowiki><imagemap></nowiki></code> and <code><nowiki></imagemap></nowiki></code>, or the [[WP:MAGIC|magic word]] (and [[mw:Extension:ParserFunctions|ParserFunction]]) <code><nowiki>{{#tag:imagemap|</nowiki>&nbsp;&nbsp;&nbsp;<nowiki>}}</nowiki></code>. The <nowiki><tag></nowiki> format is generally preferable (a good practice) for simple ImageMaps, but does not (currently) function properly with template parameters, magic words, or ParserFunctions. In this case, the <nowiki>{{#tag}}</nowiki> format is a simple and effective workaround, which replaced older, usability-troublesome [[Cascading Style Sheets|CSS]] workarounds for templates that created images linked to alternate pages, such as {{[[Template:click|click]]}}.

To summarize:
<div style="border-left: green solid 2px;">
:#There are two syntactically correct containers for ImageMap syntax: <code><nowiki><imagemap></nowiki></code> and <code><nowiki></imagemap></nowiki></code>, or <code><nowiki>{{#tag:imagemap|</nowiki></code> and <code><nowiki>}}</nowiki></code>.
:#The former is best practice, but only the latter allows the use of template parameters, magic words, and ParserFunctions.
</div>

=== The image line ===

The first line of any ImageMap ''must'' be a line specifying the image being used. If no image is specified, or the image that is specified does not exist, then the ImageMap will produce the following error message:

:<imagemap>
Image:NoSuchImage.svg|100px|This is an example of the nonexistent-image error.
default [[User:Nihiltres]]
desc none
</imagemap>

Note, however, that there must be a linebreak after the imagemap tag (of either form) and before this line. This image code is identical in syntax to normal image syntax, albeit without the surrounding square brackets (<code><nowiki>[[ ]]</nowiki></code>). All of the [[Help:Images and other uploaded files|basic image syntax]] and [[Wikipedia:Extended image syntax|extended image syntax]] applies, though options such as <code>thumb</code> may not be fully supported by ImageMap. The text provided as a comment in the image syntax on this line is not visible except as alternative text when the image is unavailable, except for options such as <code>thumb</code> which might use it.
:For example, in the case that the syntax for the normal, unmapped image was <code><nowiki>[[Image:WikipediaSignpostHead.svg|100px]]</nowiki></code>, the ImageMap code for the first line would be
:<code>Image:WikipediaSignpostHead.svg|100px</code>

To summarize:

<div style="border-left: green solid 2px;">
:#Construct the image syntax normally
:#Remove the <code><nowiki>[[</nowiki></code> and <code><nowiki>]]</nowiki></code> from around the image syntax
:#Use the resulting text as the image line
</div>

=== Mapping an area to a link ===

After the first line, any valid lines are acceptable. Usually the second line, and perhaps more following it, contain the area or areas which the ImageMap uses to map to the image. An ImageMap must have at least one area, or default target, specified, or it outputs an error message like the following:

:<imagemap>
Image:Om-mani-padme-hum-mantra.svg|100px|This is an example of the no-area-specified error.
desc none
</imagemap> 

Each line that describes an area can be subdivided into three parts: the type of area, numerical parameters for that area as necessary, and a valid wikilink or external link. These parts are separated on the line by spaces. When hovering over an area, the link destination, or the alternate text (if provided), is displayed as the [[tooltip]] when applicable.

Numerical parameters often take the form of coordinates; these coordinates are the number of pixels from the upper-left-hand corner ''given the default size'' of the image. When a 150px-wide image is scaled to 50px, the upper-right-hand corner will be designated <code>150 0</code> despite the image as rendered only being 50px wide.

When two or more areas overlap, the area specified first in the code takes precedence.

There are four types of area that can be used. For the more complex areas, it is easiest to use the [http://tools.wikimedia.de/~dapete/ImageMapEdit/ImageMapEdit.html?en visual ImageMap editor] on the toolserver:

<div style="border-left: green solid 2px;">
:;Default:A default area is specified by the type <code>default</code> and the link. It specifies a default target for the image where no areas are specified which overrides the default behaviour of no link for otherwise unlinked areas. Most simple ImageMaps with a single target should use only this type for simplicity. This type should only be specified once, and should be the last type specified by order.
::For example, the following would be a valid line:
::<code><nowiki>default [[Wikilink|Tooltip text]]</nowiki></code>
:;Rectangle:The simplest shape is a rectangle. First, the type <code>rect</code> should be specified, and then two points are specified using four numbers separated only by spaces. The first two numbers correspond to the top-left corner of the rectangle, and the second pair correspond to its bottom-right corner. The number pairs are distances, in pixels, first horizontally and then vertically from the top-left pixel of the image, relative to its default size. For example, the top-left pixel of the image has the coordinates <code>0 0</code>, while the pixel two to the right and one downwards from it would be <code>2 1</code>. After these coordinates are specified, any valid link, in normal wiki syntax, is used.
::For example, the following would be a valid line:
::<code><nowiki>rect 0 0 150 150 [[Wikilink|Tooltip text]]</nowiki></code>
:;Circle:Many buttons, icons, and other images conducive to use with ImageMap are circular. For this, one uses the type <code>circle</code>. After specifying the coordinates for the centre of the circle as for the corner of a rectangle, a third single number specifies the radius of the circle, in pixels. After this is specified, any valid link, as for the rectangle, is used.
::For example, the following might be a valid line:
::<code><nowiki>circle 100 100 50 [[Wikilink|Tooltip text]]</nowiki></code>
:;Polygon:Sometimes complex shapes are required for ImageMaps. This, using the type <code>poly</code> allows one to specify a polygon as an area by specifying the coordinates for each point of the polygon in turn, using the same method used to define points for the rectangle. Irregular shapes may therefore be properly mapped. When polygons are defined, they ''must'' be placed before any other shapes in the code.  The number of points used should be kept to a minimum, especially as polygons with many points sometimes do not work. Polygons with fewer than 20 points should always work. For more complex shapes, using multiple overlapping polygons is an effective workaround and helps simplify each shape. After the last point, any valid link can be used.
::For example, the following might be a valid line, which would create a triangle in the upper-left corner of an image:
::<code><nowiki>poly 0 0 0 150 150 0 [[Wikilink|Tooltip text]]</nowiki></code>
</div>

=== The image description icon ===

Since images should, as a good practice, include a link to the image description page, ImageMap includes, by default, an information icon on the image linking to the image description page. This by default displays on the bottom-right of an image, but can be changed by using <code>desc</code> and a location: any of <code>top-right</code>, <code>bottom-right</code>, <code>bottom-left</code>, <code>top-left</code>, or <code>none</code> to disable it completely.

<div style="border-left: green solid 2px;">
:The <code>desc</code> parameter allows you to change the location of the information icon, or disable it.
::For example, the following would be a valid line disabling the description icon:
::<code>desc none</code>
</div>

=== Overview ===

Once all of the elements have been determined, they can be placed within the container of choice, separated by linebreaks. The following ImageMap demonstrates valid syntax:

<pre><imagemap>
File:Bad Title Example.png|275px|border|This is used as alternate text.
#Note that in the above line, the border style is invoked.

# Polygons appear first in the code, always.
poly 14 186 25 219 52 219 63 186 [http://www.wikipedia.org This link is polygon-shaped, and uses an external link.]
rect 107 32 256 182 [[Earth|This rectangle links to the Earth article.]]
circle 85 135 12 [[Circle|This area is a circle.]]

desc none
</imagemap></pre>

The code produces the following:

<imagemap>
File:Bad Title Example.png|275px|border|This is used as alternate text.
#Note that in the above line, the bordered style is invoked.

# Polygons appear first in the code, always.
poly 14 186 25 219 52 219 63 186 [http://www.wikipedia.org This link is polygon-shaped, and has an external link rather than an internal one.]
rect 107 32 256 182 [[Earth|This rectangle links to the Earth article.]]
circle 85 135 12 [[Circle|This area is a circle.]]

desc none
</imagemap>

=== Resources ===
The following are helpful tools related to ImageMap:

*For complex shapes and graphical editing, it is easiest to use [http://tools.wikimedia.de/~dapete/ImageMapEdit/ImageMapEdit.html?en the graphical ImageMap creator on the toolserver].
*For easy conversion of the {{[[Template:click|click]]}} template format to ImageMap, it is easy for [[Macintosh|Mac]] users to use [[User:Nihiltres/Click-to-ImageMap|Nihiltres' conversion tool]], which is written in [[AppleScript]]. With the advent of the #tag ParserFunction, which allows ImageMaps to receive template parameters and [[WP:MAGIC|magic words]], this isn't very important as {{[[Template:click|click]]}} is no longer a usability problem, but the script may still be useful, if rough.
*The {{[[Template:click|click]]}} template is a relatively easy way to use ImageMap in template form.
*For reference information about the ImageMap extension to MediaWiki, see [[mw:Extension:ImageMap|the extension's description page]].
*The Wikipedia article about [[image map]]s.


<noinclude>
{{Wikipedia:Wikipedia Signpost/Templates/Footer|{{BASEPAGENAME}}|2008-02-18|2008-03-13|{{SUBPAGENAME}}}}
</noinclude>
[[Category:Wikipedia Signpost archives 2008-03|03 Tutorial]]
{{Wikipedia:Wikipedia Signpost/Templates/Signpost-article-end-v2}}
<noinclude>{{Wikipedia:Signpost/Template:Signpost-article-comments-end|||}}</noinclude>