Skip to main content

Editor

Editor mounts Kaleidr's on-map editing tools inside your page: a Kaleidr basemap with tools for adding text, images, markers and popups and for restyling what is on the map.

Know the scope before you build on it

The embedded editor is an in-page tool whose work lives in the page's memory. Nothing is saved, exported or published from the embed, and your page gets no callback when something changes. When the page reloads or the editor is destroyed, the edits are gone. It is not a way to give your users a map-publishing workflow. For maps that are saved, shared and embedded, build them in Kaleidr Studio and show them with Viewer.

At a glance​

QuestionAnswer
What do I need?A publishable key (kld_pk_live_…) that carries the design scope. New keys carry it by default.
Which plan?Every plan, Free included.
How does it render?In your page, not in an iframe. The map and the editor's panels are elements in your document.
Where do edits go?Nowhere. They stay in the page's memory until the page reloads or the editor is destroyed.
Can my code read the edits?No. There is no change event, no export and no access to the map object.
How many per page?One.

The smallest mount​

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

The mount target needs a height. The editor fills it.

What the embedded editor includes​

The editor's rail has eight entries:

  • Text: headings and body text placed on the map.
  • Image: images placed on the map.
  • Marker: markers at a location.
  • Popup: popups attached to a location.
  • Background: the backdrop behind the map.
  • Layer: the basemap's own layers: labels, 3D buildings, light and terrain.
  • Design: select a basemap feature, a category of features or a region, and restyle it.
  • Legend: label and legend settings.

What it does not include​

These parts of Kaleidr Studio are not in the embed:

  • The Data tab: there is no dataset upload, so the parts of the editor that style uploaded data have nothing to work on.
  • Studio's design catalog of sample maps and style types.
  • The AI panel.
  • The 3D model library.
  • Share and publish.
  • Projects: there is no list of saved maps, no open and no save.
  • Sign-in. The embed runs on your key, not on a person's Kaleidr account.

How it works​

  1. The SDK exchanges your publishable key for a short-lived session. This checks the key, its design scope and your page's origin.
  2. At the same time, the SDK loads the editor bundle, editor.js, from https://cdn.kaleidr.com. It is several megabytes and loads only when an editor mounts. The editor starts when both have finished.
  3. The editor creates a map inside your mount target and loads the basemap from https://tile.kaleidr.com. Its requests for the style, sprites and fonts carry your publishable key, which is how the basemap host recognizes your page. The session token is never put in a URL.
  4. The editor's panels appear over the map, inside the mount target.

Because all of this runs in your page, your Content Security Policy has to allow more than it does for Viewer or Tile. The exact directives are in Content Security Policy.

What your page can do​

  • Choose the basemap with styleId, for example kaleidr-night.
  • Set the opening camera with center, zoom, pitch and bearing.
  • Move the camera later with handle.setCamera(...).
  • Match your brand with theme, an object of 17 named keys such as brandColor and fontPrimary.
  • Remove the editor with handle.destroy().

Limits​

  • Nothing is saved, exported or published, and there is no change callback.
  • The handle does not expose the map. You cannot add your own layers or read what the person drew.
  • The basemap and the theme are fixed at mount. To change either, destroy the editor and mount it again, which discards the edits.
  • One editor per page at a time.
  • Theme values are applied to the whole document while the editor is mounted, and are restored when it is destroyed.
  • There is no readiness or failure signal for your code. Failures appear in the browser console.

Where to go next​