JavaScript

Dashboard manual · Python SDK · JavaScript

Call each piece of a dashboard from JavaScript, and see the result on the map at the same time.

The map above stays at the top of the screen while you scroll. Under each heading is one piece of the dashboard and a block of code. To try a block:

1. Scroll to the block.
2. Push Run under it.
3. Look at the map above, and at the output under the block.

Each Run reloads the map first, so each block starts from the same map. Blocks marked js need a Google key or a page option that this map does not have, so they have no button. The page has one object, window.rs. The global rs* functions of the reference do the same jobs, and a few of them (rsSetTheme, rsSetStreetView) have no rs. form. For the Python side of the same page, see Python SDK.

Wait for the page

Call your code in rs.ready(fn). It runs now if the page is ready, and on the event rs:ready if not. The event fires once, so a listener that you add later never runs. In Python, page_script= runs your text before the page is ready: put it in rs.ready(() => ...) too.

rs.ready(() => console.log("ready, contract", rs.contract));

Find and read roads

rs.query and rs.find give the ids of roads. rs.props gives the row of one road. These ids are roadstyle's ids, not your edge_id. See Ids past 2**53.

const ids = rs.query({highway: "primary"});      // columns that equal a value
console.log(ids.length, "primary roads");
console.log(rs.find("gatan").length, "roads with gatan in a field");
console.log(rs.props(ids[0]));

Select, highlight and focus

const ids = rs.query({highway: "primary"});
rs.select(ids[0]);          // like a click: glow, popup, road card
rs.focus(ids);              // fit the camera to the set
rs.highlight(ids.slice(0, 5));

rs.select(null) clears the selection. rs.highlight([]) clears the glow.

Filter and color

rs.setFilter({classes: ["primary", "secondary", "tertiary"], tunnels: false});   // also: bridges, access, ids
rs.setColorBy("Speed limit");                   // a name from color_options
rs.color([{color: "#ef4444", ids: rs.query({highway: "primary"})}]);

rs.color(null) removes your colors. rs.setFilter({}) shows all roads again. rs.can(part) is false for a part that the page cannot apply, for example a color option that the style does not have.

Theme, base map, overlays, views

rsSetTheme("dark");
rs.setBasemap("blank");
rs.setView("Casing only");          // a name from views=
rs.setTunnelStyle({strength: 80});

rs.setOverlay(label, visible) shows or hides one overlay of the page. rsSetBridges, rsSetTunnels and rsSetClasses are the single-control forms of rs.setFilter.

Save and share the state

rs.getState() gives a copy of the state. rs.setState(part) applies a part of it through the controls. rs.link() gives the part that differs from the start, as a #rs= link. A page opened with that link applies it.

rs.setFilter({classes: ["primary"]});
const link = rs.link();
console.log(link);
rs.setState({classes: null});       // back to all classes

Sections of the panel

The panel starts empty. Add a part of roadstyle (part: "query" or "road_card") or your own HTML (html).

rs.sections.add({id: "q", label: "Query", part: "query", text: "p.highway == 'primary'"});
rs.sections.add({id: "road", label: "Selected road", part: "road_card", fields: ["name", "highway"]});
rs.sections.add({id: "notes", label: "Notes", before: "road", fold: true,
                 html: "<p>Text of the page</p><button class='sb-primary' id='go'>Go</button>"});
document.getElementById("go").onclick = () => rs.focus(rs.query({highway: "primary"}));
console.log(rs.sections.list());

Other calls: get(id), hide(id), show(id), remove(id), fold(id, on), foldAll(on) and folded(id). A section with a label is a card. A section with fold: true or background: false needs a label.

Legend rows and color modes

rs.legend.add({id: "sensors", color: "#16a34a", label: "Sensors", shape: "circle"});
rs.colorModes.set(["Traffic", "Counted"], {active: "Traffic", onChange: name => console.log("mode", name)});
console.log(rs.legend.list(), rs.colorModes.active);

rs.legend.remove(id) removes a row. rs.colorModes.select(name) picks a mode, and rs.colorModes.clear() takes the list away.

Toolbox

rs.tools.add({id: "export", title: "Export", icon: "⇩", onClick: () => console.log("pressed")});
console.log(rs.tools.list().map(t => t.id));

rs.tools.bind(id, {onClick}) gives a tool its behavior. open(id) and close(id) open and close the box of a tool. remove(id) removes a tool of your page. ready() shows a bar that toolbar.hold keeps hidden. The built-in tools are theme, navigate, street_view, google_3d, basemap, roads, buildings, legend, settings and attribution.

Help window

rs.help.set({title: "How to read this page", intro: "The map shows roads.",
             terms: [["Primary", "A main road."]], note: "Data: OpenStreetMap."});
console.log(rs.help.get().title);

rs.help.button(el, words) puts a ? button with its own words in el. rs.help.open(words) and rs.help.close() open and close the window. rs.help.clear() removes the window and the button.

Number tiles, charts, tabs and a hover box

rs.sections.add({id: "stats", label: "Statistics", html: "<div class='rs-kpis' id='kp'></div><div id='ch'></div>"});
document.getElementById("kp").innerHTML = rs.kpi("Roads", "2 800", "primary and secondary", "#0e7c8e");
const s = rs.svg(document.getElementById("ch"), "svg", {viewBox: "0 0 100 20", width: "100%"});
const bar = rs.svg(s, "rect", {x: 0, y: 4, width: 60, height: 12, fill: "var(--accent)"});
rs.hover.on(bar, "<b>60 %</b> of the roads");

rs.tabs.use(nav, onChange) makes the tabs of a nav element work and gives {select(id), current()}. Dashboard parts shows the HTML and the other shared pieces.

Live data

live_data=True must be on in Python. rs.setData takes an array of rows, an Arrow table, or the URL of a JSON file. Write edge_id as text.

const ids = rs.query({highway: "primary"});
const rows = ids.map(id => ({edge_id: String(rs.props(id).edge_id), flow: Math.round(Math.random() * 1000)}));
const r = await rs.setData(rows, {colorBy: "flow", legend: {title: "Random flow"}});
console.log(r);                      // {rows, matched, ms}
console.log(rs.naturalBreaks(rows.map(x => x.flow), 4));

rs.clearData() takes the data away. See Live data for all options.

Phone sheet and free area

console.log("sheet height:", rs.sheet());        // 0 closed, 1 for 40 %, 2 full, null if the page has no sheet
console.log(rs.freeArea());                      // {lo, hi, top, bottom}: the part of the map that nothing covers

rs.sheet(n) sets the height of the sheet.

Street View and Google 3D

These windows need a Google key, so the map above cannot run them.

rsSetStreetView(true);        // street_view="window" only
rsStreetViewStep(20);         // 20 m along the edge
console.log(rsGetStreetViewSpot());
rsSetGoogle3D(true);          // google_3d=True only

Google Street View and Google 3D explain the options.

Replace the style, and clean up

rs.setStyle(style) gives the page a new roads style. Every control that a style gives follows it. rs.error is null, or the error of a style that the dashboard cannot read. rs.destroy() removes the listeners of the object.

Events

All events fire on document as CustomEvents. Read the data from e.detail. rs.on(name, fn) listens for the shorter names (select, deselect, filter, color, basemap and others), calls fn with the detail itself, and gives the function that stops the listener.

const stop = rs.on("select", d => console.log("selected", d.properties.name));
document.addEventListener("rs:themechange", e => console.log("theme", e.detail.theme), {once: true});
rs.select(rs.query({highway: "primary"})[0]);
stop();

The page sends these events: rs:ready, rs:select, rs:deselect, rs:filterchange, rs:colorchange, rs:highlightchange, rs:themechange, rs:basemapchange, rs:basemapready, rs:buildingschange, rs:buildings3dchange, rs:labelschange, rs:overlaychange, rs:overlayschange, rs:interactionchange, rs:tunnelchange, rs:roadfillchange, rs:viewchange, rs:viewselect, rs:sectionchange, rs:helpchange, rs:colormode, rs:datachange, rs:toolchange, rs:toolsready, rs:sheetchange, rs:layoutchange, rs:streetviewchange, rs:streetviewmove, rs:streetviewspot, rs:google3dchange, rs:g3dmodechange and rs:tableready.

When each event fires, and its detail, are in the reference.

See also: Overview · Python SDK · Dashboard layout · Add to the panel · Live data · JavaScript API