Image Marker widget: expand documentation with layers, geofence data formats, pin positioning and mention indoor tracking

[Freddyminu]

Summary

• Clarifies that the Image Marker widget is the standard choice for indoor device tracking, where GPS is unavailable and device positions are defined relative to a custom image
• Rewrites the page to cover all major configuration areas: Data From field, layer variable, geofence variable, Basic vs Advanced mode differences, and the pin position editor
• Documents the full fixed_position key format for both Basic mode (device ID only) and Advanced mode (device ID + group ID)
• Adds complete JSON examples for the layer variable and for both circle and polygon geofences, including all metadata fields
• Clarifies the 30-device limit in Basic mode and how Advanced mode with groups bypasses it
• Adds .mcp.json to .gitignore

Closes #66

[vitorfdl]

PR Review: image-marker.md — Image Marker Widget Documentation

Overall Assessment

Good foundational structure and technically thorough. The doc covers the key concepts well but has several areas where it can better serve the reader — especially around information ordering, technical density, tone alignment with TagoIO voice, and cross-linking.

---

1. Communication Guidelines Alignment

✅ What's working

• Direct, second-person address ("you need," "you can").
• Avoids hype and marketing superlatives.
• Uses action verbs ("place," "connect," "configure").

⚠️ What needs adjustment

Line 1 — Opening paragraph tone:

"The Image Marker widget lets you place pins on any image…"

This is fine but slightly passive. Consider front-loading the outcome more clearly per TagoIO's "Useful + Direct" documentation tone:

The Image Marker widget places pins on custom images — floor plans, building maps, facility diagrams — and connects each pin to live or historical device data. It's the standard choice for **indoor device tracking**, where GPS isn't available and positions are defined relative to an image.

Section 2 table — "Description" column is too dense:

The table descriptions for Basic and Advanced modes read like run-on paragraphs inside cells. This hurts scannability. Consider breaking these into shorter sentences or moving the detail outside the table.

---

2. Formatting and Information Ordering

🔴 The prerequisites should come before configuration steps

Currently the doc opens with the "you need at least two things" list, immediately followed by a reference to an optional geofence variable. This is good. But then "Creating your own" jumps straight into configuration fields without a brief orientation of what the widget looks like when fully set up or what the workflow is.

Suggestion: Add a brief workflow overview between the intro and the detailed sections:

## How it works

1. Add the Image Marker widget to a dashboard.
2. Configure the **Data From** field with your pin data variables.
3. Set a **layer variable** to store the floor plan image and pin positions.
4. Use the **editor** to visually place pins on the image.
5. Optionally, draw geofences to define zones.

This gives the reader a mental map before diving into details.

🔴 Section 3 ("Positioning Pins") should come after Section 4 ("Layer")

Section 3 references the layer variable format and says "see Layer for the full format," which means the reader encounters a forward reference before the concept is explained. Swap these, or merge "Positioning Pins" as a subsection of "Layer."

🟡 Section 6, 7, 8 feel like an appendix

Infobox, Filters, and Geofence are optional features. They're fine as later sections, but consider grouping them under a shared heading like ## Additional features to signal they're not part of core setup.

---

3. Ease of Understanding

🔴 The fixed_position key format explanation is confusing

"Each key in fixed_position is the device ID concatenated with the group ID of the variable assigned to that pin."

The word "concatenated" without a separator is ambiguous. The reader doesn't know if there's a delimiter. The JSON examples show <device-id><group-id> — but are these literally joined as one string? This should be explicit:

The key is the device ID immediately followed by the group ID, with no separator. 
For example, if the device ID is `abc123` and the group is `xyz789`, the key is `abc123xyz789`.

🟡 Coordinate system needs a visual hint

"These are relative coordinates where (0, 0) is the top-left corner of the image and (1, 1) is the bottom-right corner."

This is correct but could benefit from a small inline diagram or at minimum a note like:

> Think of it as percentages: `x: 0.5` means the pin is at 50% of the image width.

🟡 The blockquote tip in Section 1 is doing too much

"If you need more than 30 pins, use Advanced mode with a single device that accumulates the last known position of each tracked device as separate groups."

This bundles a limit, a workaround, and a concept (groups) into one sentence. Break it up:

> **Limit:** The Data From field supports up to 30 devices.
>
> **Workaround:** To display more than 30 pins, use Advanced mode. Configure a single device that stores each tracked device's position as a separate [group](/docs/tagoio/devices/grouping-variables). Each group becomes its own pin.

---

4. Unnecessary or Excessive Technical Information

🟡 Full JSON payloads for layers — consider collapsing or trimming

The two full JSON blocks in Section 4 (Basic and Advanced mode) include fields like created_at, time, and id that are system-generated and not actionable for configuration. The reader mostly needs to understand fixed_position and metadata.file.

Suggestion: Show a trimmed version focusing on the fields the user controls, with a note:

> The full payload includes system fields (`id`, `time`, `created_at`). The fields you configure are shown below.

Then show only metadata content. Keep the full payload in a collapsible <details> block or link to an API reference.

🟡 Geofence JSON — same issue

The circle and polygon JSON examples include every field. Consider highlighting only the metadata structure that differs between types and collapsing the rest.

✅ The events variable JSON in Section 8 is appropriately brief — good.

---

5. Missing Cross-Links

The following terms are used without linking to their documentation. Based on the existing TagoIO docs, here are the links to add:

Term / Concept	Where it appears	Suggested link
Blueprint Dashboards	Section 1 (Data From)	Blueprint Dashboard
Blueprint device	Section 1 (Data From)	Blueprint Devices & Entities
Metadata	Section 4 (JSON), Section 6 (Infobox)	Metadata
Formula	Section 6 (Infobox)	Formula
Groups / Grouping Variables	Multiple sections (already partially linked, but verify)	Grouping Variables
Geofence actions/triggers	Section 8 (events concept)	Trigger by Geofence (Actions)
Map widget geofences	Section 8 (related concept)	Geofences in Map Widgets
Dashboards	Opening / Section 1	Dashboards overview
Widgets overview	"Creating your own"	Widgets

The existing internal link [groups](/docs/tagoio/devices/grouping-variables.md) uses a .md extension — verify this resolves correctly in the docs build system. The canonical URLs in other docs don't include .md.

---

6. Specific Line-Level Comments

Location	Issue	Suggestion
Title metadata description	Too long for SEO meta description (>160 chars).	Trim to: "Place pins on floor plans, track indoor devices, and configure layers and geofences with the Image Marker widget."
Section 2 heading	"Image Marker Behavior Modes" is vague.	→ "Pin Assignment Modes" or "Basic vs. Advanced Mode"
Section 5	"Changes only take effect after clicking Save"	Good — but move this warning to the top of the section as a callout/admonition, not buried in the paragraph.
Section 6	"Embedded widget — embed a secondary widget inside the infobox."	Which widget types are supported? Even a brief "any dashboard widget" or a constraint would help.
Section 8	"You must configure at least one event in the widget settings."	Clarify where in settings. Is it the "Geofence Options" tab? Other widget docs (Map) reference this tab explicitly.
Section 8	"eventColor": "" in examples	If the field is empty string by default, briefly note that users can set a hex color here. Otherwise readers may wonder if it's required.

---

7. Summary of Recommended Changes (Priority Order)

1. Reorder sections — Move "Layer" (§4) before "Positioning Pins" (§3), or merge them.
2. Add workflow overview — Brief numbered list after the intro showing the end-to-end setup flow.
3. Trim JSON examples — Focus on user-controlled fields; collapse full payloads.
4. Add missing cross-links — Blueprint, Metadata, Formula, Geofence Actions (see table above).
5. Clarify concatenation format — Add a concrete example of the fixed_position key.
6. Break up dense blockquotes — Especially the 30-pin limit tip.
7. Rename Section 2 — Make the heading self-explanatory.
8. Fix .md extension in links — Align with canonical URL format used across the docs.

---

Let me know if you'd like me to produce a rewritten version of any specific section based on these notes.