Tutorial

14 short steps on one live map: read the idea, change the query, press Run - the map shows the result and the tutorial says whether it is what the step asked for. Nothing is saved on the map server.

Your first map

The chapter notes

  1. Turn it on

    A Mappia map is described by a query: a list of layers, written in JavaScript. This one has a single layer, the states of Brazil - a published map named CSR:estados. It starts switched off, so the map is empty.

    Your turn:

    Change visibility to true, then press Run.
    // One layer: the states of Brazil
[
  {
    name: "CSR:estados",
    title: "States",
    visibility: false,
  },
];
    Hints

    visibility decides whether the layer is drawn when the map opens.

    The line should read visibility: true, - lower case, no quotes.

    Solution
    // One layer: the states of Brazil
[
  {
    name: "CSR:estados",
    title: "States",
    visibility: true,
  },
];

  2. Give it a name

    title is the name the reader sees in the layer list and in the menus. name stays as it is: it points at the published map.

    Your turn:

    Change the title to "States of Brazil" and Run.

    It continues from the query of the step before.

    Hints

    Change only the text between the quotes after title:.

    The line should read title: "States of Brazil", - text keeps its quotes.

    Solution
    // One layer: the states of Brazil
[
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];

  3. The reader decides

    Your query decides how the map opens: visibility: true means States of Brazil is drawn when the map starts. After that, whoever reads the map can switch each layer off and on with the map itself - the eye button on the layer's row, at the top left of the map, or Maps, the map's own menu bar along its top edge.

    Your turn:

    No code this time. In the map on the right, hide States of Brazil with the eye button on its row, then show it again.

    It continues from the query of the step before.

    Hints

    Look inside the map: at its top left, the row States of Brazil has an eye button. Click it once to hide the layer, once more to show it.

    Or click Maps in the thin bar along the top edge of the map (not this page's menus), then the switch next to States of Brazil, twice.

    Solution
    // One layer: the states of Brazil
[
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];

  4. A name must exist

    name must be a map that the server publishes, written WORKSPACE:map. A name that is not in the catalogue is not drawn - the first thing to check when a layer is missing. Break it on purpose, to see the message you will get.

    Your turn:

    Change the name to "CSR:does_not_exist", Run, and read the message. The next step puts the map back.

    It continues from the query of the step before.

    Hints

    Only the text inside the quotes after name: changes.

    The line should read name: "CSR:does_not_exist",.

    Solution
    // One layer: the states of Brazil
[
  {
    name: "CSR:does_not_exist",
    title: "States of Brazil",
    visibility: true,
  },
];

  5. One expression, not a program

    The platform does not run a query line by line: it reads the whole text as one expression, whose value is the list of layers. A statement such as var x = 1; before the list breaks it. This page catches that before anything reaches the map.

    Your turn:

    Type var x = 1; on a new line just before the [ and Run: read the message. Then delete that line and Run again, so the map comes back.
    // The map from the first steps
[
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];
    Hints

    Put the cursor at the start of the [ line, type var x = 1; and press Enter, then Run.

    After the message, delete the whole line var x = 1; - the query starts with the [ again - and Run.

    Solution
    // The map from the first steps
[
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];

Layers and their properties

The chapter notes

  1. A second layer

    A map is usually several maps on top of each other. Each entry of the list, between { }, is one layer, and entries are separated by commas. The first entry is drawn on top: the relief you add will cover the state borders - the next step fixes that.

    Your turn:

    Add { name: "CSR:altimetria", title: "Elevation", visibility: true } as the first entry of the list, then Run.
    // Each entry of the list is one layer
[
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];
    Hints

    Copy the whole { ... }, block of the states, paste it right after the [, then change its name and title.

    Between the two { } blocks there must be a comma: }, then {.

    Solution
    // Each entry of the list is one layer
[
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
  },
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];

  2. Half transparent

    opacity goes from 0 (invisible) to 1 (opaque) - a fraction, not a percentage. Below 1, what is under the layer shows through: here the state borders and the basemap's towns, under the relief.

    Your turn:

    Make the Elevation layer half transparent, then Run.

    It continues from the query of the step before.

    Hints

    Add a property to the Elevation entry - the one on top - next to its visibility.

    Add the line opacity: 0.5, inside the Elevation { } - a number, without quotes.

    Solution
    // Each entry of the list is one layer
[
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
    opacity: 0.5,
  },
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
];

  3. A layer the reader turns on

    A layer can start switched off and wait in the top menu until the reader wants it. That keeps the first view simple. Here: the forest biomass of the Amazon.

    Your turn:

    Add { name: "CSR:biomassa_baccini_bioma_am", title: "Forest biomass (Amazon)", visibility: false } at the end of the list and Run. Then switch it on from Maps, the menu bar along the top edge of the map - a layer that is off has no row with an eye button yet.

    It continues from the query of the step before.

    Hints

    The new { ... }, entry goes just before the final ]; - check there is a comma after the } above it.

    Keep visibility: false in the query; the switch in Maps turns it on.

    Solution
    // Each entry of the list is one layer
[
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
    opacity: 0.5,
  },
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
  {
    name: "CSR:biomassa_baccini_bioma_am",
    title: "Forest biomass (Amazon)",
    visibility: false,
  },
];

Where maps come from

The chapter notes

  1. Names come from the catalogue

    The map server publishes a catalogue of its maps, each with a name such as CSR:altimetria. A layer's name must be one of them, copied exactly. Each map also covers its own region. Some names in this tutorial's catalogue: CSR:bioma_cerrado_declividade (slope, Cerrado), CSR:biomassa_baccini_bioma_am (forest biomass, Amazon), CSR:precip_annual_average (annual rainfall, Mozambique).

    Your turn:

    Add the slope of the Cerrado, CSR:bioma_cerrado_declividade, titled "Slope (Cerrado)", as the first entry - on top of the others - and Run.
    // The map so far: three layers
[
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
    opacity: 0.5,
  },
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
  {
    name: "CSR:biomassa_baccini_bioma_am",
    title: "Forest biomass (Amazon)",
    visibility: false,
  },
];
    Hints

    Names are copied from the catalogue, not guessed: workspace, colon, map.

    Right after the [, add { name: "CSR:bioma_cerrado_declividade", title: "Slope (Cerrado)", visibility: true },.

    Solution
    // The map so far: three layers
[
  {
    name: "CSR:bioma_cerrado_declividade",
    title: "Slope (Cerrado)",
    visibility: true,
  },
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
    opacity: 0.5,
  },
  {
    name: "CSR:estados",
    title: "States of Brazil",
    visibility: true,
  },
  {
    name: "CSR:biomassa_baccini_bioma_am",
    title: "Forest biomass (Amazon)",
    visibility: false,
  },
];

Organising layers in groups

The chapter notes

  1. A group in the top menu

    A real map has dozens of layers; groups organise them. A group with a title becomes an entry of the top menu, and its layers go in elements, a list like the query itself.

    Your turn:

    Wrap the States layer in { title: "Boundaries", elements: [ ... ] }, Run, and open Boundaries in the top menu.
    // Relief and borders, not organised yet
[
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
  },
  {
    name: "CSR:bioma_cerrado_declividade",
    title: "Slope (Cerrado)",
  },
  {
    name: "CSR:estados",
    title: "States",
    visibility: true,
    opacity: 0.5,
  },
];
    Hints

    The group is an entry of the list too: { title: "Boundaries", elements: [ before the States block, ] }, after it.

    Inside elements: [ ... ] the States block stays exactly as it was.

    Solution
    // Relief and borders, not organised yet
[
  {
    name: "CSR:altimetria",
    title: "Elevation",
    visibility: true,
  },
  {
    name: "CSR:bioma_cerrado_declividade",
    title: "Slope (Cerrado)",
  },
  {
    title: "Boundaries",
    elements: [
      {
        name: "CSR:estados",
        title: "States",
        visibility: true,
        opacity: 0.5,
      },
    ],
  },
];

  2. A heading in the layer panel

    A group with viewTitle instead of title is a heading in the layer panel, above those of its layers that are on. openGroup: true starts it expanded.

    Your turn:

    Wrap Elevation and Slope in { viewTitle: "Terrain", openGroup: true, elements: [ ... ] } and Run.

    It continues from the query of the step before.

    Hints

    One group holds both layers: { viewTitle: "Terrain", openGroup: true, elements: [ before Elevation, ] }, after Slope.

    Use viewTitle, not title: title makes a top-menu entry.

    Solution
    // Relief and borders, not organised yet
[
  {
    viewTitle: "Terrain",
    openGroup: true,
    elements: [
      {
        name: "CSR:altimetria",
        title: "Elevation",
        visibility: true,
      },
      {
        name: "CSR:bioma_cerrado_declividade",
        title: "Slope (Cerrado)",
      },
    ],
  },
  {
    title: "Boundaries",
    elements: [
      {
        name: "CSR:estados",
        title: "States",
        visibility: true,
        opacity: 0.5,
      },
    ],
  },
];

  3. Groups inside groups

    Groups nest: a group's elements can hold layers or other groups. A top-menu group around the Terrain heading gives both - an entry in the top menu and a heading in the panel. Its color colours the menu entry and the rows of its layers.

    Your turn:

    Put the whole Terrain group inside { title: "Relief", color: "#8d4925", elements: [ ... ] }, Run, and open Relief in the top menu.

    It continues from the query of the step before.

    Hints

    The same move as Boundaries, one level up: Relief's elements holds the Terrain group.

    { title: "Relief", color: "#8d4925", elements: [ before { viewTitle: "Terrain", and ] }, after the Terrain group's closing },.

    Solution
    // Relief and borders, not organised yet
[
  {
    title: "Relief",
    color: "#8d4925",
    elements: [
      {
        viewTitle: "Terrain",
        openGroup: true,
        elements: [
          {
            name: "CSR:altimetria",
            title: "Elevation",
            visibility: true,
          },
          {
            name: "CSR:bioma_cerrado_declividade",
            title: "Slope (Cerrado)",
          },
        ],
      },
    ],
  },
  {
    title: "Boundaries",
    elements: [
      {
        name: "CSR:estados",
        title: "States",
        visibility: true,
        opacity: 0.5,
      },
    ],
  },
];

  4. Properties a group shares

    defaultProperties on a group is given to every layer inside it - unless the layer sets the property itself. Use it for what a whole theme shares: an opacity, a starting state.

    Your turn:

    Give the Terrain group defaultProperties: { visibility: false, opacity: 0.7 } and Run. Elevation keeps its own visibility: true.

    It continues from the query of the step before.

    Hints

    defaultProperties is a property of the group, next to viewTitle and openGroup.

    Add the line defaultProperties: { visibility: false, opacity: 0.7 }, under openGroup: true,.

    Solution
    // Relief and borders, not organised yet
[
  {
    title: "Relief",
    color: "#8d4925",
    elements: [
      {
        viewTitle: "Terrain",
        openGroup: true,
        defaultProperties: { visibility: false, opacity: 0.7 },
        elements: [
          {
            name: "CSR:altimetria",
            title: "Elevation",
            visibility: true,
          },
          {
            name: "CSR:bioma_cerrado_declividade",
            title: "Slope (Cerrado)",
          },
        ],
      },
    ],
  },
  {
    title: "Boundaries",
    elements: [
      {
        name: "CSR:estados",
        title: "States",
        visibility: true,
        opacity: 0.5,
      },
    ],
  },
];

  5. Make it yours

    That is the core of every Mappia map: layers with a name and their properties, organised in groups. This last step has no task to check - change anything you like and Run. The next chapters (servers, calculated maps, controls) build on this map.

    Your turn:

    Change any title, opacity or group, Run, and look at the map. Copy the query when you are happy with it.

    It continues from the query of the step before.

    Hints

    Try a new color for Relief, or another opacity for Boundaries.

    If something breaks, the message says which line - and the last working map stays on screen.

    Solution
    // Relief and borders, not organised yet
[
  {
    title: "Relief",
    color: "#8d4925",
    elements: [
      {
        viewTitle: "Terrain",
        openGroup: true,
        defaultProperties: { visibility: false, opacity: 0.7 },
        elements: [
          {
            name: "CSR:altimetria",
            title: "Elevation",
            visibility: true,
          },
          {
            name: "CSR:bioma_cerrado_declividade",
            title: "Slope (Cerrado)",
          },
        ],
      },
    ],
  },
  {
    title: "Boundaries",
    elements: [
      {
        name: "CSR:estados",
        title: "My states",
        visibility: true,
        opacity: 0.5,
      },
    ],
  },
];

The chapter notes

Every idea of the tutorial, written out with its tables and a full example you can run - for reading, printing, or going further than the steps.

  1. 1 Your first mapA Mappia map is described by a query: one JavaScript expression whose value is the list of layers to show.
  2. 2 Layers and their propertiesSeveral maps in one query, each a layer with its own title, opacity and starting state.
  3. 3 Where maps come fromLayer names come from a map server's catalogue (WMS); addRemoteWMSServer brings in maps from other servers, such as INPE's deforestation maps.
  4. 4 Source typessource decides where a layer's pixels come from: a published map, a calculation, a file of features, a tile service or a basemap.
  5. 5 Calculated maps and controlsA calculated layer computes a new map from the values of published maps, and controls in its panel feed the calculation.
  6. 6 Organising layers in groupsGroups with a title become entries of the top menu; viewTitle groups become headings in the layer panel; defaultProperties is shared by every layer inside.
  7. 7 The && chain, globals and functionsSetup calls joined with && before the layers, setQueryGlobalProperties for shared values and functions, runNow, and functions called from buttons.
  8. 8 The ExtjsUtils toolboxExtjsUtils holds the platform's helpers your code calls: messages, layers and legends, the map, requests, GeoJSON, page styles and more.
  9. 9 Save, share and embed a mapSave a query in the Mappia editor to get its number, open it with a link whose parameters set the tools and options, and embed it in any page.
  10. 10 Your page and the map - MappiaIOMappiaIO connects a page to an embedded map: the page applies queries and sends messages, the query answers and reports what the reader does.

After the tutorial: the tools (every widget and layer type, each with runnable examples), the real maps built with Mappia, and the reference.