Checkbox

Quick start

The example below, running in the Mappia calculator - click it to run it live. Full-size picture

Run it
Click the picture: the map opens right here and runs the example. Nothing is saved, and nothing to install.
Try it
- Turn the switch off: after the countdown, the soils below 50 Mg/ha appear in yellow beside the brown carbon-rich ones.
- Turn it back on: only the brown soils above 50 Mg/ha remain.
Make it yours
Copy the query, change it - the key parameters are below - and run it again in the playground, or paste it into the Mappia editor to save it as your map.
More ways to use it
- Several switches, one filter

Key parameters

Parameter	Example	What it does
`handler`	`onToggle`	Function run on every change as `handler(checkbox, checked)`, with `this` = the layer. Looked up in `functions` first.
`checked`	`true`	Starts the switch on. The handler does not run for this starting state.
`text`	`Only soils above 50 Mg/ha`	Text shown next to the switch. Change it later with `setBoxLabel`.
`id`	`only_rich`	Lets your code find the switch: `Ext.getCmp('only_rich')`.
`toggle`	`Ext.getCmp('only_rich').toggle(false)`	Turns the switch on or off from code and runs the handler, as a click would. Without an argument it flips.

Every parameter, with its type and default, is in the reference at the end of this page.

Complete example

The query 37 lines · runs as is

// Checkbox: not an input itself. Its handler stores the state in an inputmanager, whose
// plain "global" values are what reach expression() (inputs[0] - checkboxes take no position).
[
  {
    title: "Carbon-rich soils switch",
    name: "CSR:soil_organic_carbon_stock",
    source: "calculate",
    opacity: 0.85,
    visibility: true,
    paramsButtonConfig: [{ type: "query", pressed: true }],
    descriptionHtml:
      "{{checkbox|id=only_rich|text=Only soils above 50 Mg/ha|checked=true|hideLabel=true|handler=onToggle}}" +
      "{{inputmanager|id=state}}",
    functions: {
      // this = the layer; called with the checkbox and its new state
      onToggle: function (checkbox, checked) {
        this.getInputs().id["state"].setValues({ onlyRich: checked }); // recalculates
      },
    },
    onInputsReady: function (inputs) {
      inputs.id["state"].setDefaultValues({ onlyRich: true });
    },
    // The legend shows what the map shows - and changing it is what redraws the map: a change of
    // the inputs that leaves the legend as it was does not. The class always shown is value 1, the
    // optional one comes after it (legend values in ascending order).
    beforeCalc: function (inputs) {
      var legend = [{ color: [121, 85, 72], value: 1, title: "Above 50 Mg/ha" }];
      if (!inputs.id["state"].global.onlyRich) legend.push({ color: [241, 196, 15], value: 2, title: "Below 50 Mg/ha" });
      this.setCalculateLegend(legend);
    },
    expression: function (layersVals, inputs) {
      var onlyRich = inputs[0].global.onlyRich;
      if (layersVals[0] >= 50) return 1;
      return onlyRich ? this.nullValue : 2;
    },
  },
];

More examples

Other ways to use Checkbox, each a complete query that runs as is - like the one above.

Each checkbox turns one class of the map on or off - here dry, moderate and wet places by annual rainfall.

Click the picture to run it live. Full-size picture

Edit it in the playground

The query 47 lines · runs as is

// Several switches, one filter: each checkbox turns one class of the map on or off - here dry, moderate and wet places by annual rainfall.
// Checkboxes are not inputs: one handler writes the state of the checkbox it is called for into an
// inputmanager (setValues merges keys and recalculates), and expression reads the three states.
[
  {
    title: "Rainfall classes",
    name: "CSR:precip_annual_average",
    source: "calculate",
    opacity: 0.85,
    visibility: true,
    paramsButtonConfig: [{ type: "query", pressed: true }],
    descriptionHtml:
      "{{inputmanager|id=classes}}" +
      "{{checkbox|id=show_dry|text=Dry: below 800 mm|checked=true|hideLabel=true|handler=onClassToggle}}" +
      "{{checkbox|id=show_moderate|text=Moderate: 800 to 1200 mm|checked=true|hideLabel=true|handler=onClassToggle}}" +
      "{{checkbox|id=show_wet|text=Wet: above 1200 mm|checked=true|hideLabel=true|handler=onClassToggle}}",
    functions: {
      // this = the layer; the checkbox's id names the class it switches
      onClassToggle: function (checkbox, checked) {
        var values = {};
        values[checkbox.id.replace("show_", "")] = checked;
        this.getInputs().id["classes"].setValues(values);
      },
    },
    onInputsReady: function (inputs) {
      inputs.id["classes"].setDefaultValues({ dry: true, moderate: true, wet: true });
    },
    // The legend lists only the classes shown. That also makes the layer recalculate: a change of
    // the inputs that leaves the legend as it was does not redraw the map.
    beforeCalc: function (inputs) {
      var show = inputs.id["classes"].global;
      var legend = [];
      if (show.dry) legend.push({ color: [230, 160, 40], value: 1, title: "Dry (below 800 mm)" });
      if (show.moderate) legend.push({ color: [120, 180, 90], value: 2, title: "Moderate (800 - 1200 mm)" });
      if (show.wet) legend.push({ color: [40, 110, 190], value: 3, title: "Wet (above 1200 mm)" });
      this.setCalculateLegend(legend);
    },
    expression: function (layersVals, inputs) {
      var show = inputs[0].global; // the inputmanager: the only input
      var rainfall = layersVals[0];
      if (!this.isNumeric(rainfall)) return this.nullValue;
      var rainClass = rainfall < 800 ? 1 : rainfall <= 1200 ? 2 : 3;
      var shown = rainClass === 1 ? show.dry : rainClass === 2 ? show.moderate : show.wet;
      return shown ? rainClass : this.nullValue;
    },
  },
];

Customize it

Make the state reach the calculation

A checkbox is not an input: its state never reaches expression by itself, and it takes no position in inputs. The example uses the usual three steps:

The handler stores the state in an InputManager with setValues, which also recalculates the layer.
onInputsReady calls setDefaultValues with the same state as checked=true, because the handler does not run for the starting state.
expression reads the stored value by the manager’s position: inputs[0].global.onlyRich.

Use it without a calculation

The handler can do anything on the page, for example show or hide another layer of the map:

descriptionHtml: "{{checkbox|id=show_states|text=Show state borders|handler=onShowStates}}",
functions: {
  onShowStates: function (checkbox, checked) {
    /* on the map a plain layer is named by its title: find it by the map it shows */
    this.map.layers.forEach(function (layer) {
      if (layer.params && layer.params.LAYERS === "CSR:estados") layer.setVisibility(checked);
    });
  },
},

Change its look

labelBefore=true puts the text before the switch instead of after it.
fieldLabel adds a label at the left of the whole field; hideLabel=true removes it.
iconCls replaces the CSS class of the switch icon, to restyle it.
Ext.getCmp(id).setBoxLabel("Show details (3)") changes the text after the map opened.

Pitfalls

The handler also runs once with checked = false when the layer is removed. Undo there whatever turning it on did.
Write the handler as a regular function, not an arrow function, or this is not the layer.
notify and unselect are accepted for symmetry with the map-picking switches, but do nothing on a plain checkbox.

Reference: every parameter

Generated from the platform source. Every entry, searchable, is in the API reference; the raw data is api.json. Open an entry for its description, parameters and example; # links to it.

checkbox · on/off, calls a function

Checkbox13 entries

Written in a layer's descriptionHtml as {{checkbox|parameter=value|...}}

A checkbox that calls a function of the layer when toggled. It is not registered as an input: read its state inside the handler.
Usage: {{checkbox|text=Show details|handler=onToggleDetails}}

This tool is created from Ext.form.Checkbox.
Only customized properties are listed here.

`checked`

Boolean= false# Set true to start checked.

Set true to start checked. handler is not run for the initial state.

|checked=true|

`fieldLabel`

String# Defines a label at the left of the whole field (Ext fieldLabel), in addition to the text shown next to the switch.

Defines a label at the left of the whole field (Ext fieldLabel), in addition to the text shown next to the switch. hideLabel=true removes it and its reserved space.

|fieldLabel=Options|

`forceUpdateLayer`

function()# Fires the forceupdatelayer event of the widget.

Fires the forceupdatelayer event of the widget. For the map-interaction tools registered as inputs (summedarea, areaintegral) this is the event the layer listens to, so calling it marks the input as changed and recalculates the layer with the values currently stored in inputs.id[ID].

Ext.getCmp('sum_tool').items.get(0).forceUpdateLayer();

`handler`

function# Defines the callback run whenever the checkbox is checked or unchecked (by the user or by toggle()).

Defines the callback run whenever the checkbox is checked or unchecked (by the user or by toggle()). Called as handler(checkbox, checked) with this = the layer. The value is resolved in this order: a key of the layer functions object, then a global function with that name, then the text itself evaluated as a function (a full function(){...} or a statement body). The checkbox is not a layer input: read checked here and act (e.g. setValues on an InputManager, changeLayers...). It is also called once with checked=false when the widget is removed together with its layer.

|handler=onToggleDetails|

functions: {
    onToggleDetails: function(checkbox, checked) {
        this.getInputs().id['state'].setValues({details: checked});
    }
}

`iconCls`

String= cmn-toggle-icon# Defines the CSS class of the toggle switch icon; replace the default to restyle the switch.

Defines the CSS class of the toggle switch icon; replace the default to restyle the switch.

|iconCls=my-toggle-icon|

`id`

String# Defines the id of the checkbox component (Ext.getCmp(id)), e.g. to call toggle() or setBoxLabel() from a button.

Defines the id of the checkbox component (Ext.getCmp(id)), e.g. to call toggle() or setBoxLabel() from a button. Generated when omitted.

|id=show_details|

`inputValue`

String# Defines the DOM value attribute of the underlying <input type="checkbox"> (useful inside an HTML form).

Defines the DOM value attribute of the underlying <input type="checkbox"> (useful inside an HTML form).

|inputValue=details|

`labelBefore`

Boolean= false# Set true to render the text before (left of) the toggle switch instead of after it.

Set true to render the text before (left of) the toggle switch instead of after it.

|labelBefore=true|

`notify`

Boolean= true# Accepted for parity with the map-picking switches (pickpoint, hoverpixel...), where it controls the activation notification.

Accepted for parity with the map-picking switches (pickpoint, hoverpixel...), where it controls the activation notification. A plain checkbox shows no notification, so the value has no effect here.

`setBoxLabel`

function(boxLabel)# Changes the text shown next to the checkbox (the markup text parameter) after it was rendered.

Changes the text shown next to the checkbox (the markup text parameter) after it was rendered. Available on every checkbox-style tool (checkbox, pickpoint, hoverpixel, summedarea, areaintegral); get the component with Ext.getCmp(id).

boxLabel String: New label text (HTML allowed).

Ext.getCmp('my_checkbox').setBoxLabel('Show details (3)');

`text`

String# Defines the text shown next to the toggle switch (the checkbox boxLabel).

Defines the text shown next to the toggle switch (the checkbox boxLabel).

|text=Show details|

`toggle`

function(forceState)# Checks or unchecks the checkbox from code, running its handler as if the user had clicked it.

Checks or unchecks the checkbox from code, running its handler as if the user had clicked it. Without an argument the current state is inverted. Get the component with Ext.getCmp(id).

forceState Boolean: true to check, false to uncheck; omit to invert the current state.

Ext.getCmp('show_details').toggle(false); // uncheck

`unselect`

Boolean= true# Accepted for parity with the map-picking switches, where it selects the activation message.

Accepted for parity with the map-picking switches, where it selects the activation message. A plain checkbox never unchecks itself, so the value has no effect here.