8.2.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
- mapplic7.1.2-legacy.zip - old jQuery version of Mapplic

### The 'dist' folder #

To render the mall demo map, you need to publish and access the mapplic/dist folder using a web server, either live or local. This means that you cannot simply open the index.html file in a web browser directly from your computer. Instead, you will need to use a web server to serve the files, which will allow you to access them through a URL.

This folder contains everything that is needed to publish a map for production.

- assets - map files, images, spreadsheets and any other assets used
- data.json - data file that contains all the settings and details of the map
- index.html - index file that loads a map
- mapplic.css - plugin stylesheet
- mapplic.js - plugin javascript library

In order to add a map to an existing project:

1. Add mapplic.js and mapplic.css in the head section of your page:
   `<script type="module" src="./mapplic.js"></script>
   <link rel="stylesheet" href="./mapplic.css">`
2. Use the <mapplic-map> element anywhere in your page making sure that the data-json attribute is either a path to a map data.json file (relative to index.html) or a stringified JSON object.
   `<mapplic-map data-json="data.json"/>`

That's all! Your map should show up if you imported the two files (js and css) correctly.

If you're having issues, check the JavaScript console for any error message.

Using older versions of the plugin is still safe and upgrading is not necessary as long as the plugin functions as expected. However, when starting a new project, we highly recommend using version 8 or higher

The use of a web server is necessary due to security reasons. Browsers implement a security feature called Cross-Origin Resource Sharing (CORS) policy which restricts web pages from making requests to a different domain than the one that served the web page.

## Map builder#

Version 8 introduces the new map builder, which greatly simplifies map editing and makes it more user-friendly.

The builder can be accessed from mapplic-admin/dist folder served through a web server, either live or local.

- assets - map files, images, spreadsheets and any other assets
- data.json - data file of the Mall demo
- data-lots.json - data file of the Lots demo
- data-us.json - data file of the United States demo
- data-world.json - data file of the World demo
- index.html - index file of the builder
- mapplic-admin.css - builder + plugin stylesheet (bundled)
- mapplic-admin.js - builder + plugin javascript (bundled)
- save.js - a nodejs script for saving maps

Through the left side panel, you can begin to modify the map, but it cannot be saved yet as saving files requires a backend script with the capability to modify and save files.

For map saving to work, you need to have Node.js installed. Nagivate to this folder using a terminal and run the following command:

`node save.js`

If "Mapplic save script running." shows up, you can save your modifications with the map builder.

In order to load a different demo map, add the ?map=[TARGET-DATA].json parameter to your URL.
For example, if you're running the admin on http://localhost/mapplic-admin-test/, modifying the url to http://localhost/mapplic-admin-test/?map=data-us.json should load the United States map.

You can duplicate and rename any of these .json files to start a new map.

The Maps popup can also be used to switch maps or generate data file for built-in geograhpic maps. The save.js script must be running in order to generate new jsons.

Anyone with access to the map builder can modify the map so it should only be used on local environments or password protected pages. Never publish the builder on a page with public access!

### 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.2.1 - Oct 10, 2023

- Wayfinding BETA
- 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