8.4.1

# Documentation

Mapplic is a custom map plugin that empowers users to create fully interactive maps from static vector (SVG) or image (PNG, JPG) files. With its impressive list of features including a filterable directory, CSV support and many more, it is a versatile tool that can help users achieve their mapping goals easier than ever. Featuring a real-time map builder, version 8 represents a complete overhaul of Mapplic using the latest technologies.

## Getting started#

The structure of the download package is as follows:

- docs - this documentation in HTML format
- mapplic - main project library
  - dist - main distribution
  - public
  - src
  - index.html
  - package.json
- mapplic-admin - map builder project library
  - dist - map builder distribution
  - public
  - src
  - index.html
  - package.json
- mapplic-wp.zip - installable WordPress plugin

### Istallation

The WordPress plugin can be installed by uploading the mapplic-wp.zip at Plugins > Add New Plugin > Upload Plugin, or unpacking its' content to your wp-content/plugins/ folder.

### Update

In order to update the plugin, simply deactivate and delete the old version and upload the new mapplic-wp.zip install downloaded from CodeCanyon.

Version 8's complete rewrite means that updating from 7.x or earlier to 8.x will result in map changes, potentially necessitating manual adjustments.

## Map builder#

The map builder can be accessed by navigating to the Maps menu on your WordPress backend.

### Layers #

The most basic building block of a map is the layer. At least one layer is required, but you can define multiple layers, which is useful for multi-level maps (like a building with multiple floors).

Layer attributes

- ID - required and must be unique
- NAME - display name of the layer
- FILE - required, path to the map file (svg, png or jpg)
- STYLE - optional style assigned to svg layers only

You can select which layer to display by default.

The width and height (in pixels) of your map file must be defined manually. If the dimensions are not set, the map will not render. If the dimensions are incorrect, the locations will render on the wrong position.

Maps (in web mercator projection) can be geocalibrated by setting the map extent. Geocalibrating a map is an advanced task and requires GIS skills.

### Locations #

Locations can be customized using a list of attributes.

- ID - unique ID (required). Starts with a letter and no space or special characters allowed
- TITLE - title of the location displayed in popups and directory
- ABOUT - short description of the location displayed in popups and directory
- DESC - HTML enabled description text displayed in popups
- LAYER - ID of the layer the location belongs to. If left blank and there is no matching vector feature available, the global markers layer will be used
- COORD - comma separeted x and y coordinate of location
- ZOOM - focus zoom level of location. If left blank, the global Max zoom will be used
- TYPE - type of the marker
- COLOR - hex color used for marker and popup styling
- LABEL - short text in the marker
- ACTION - action to perform when a location is focused
- LINK - URL used for redirects or popup buttons
- STYLE - predefined style used for complex marker and popup styling. Overwrites standard COLOR attribute
- IMAGE - image displayed in popups
- THUMB - thumbnail displayed in directory or as marker if "thumbnail" type is used
- GROUP - group(s) the location belongs to
- SAMPLE - location to use as sample
- HIDE - hide location from directory
- DISABLE - disable location

Locations can inherit attributes from another location set as SAMPLE. Default location values can also be set.

Locations can be imported from and exported as CSV. Export your locations to see the correct structure of a Mapplic compatible CSV file.

### Directory #

The advanced directory mode can be accessed starting from version 8.1 or later. It allows for the listing of various types of locations (in either list or grid format) in both landscape mode (with a sidebar) and portrait mode. The number of columns can be adjusted to suit preferences. By utilizing screen breakpoints from the Settings panel, different layouts can be achieved.

### Settings #

You can fine tune your map with a list of settings available on the Settings panel. Changes are applied immediately.

- Fullscreen
- Hover tooltip
- Deeplinking
- Padding
- Accessibility
- Responsivity
  - Below (px)
  - Portrait (on/off)
  - Sidebar width (px) - landscape mode
  - Type (List/Grid)
  - Column count (number)
  - Container height (px)
  - Element height (px) - portrait mode
- Zoom and pan
  - Max zoom
  - Reset button
  - Zoom buttons
- Translations
  - More button
  - Search
  - Clear all

### Appearance #

You can define reusable location styles which are added as CSS classes to a marker or an svg element. Styles can control the background and stroke colors of base, hover and active states as well as stroke width and text color.

If a style is assigned to a location, it will overwrite its color attribute.

The map's primary color can be customized to match your website's design.

Use the Custom CSS field for advanced styling.

## SVG map#

You can make certain parts of an SVG file interactive, such as a region of a geographic map or a room of a building. This feature is only available when using SVG as base map (PNG and JPG based maps can only have location markers).

Groups that begin with the name MLOC- are detected by Mapplic, and their named child elements are considered interactive elements.

- MLOC-units
  - u01
  - u02
  - u03

Using the above structure, there will be 3 interactive elements and you can link a location to any of those elements by setting the location ID to u01, u02 or u03. Please ensure that location IDs always start with a letter and not a number or a special character.

Keeping your SVG map files clean and lightweight is crucial to ensure optimal performance. Overly large files can negatively impact the performance of the map.

## Credits#

Version 8 of Mapplic was completely rebuilt using React, the most widely used JavaScript library. It is packaged in a way that makes it compatible with any website.

- React - JavaScript library
- Vite - build tool
- Framer Motion - animations
- Papa Parse - CSV parsing
- Feather - icon set
- and many other awesome tools

## Changelog#

### 8.4.1 - Apr 9, 2024

- samples reworked
- fixes and improvements

### 8.4.0 - Feb 27, 2024

- WordPress version
- Legend feature
- fixes and improvements

### 8.2.1 - Oct 10, 2023

- improved performance
- small fixes

### 8.1.0 - June 23, 2023

- DIRECTORY feature
- screen breakpoints
- built-in code editor
- improved admin UI
- string translations
- other fixes and improvements

### 8.0.2 - March 21, 2023

- minor bug fixes

### 8.0.0 - March 18, 2023

- rewrite in React