MapNJ v0.2.0

Usage

Installation

MapNJ has several ways to use it.

Using via NPM

Use the following command:

        
$ npm install mapnj

Loading from CDN

When a partial version is specified, the latest patch version within that major and minor version will be automatically provided.
※ @0.2 => 0.2.0 

      
<script src="https://cdn.jsdelivr.net/npm/mapnj@0.2/dist/MapNJ.min.js"></script>

It's also possible to strictly specify the version. 

      
<script src="https://cdn.jsdelivr.net/npm/mapnj@0.2.0/dist/MapNJ.min.js"></script>

Downloading and using the source directly

Each version is available from GitHub Releases. ( GitHub Release )

Design Source Setup

To use MapNJ, you need to prepare an SVG (design source) in advance.
This guide introduces methods using Adobe Illustrator (Illustrator) and Figma for creating design sources.
These applications allow you to set unique IDs and data attributes to elements when exporting SVGs.
MapNJ reads these settings to manipulate designs and events.

I will explain the creation of design materials in 3 STEPS.

Watching the demo makes it easier to understand the creation process. ( Demo )

STEP1. Creating SVG illustrations

Create vector data for the entire map. Divide the map into areas.

Use the color scheme of all areas that are selected (active).

Although not required, create label elements as well.

Define lines for the areas (and labels) if necessary.

Finally, outline all the elements and convert them into vector data.

※ MapNJ is a script that manages the active and inactive states of map illustrations. During the design phase, all areas are created in an active state, and the design for the inactive state is defined using JavaScript.

※ When using lines in Illustrator, always select "Center" for the stroke alignment. If you choose "Inside" or "Outside," it will result in an unintended output, treating the element as having two different fill colors.

STEP2. Naming design nodes

In the design app's layer panel, name each part according to the following rules:

mapnj-[typeName]-[AreaId]-[freeText]
  • ※ Use alphanumeric characters for naming.
  • ※ Currently, only "area" and "label" are recognized as "type name".
  • ※ Assign the same "AreaId" to both the area and the label you want to link together.
  • ※ "Free text" is usually not necessary to use; it is a reserved area.

Area

Role: Activates when clicked. Additionally, it deactivates other areas.

Naming Example : mapnj-area-osaka

Label

Role: Activates the area specified by the ID when clicked. Additionally, it deactivates other areas.

Naming Example : mapnj-label-osaka

※ If multiple elements are grouped together, name the group node.

STEP3-1. Exporting SVG with Illustrator

  • Select "File > Export > Export for Screens..." from the menu
  • In the SVG export settings screen, set the file format to "SVG"
  • Check "Use Artboard" if you want to export based on artboards (optional)
  • Click "Export"
  • Set the style to "Internal CSS"
  • Set the font to "SVG"
  • [IMPORTANT] For "Object ID": Set to "Layer Names" if you want to output information to the ID attribute. / Set to "Unique" (or "Minimal") if you want to output to the data-name attribute. ※1
  • Export the file.

※1 Since the value of the id attribute must be unique within a document, using the data-name attribute is always a good approach. If there is a possibility of node names being duplicated, actively use the data-name attribute (or "free text").
When using the data-name attribute, it is necessary to also use the attributeType option. ( attributeType )

STEP3-2. Exporting SVG with Figma

  • Select "SVG" from the Export settings
  • Open the advanced settings screen
  • Select "Ignore Overlapping Layers" (optional) ※1
  • Select "Include id attribute" ※2
  • Export the file.

※1 If you don't check this option, an additional rect element with the color of the upper frame will be output.

※2 If you don't check this, text information won't be output. When output, it will be as an id attribute.

Code Preparation

Open the created svg design file directly in a code editor and place it.

If there is an <?xml...?> tag output on the first line, delete it.

Also, wrap the SVG tag in any tag you give it an ID (or class).

      
<div id="your-mapnj">
  <svg>
    <defs>
      <style></style>
    </defs>

    <!-- 通常ノードへマッピングした場合の出力例 -->
    <!-- ※ 注意: Illustratorの設定次第ではidではなくdata-nameにマッピングされています -->
    <path id="mapnj-area-xxx" d="" />
    <path id="mapnj-label-xxx" d="" />

    <!-- グループ化した要素にマッピングした場合の出力例 -->
    <!-- ※ 注意: Illustratorの設定次第ではidではなくdata-nameにマッピングされています -->
    <g id="mapnj-area-xxx"><path d="" /><path d="" /></g>
    <g id="mapnj-label-xxx"><path d="" /><path d="" /></g>
  <svg>
</div>

When using a Node module, import MapNJ.
Instantiate it by passing the selector of the element wrapping the SVG as an argument. 

        
import MapNJ from 'mapnj';

const mapnj = new MapNJ('#your-mapnj');

The same applies when using the pre-built file directly.

        
<script src="path/to/MapNJ.js"></script>
<script>
  const mapnj = new MapNJ('#your-mapnj');
</script>

The constructor of MapNJ accepts a CSS selector string or an Element object as its first argument. The constructor determines the type of the argument and processes it accordingly, so you can instantiate it using either of the following methods. 

        
new MapNJ('.foo'); 
new MapNJ(document.querySelector('.foo'));