1# dokuwiki-plugin-imapmarkers
2
3This software is a plugin for [DokuWiki](https://www.dokuwiki.org/).
4You can make image maps with markers and links.
5
6It is inspired by [dokuwiki-plugin-imagemap](https://github.com/i-net-software/dokuwiki-plugin-imagemap/), whose author, Gerry Weißbach, suggested me to write an own plugin for my purposes.
7This plugin is a superset of the *dokuwiki-plugin-imagemap* plugin, simply use no references and omit area-identifiers.
8
9__*An interactive example can be found here*__: [http://insitu.w4f.eu/doku.php?id=imapmarkers:interactive-example](http://insitu.w4f.eu/doku.php?id=imapmarkers:interactive-example)
10
11This is a non-interactive sample of such a map:
12![Acient World Map with Marker](readme/map-with-marker.png)
13
14Sourcecode in DokuWiki:
15```
16{{imapmarkers>https://upload.wikimedia.org/wikipedia/commons/f/fd/1744_Bowen_Map_of_the_World_in_Hemispheres_-_Geographicus_-_World-bowen-1744.jpg|Bowen Map of the World, 1744}}
17[[https://en.wikipedia.org/wiki/Asia|CON1|Asia @ 2775,804,30]]
18[[https://en.wikipedia.org/wiki/Africa|CON2|Africa @ 2145,966,30]]
19[[https://en.wikipedia.org/wiki/North_America|CON3|North America @ 1005,846,30]]
20[[https://en.wikipedia.org/wiki/South_America|CON4|South America @ 1368,1290,30]]
21[[https://en.wikipedia.org/wiki/Antarctica|CON5|Antarctica @ 947,2031,30]]
22[[https://en.wikipedia.org/wiki/Europe|CON6|Europe @ 2370,669,30]]
23[[wp>Australia|CON7|Australia @ 3138,1404,30]]
24{{cfg>}}
25  {
26    "marker" : "internal",
27    "marker-color": "red",
28    "clicked-reference-css": { "font-weight": "bold", "color": "red" },
29    "area-fillColor": "ff0000",
30    "area-fillOpacity": 0.2
31  }
32{{<cfg}}
33{{<imapmarkers}}
34
35{{imapmloc>CON1|Asia}} |
36{{imapmloc>CON2|Africa}} |
37{{imapmloc>CON3|North America}} |
38{{imapmloc>CON4|South America}} |
39{{imapmloc>CON5|Antarctica}} |
40{{imapmloc>CON6|Europe}} |
41{{imapmloc>CON7|Australia}}
42```
43
44## Usage and Syntax
45
46### Create a Map with Areas
47
48You start with ```{{imapmarkers>IMAGE-LINK|TITLE}}``` and end with ```{{<imapmarkers}}```.
49
50```IMAGE-LINK``` is a normal DokuWiki image link, [see here](https://www.dokuwiki.org/images), this may be an DokuWiki-internal or external address (https://…).
51
52```TITLE``` is the title for your image, technically the ```alt="TITLE"``` attribute of the ```img``` element.
53
54Enclosed in this, you define no, one or multiple image areas, [see here](https://www.w3schools.com/html/html_images_imagemap.asp), with this special area definition:
55
56**Area with identifier**: ```[[LINK|IDENTIFIER|TITLE@COORDINATES]]```
57
58**Area without identifier**: ```[[LINK|TITLE@COORDINATES]]```
59
60```LINK``` is an ordinary [DokuWiki-link](https://www.dokuwiki.org/link).
61This may be an external, internal or interwiki link.
62If the area or marker is clicked, this link is opened.
63If the identifier is blank or omited and you click the area, the area is shown until you click it again.
64
65```IDENTIFIER``` is a page-unique identifier for this area.
66This identifier is later used in a clickable element, say **reference**, to show the marker.
67If the identifier is blank or omited you can't refer to it.
68Identifiers are case sensitive.
69
70```TITLE``` is the title of the area.
71If you hover over the area, this title is shown.
72
73```COORDINATES``` are the areas location on the image. Coordinates can have 3 integer values (circle), 4 integer values (rectangle) or 6 or more integer values (polygon). If you define a polygon the number of values must be divisible by 2.
74Details: [see here](https://www.w3schools.com/html/html_images_imagemap.asp).
75
76**Circle**: X,Y,RADIUS
77
78**Rectangle**: LEFT,TOP,RIGHT,BOTTOM
79
80**Polygon**: X1,Y1,X2,Y2,X3,Y3 (and so on …)
81
82All coordinates you enter here are from your original image.
83
84### Configuration
85
86A configuration is inside the map definition and starts with ```{{cfg>}}``` and ends with ```{{<cfg}}```
87
88Between this you define a [JSON](https://www.json.org/json-en.html) object.
89This plugin tests, if it is correct JSON.
90
91There are these configuration options:
92
93**"marker"**: (string) ```"internal"``` -- Use the plugins-internal marker. This is the default, so no need to write this, if you are happy with the internal marker.
94
95**"marker"**: (string) ```"LINK"``` -- Internal or external link to an image.
96
97Example: ```"marker": "imapmarkers:marker.002.png"```
98
99Example: ```"marker": "https://upload.wikimedia.org/wikipedia/commons/f/f2/678111-map-marker-512.png"```
100
101**"marker-width"**: (positive number) -- Set the markers width to this value.
102
103Example: ```"marker-width": 20```
104
105**"marker-height"**: (positive number) -- Set the markers height to this value.
106
107Example: ```"marker-height": 32```
108
109**"marker-color"**: (string) ```"HTML-COLOR"``` -- Set the internal markers color to this value.
110
111Example: ```"marker-color": "#FDEB00"```
112
113**"clicked-reference-css"**: (JSON) ```JSON-OBJECT-WITH-CSS-DEFINITIONS```  -- The CSS definitions are applied to a reference, if you click the reference.
114
115Example: ```"clicked-reference-css": { "font-weight": "bold", "color": "red" }```
116
117**"area-fillColor"**: (string) "HTML-COLOR-HEXADECIMAL" -- Set the color of the hoverd area. Don't use a `#' before the hex-code.
118
119Example: ```"area-fillColor": "ff0000"```
120
121**"area-fillOpacity"**: (float) ```OPACITY-PERCENT``` -- Set the opacity of the hovered area.
122The value must between 0 and 1.
123```1``` is full opacity.
124```0``` is no opacity, i.e. the hovered area is not shown.
125
126Example: ```"area-fillOpacity": 0.3```
127
128Complete Configuration-Example (Place this **inside** your map definition!):
129
130```
131{{cfg>}}
132  {
133    "marker-color": "red",
134    "clicked-reference-css": { "font-weight": "bold", "color": "red" },
135    "area-fillColor": "ff0000",
136    "area-fillOpacity": 0.2
137  }
138{{<cfg}}
139```
140
141### Create References
142
143References are spans, i.e. a piece of inline text.
144And if you click a reference, the marker is shown in the middle of the **area** with the same **identifier**.
145
146References can be places everywhere in the page.
147
148**Reference**: ```{{imapmloc>IDENTIFIER|TEXT}}```
149
150```IDENTIFIER``` refers to the **areas** identifier.
151You may define multiple references for one identifier.
152
153```TEXT``` is the text shown in the page.
154
155Example: ```{{imapmloc>CON1|Asia}}``` -- Refers to the area with ```CON1``` as identifier.
156
157## Installation
158
159Install the plugin using the [Plugin Manager](https://www.dokuwiki.org/plugin:extension) or the download URL above, which points to latest version of the plugin.
160
161
162### Manual Installation
163
164Download: [https://github.com/kgitthoene/dokuwiki-plugin-imapmarkers/zipball/master/](https://github.com/kgitthoene/dokuwiki-plugin-imapmarkers/zipball/master/)
165
166Extract the zip file and rename the extracted folder to ```imapmarkers```.
167Place this folder in ```DOKUWIKI-SERVER-ROOT/lib/plugins/```
168
169Please refer to [http://www.dokuwiki.org/extensions](http://www.dokuwiki.org/extensions) for additional info
170on how to install extensions in DokuWiki.
171
172## Used Software and Attribution
173
174This plugin is based on [dokuwiki-plugin-imagemap](https://github.com/i-net-software/dokuwiki-plugin-imagemap/), [ImageMapster](http://www.outsharked.com/imagemapster/) and [PHP Simple HTML DOM Parser](https://sourceforge.net/projects/simplehtmldom/).
175
176## License
177
178[MIT](https://github.com/kgitthoene/dokuwiki-plugin-imapmarkers/blob/master/LICENSE.md)
179