6d7da1c0f7
Four path lines said public/doxa-maps/ (the folder was renamed in 09014f8a), and the embed
example used a <doxa-map> tag, but a bundle registers the tag named after its folder
(template-bundle/index.js), so the example is <your-map>.
106 lines
5.4 KiB
Markdown
106 lines
5.4 KiB
Markdown
# plugin-designs/ — where YOUR maps live
|
|
|
|
The shared template lives in `../library/` (aliased `@map`) — you never edit it per-map.
|
|
You build your map by making a folder **here**, `plugin-designs/<your-map>/`, and composing the
|
|
template's building blocks. Your folder is yours (colors, API, i18n); the template is shared
|
|
(Apache-2.0, propagated to every map on the next build).
|
|
|
|
## Shared vs. yours — the balance
|
|
|
|
```
|
|
library/ (@map) ── SHARED, reusable, parameterized ──► legend · map · map-controls
|
|
│ (every map reuses these)
|
|
│ imported by
|
|
▼
|
|
plugin-designs/<your-map>/ ── YOURS ──► the map's "main" class (the .vue profile = the Vue
|
|
│ instance for that map)
|
|
└── src/ ── YOURS ──► this map's OWN non-reusable components, colors, API, utils
|
|
|
|
One bundle can hold as many maps as you want — add another .vue profile and rebuild.
|
|
```
|
|
|
|
- **Reusable → `library/`.** The legend, the map, the map-controls are shared, parameterized
|
|
components every map reuses. Fix once, every map benefits. Never edit it to customize one map.
|
|
- **This map's own → `plugin-designs/<your-map>/`.** It holds two things: the map's **"main" class**
|
|
(each `.vue` profile *is* the Vue instance for that map) **and** that map's **own non-reusable
|
|
components** (in `src/`). Nothing here leaks to another map.
|
|
- **Many maps per bundle.** The bundler bundles one map or many — add another flat `.vue` and rebuild.
|
|
|
|
## Production or experimental — every profile declares itself
|
|
|
|
Every app profile is one of two things, and **experimental profiles are unlimited and
|
|
encouraged** — create as many as you need:
|
|
|
|
- **Experimental, not built:** prefix the folder with `_` — the build skips it; it just sits
|
|
in code. Zero cost, zero risk.
|
|
- **Experimental, built:** builds normally, but it belongs in the **Experimental section** of
|
|
the power app's layout (nav section) — never embedded on partner surfaces.
|
|
- **Production:** a real product — main sections of the power app + individually embeddable.
|
|
|
|
(The **power app** = the SPA layout that composes all profiles into one application.)
|
|
|
|
## The pattern in one picture
|
|
|
|
```
|
|
plugin-designs/<your-map>/ ← one FOLDER = one BUNDLE, named after the folder
|
|
├── index.js ← entry: registers the custom element, finds the profiles
|
|
├── overview.vue ← one .vue = one PROFILE (flat in the folder — no profiles/ subfolder)
|
|
└── detail.vue ← another profile in the SAME bundle
|
|
|
|
builds to ─────────────► public/dx-maps/<your-map>/<your-map>.js (one file)
|
|
```
|
|
|
|
- **Folder name = bundle name.** Folders starting with `_` or `.` are skipped (handy for WIP).
|
|
- **Each `.vue` = one profile** (one map screen). One bundle can hold many.
|
|
- **Pick the profile at embed time** with the `profile` field — every profile shares one bundle:
|
|
|
|
```html
|
|
<script src="/dx-maps/<your-map>/<your-map>.js"></script>
|
|
<your-map profile-config='{"profile":"overview","tk":"pk.eyJ..."}'></your-map>
|
|
<your-map profile-config='{"profile":"detail","tk":"pk.eyJ..."}'></your-map>
|
|
```
|
|
|
|
## Add a map — three steps
|
|
|
|
```bash
|
|
# 1. create the folder + one profile
|
|
mkdir -p plugin-designs/<your-map>
|
|
# index.js ← copy doxa-simple-map/index.js, rename the tag
|
|
# <name>.vue ← your screen, built from @map/* blocks (flat in the folder)
|
|
|
|
# 2. build
|
|
npm run build # → public/dx-maps/<your-map>/<your-map>.js
|
|
# (just this one: BUNDLE=<your-map> npm run build:bundle)
|
|
|
|
# 3. embed the script tag + element (dev staging at `npm run dev` shows a paste-ready snippet)
|
|
```
|
|
|
|
## Your three things (everything else is shared)
|
|
|
|
- **Colors** — how pins are colored. Pick one the template ships (`getColorStrategy('language-family')`),
|
|
or drop your own in `plugin-designs/<your-map>/src/colors/` (start from
|
|
`template-bundle/src/colors/example-mode.js`). Never edit `@map/colors/` to recolor your map.
|
|
- **API** — your map reads its data from the `profile-config` on the page, so the same bundle points
|
|
at different data with no rebuild. `DataSourceManager` accepts `csv` (bundled file), `api` (one JSON
|
|
URL), or `rest-api` (a live REST endpoint, the default). Prefer the real API over inlined JSON.
|
|
- **i18n** — the template ships 11 base locales in `@map/i18n/locales/`. Use `useI18n()` for strings
|
|
and `RTL_LOCALES` for right-to-left; add or override strings from your own profile.
|
|
|
|
## The one hosting variable
|
|
|
|
The only thing that changes between hosting modes is the `<script src>`: a **relative** path when
|
|
your own site serves the file, or an **absolute CDN URL** when a partner site serves it. The bundle
|
|
is identical either way. See `../documentation/CONTRIBUTING.md` for the two CDN modes and partner-site embedding.
|
|
|
|
## Profile patterns (mix freely)
|
|
|
|
- **Individual** — one `.vue` per bundle (simplest).
|
|
- **Parameterized** — one profile, behavior driven by `profile-config` props (e.g. `tabs[]`).
|
|
- **Nested** — one profile that renders others (workbench-style, like `doxa-research-map`).
|
|
|
|
## See also
|
|
|
|
- `doxa-simple-map/index.js` — fully commented reference bundle entry
|
|
- `template-bundle/` — minimal two-profile skeleton to copy
|
|
- `../library/colors/README.md` — the color-strategy contract
|
|
- `../README.md` — repo overview & build pipeline · `../documentation/CONTRIBUTING.md` — build vs dev, CDN modes
|