The widget markup language

The double-brace markup that puts sliders, buttons, pickers and loaders inside a layer’s panel - every tag, the parameter grammar, how callbacks are resolved and what each widget’s value holds.

Mappia reference, section “Tools”. Page: https://mappia.earth/reference/markup-widgets/ Generated API entries: MarkupSyntax, Slider, Textfield, Combobox, Button, Checkbox, Label, Window, Timeline, PickPoint, Hoverpixel, SummedArea, AreaIntegral, InputManager, ZoomLevel, LoadCsv, LoadJson, FileField, LegendHtml, OpacitySlider, LiveComposedSplit, LayersProperties.descriptionHtml (https://mappia.earth/assets/api.json)

A layer’s descriptionHtml is free HTML with one addition: text in double braces becomes an interface element. This is the language of that markup - a small one, with its own parameter grammar, its own escaping and its own rules for finding the function a widget should call.

Widgets that collect a value also feed the layer’s calculation, which is what makes a Mappia map interactive: a slider moved by the user re-runs the arithmetic over the pixels. The full parameter list of every widget is in the API reference under Tools; this page is the language and the behaviour around it.

Use these tools inside a layer’s descriptionHtml. Parameters are pipe-separated:

HTML and multiple tools can be concatenated:

descriptionHtml:
  '<p>Intro</p>' +
  '' +
  '' +
  ''

Open the query panel with paramsButtonConfig: [{ type: 'query', pressed: true }] when the user must see the tools.

Input order: tools that act as inputs (slider, textfield, combobox, timeline, zoomlevel, pickpoint, hoverpixel, summedarea, areaintegral, loadcsv, loadjson, filefield, inputmanager, window) feed expression / beforeCalc / afterCalc as inputs[0], inputs[1], … in markup order. When they have an id they are also inputs.id[ID] — on the page only (beforeCalc, onInputsReady, afterCalc, functions): inside expression the inputs arrive as a JSON copy of the array, which drops the id map, so expression must use positions. button, checkbox, label, legendhtml, opacityslider, livecomposedsplit are not inputs.

Callback names (handler=, toggleHandler=, runOnClick=, runOnHover=, onMark=, onPlayToggle=, _onChange=, …) resolve in this order: (1) layer.functions[name] → (2) a global window[name] (from setQueryGlobalProperties) → (3) the text itself evaluated as a function (a full function(){…} or a bare statement body). this inside is the layer (exceptions per widget below). `` skips step 2. Prefer functions: { onRun: function() { … } } on the layer.

Catalog (all Mark.create tags)

Also allowed in descriptionHtml: raw HTML (not a `` tag).

Markup syntax (all tools) — api.json → Tools → MarkupSyntax

Input values — what inputs.id[ID] holds and what triggers a recalculation

From the <Widget>.value entries in api.json (read the entry for details):

Caveats worth repeating: LoadCsv.trim is a no-op; SummedArea.value is never filled; Hoverpixel never recalculates by itself (lastInfo is still always current); Timeline.onPlayToggle must return truthy (a bare statement body returns true).

How to choose a tool

Minimal patterns (copy / adapt)

Button + handler

{
  title: 'Demo',
  name: 'CSR:estados',
  source: 'calculate',
  visibility: true,
  paramsButtonConfig: [{ type: 'query', pressed: true }],
  descriptionHtml: '',
  functions: {
    onHi: function() {
      ExtjsUtils.ALERTIFY.log('hi');
    }
  }
}

Slider as expression input

{
  title: 'Threshold',
  name: 'CSR:altimetria',
  source: 'calculate',
  visibility: true,
  paramsButtonConfig: [{ type: 'query', pressed: true }],
  descriptionHtml: '',
  expression: function(layerVals, inputs) {
    var thr = inputs[0];
    return layerVals[0] > thr ? 1 : undefined;
  }
}

Combobox

data is a list of one-element arrays: each value is both what the list shows and what the input holds. A second element (["01", "Jan"]) is ignored - the store has a single value field.

Timeline

Pairs with composed / calculate layers that change styles per step. See api.json → Timeline (onPlayToggle, preloadTiles, …).

Pickpoint / hoverpixel

functions: {
  onPicked: function (evt) { /* evt.type 'add'|'remove', evt.features[layerIdx][i].data; this = the pickpoint checkbox, this.value = PointAttributeManager */ },
  onHoverValue: function (layerVals, inputs, coordinates, mouseEvt, lastCoordinates) { /* this = layer */ },
  onClickValue: function (layerVals, inputs, coordinates, clickEvt, lastCoordinates) { /* this = layer */ }
}

pickpoint recalculates the layer after every click (onmark); hoverpixel never does — use the callbacks (they receive the map values) or force a recalculation.

Checkbox (handler, not an input)

functions: {
  onToggleDetails: function (checkbox, checked) {
    this.getInputs().id["state"].setValues({ details: checked }); // recalculates the layer
  }
}

Area integral (two-click rectangle; needs maps published with the integral operation)

functions: {
  onAreaSummed: function (layersValues, inputs, boundingBox, pixel, lastInfo) {
    // boundingBox = [minLon, minLat, maxLon, maxLat] (EPSG:4326); lastInfo = {first:{lon,lat}, second:{lon,lat}}
    ExtjsUtils.ALERTIFY.log("Sum: " + layersValues[0]);
    Ext.getCmp("integral_tool").items.get(0).forceUpdateLayer(); // only if beforeCalc must see inputs.id["integral_tool"]
  }
}

summedarea is the free-polygon sibling: runOnClick(layersValues, inputs, feature); its inputs value is never filled.

Opacity + legend

Live composed split

Requires a calculated layer built from two styles of the same map (often the same name twice with two styles entries). The parameters are listed in the API reference under Tools -> LiveComposedSplit.

Window

File / CSV / JSON

With stable ids, the layer’s callbacks read inputs.id["tbl"] (a CSV table object), inputs.id["cfg"] (parsed JSON) and inputs.id["loadshp"]() (the selected file). When each of these becomes available, and why a layer waits for them, is described in the execution model.

Zoom level (hidden input)

inputs.id["z"] = current zoom (number); refreshed when the map stops moving, and it recalculates the layer only when the zoom actually changed.

Timeline with a play veto

functions: {
  onPlay: function (pressed, layer, timeline, playBtn) { return !window.stillLoading; } // falsy = veto
}

Authoring checklist

1. Put tools only in descriptionHtml (not as top-level QUERY keys).
2. Use the exact tag from the catalog (livecomposedsplit, not LiveComposedSplit).
3. Give interactive tools stable ids when other code or inputs must find them.
4. Wire handler / toggleHandler / runOnClick names to functions: { … } on the same layer (regular function, not arrows — this is the layer).
5. Remember input order for expression(layerVals, inputs), and that only plain data reaches expression.
6. For a side-by-side comparison use livecomposedsplit; there is no second split API.
7. Prefer api.json → Tools → <Name> when a parameter’s type/default is unclear; <Name>.value says what the input holds.
8. Panels with several widgets, the layer-row buttons (paramsButtonConfig) and page chrome belong to the layer and group model.
9. An unknown tag fails silently: the element is simply not created, and the console shows ` INVALID OBJECT NAME`.