31:T5cc,This notebook shows examples of using Flo.w RDF v4 and the accompanying [Observable helper library](https://observablehq.com/@emuanalytics/flow-rdf-v4-helper-library) in Observable notebooks. The helper library is designed to integrate Flo.w RDF v4 with notebooks in a way that is natural, convenient to use and leverages Observable functionality such as reactivity and `viewof`. The helper library is configured and imported at the bottom of this notebook. The entry point to the library (`Flow`) is used throughout the notebook to access Flo.w RDF functionality. In addition to helper functions defined at the root of the entry point (e.g. `Flow.datasetQuery`), the entry point also exposes: - **Flow.ui** The complete Flo.w RDF UI public API (e.g. `Flow.ui.addIcon(...)`) - **Flow.core** The complete Flo.w RDF Core public API (e.g. `Flow.core.MapDataSource`) - Frequently-used functions promoted to top-level functions (e.g. `Flow.expr` from `Flow.core.expr`) - Useful third-party libraries (e.g. `Flow.toc`, `Flow.luxon`, `Flow.turf`, `Flow.vega`) Note that the [helper library](https://observablehq.com/@emuanalytics/flow-rdf-v4-helper-library) is fully documented and provides additional examples of every helper method. When working with notebooks we advise that you use Observable cell reactivity in preference to Flo.w RDF reactivity where possible - using Flo.w RDF reactivity only at the final stage of visualization to make data and options available to a Flo.w map.32:T489,The helper library adds convenience function for working with the Flo.w UI map component and underlying Flo.w RDF Core map features: **Flow.map** displays a Flo.w UI Map. It is designed to be used with `viewof` to retrieve the underlaying Flo.w RDF Core map instance when the map has been initialized and its API is ready for use. Basic configuration of the map is set using the `options` argument passed to `Flow.map`. However, adding data sources and map layers is performed in a dependent cell using the API provided by the Flo.w RDF Core map instance returned by `viewof map = Flow.map(...)`. **Flow.mapClickedFeature** is used to retrieve information about clicks on the map. This function returns a generator that updates as features are clicked and dependent cells will be re-evaluated. **Flow.mapSelection** is used to retrieve selection updates from the map. This function returns a generator that updates as selection state changes and dependent cells will be re-evaluated. It is usually more convenient to use this helper function rather than configuring the `selectionState` property when registering the selection with the Map SelectionPlugin. 33:T50d,{ mainMap.popupPlugin.registerPopup("popup", { content: popupTemplate }); const source = new Flow.MapDataSource({ id: "airquality", type: "vector", src: "airquality", featureId: "label" }); const circleLayer = new Flow.MapLayer({ id: "circle-layer", type: "circle", source: "airquality", style: Flow.layerStyle("circle") .circleColor( Flow.expr(`@no2 ? from-palette('YlOrRd', @no2, 0, 100) : gray`) ) .circleStrokeWidth(Flow.expr("@@hover ? 5 : 0")) .circleRadius(Flow.expr(`@no2 ? @no2 / 5 : 5`)) .build() }); const symbolStyle = Flow.layerStyle("symbol") .visibility(true) .textField(Flow.expr("@name")) .textColor("white") .textSize(Flow.expr("interpolate(linear(), zoom(), 10, 10, 15, 20)")) .textVariableAnchor(["top", "left"]) .textRadialOffset(0.5) .build(); const symbolLayer = new Flow.MapLayer({ id: "symbol-layer", type: "symbol", source: "airquality", interactive: false, style: symbolStyle }); mainMap.transaction(() => { mainMap.addSource(source); mainMap.addLayer(circleLayer); mainMap.addLayer(symbolLayer); }); mainMap.selectionPlugin.enableSelection("airquality", { mode: "multi", popup: "popup" }); }34:T644,---- ## Reactive State Reactive state is initialized in the notebook `config` cell provided when initializing the helper library. (See the bottom of this notebook for an example). **NOTE** Unlike previous versions of Flo.w RDF, reactive state properties must be pre-declared and have initial values set. It is not possible to add new properties after the state has been initialized. Arbitrary properties added to state after initialization will be visible but will **not** be reactive. Use the following function for setting and getting reactive state properties: - **Flow.stateGet** - retrieve a reactive property value by path. This returns a `Generator` that will update the cell value whenever the reactive property changes. - **Flow.stateSet** - set a reactive property value by path. - **Flow.stateTransaction** - wrap a series of `Flow.stateSet` calls in a single update transaction. In a typical notebook, Observable cell reactivity is combined with helper functions like `datasetQuery` to retrieve data for visualization. As a final step, `Flow.stateSet` is used to make this data and other config options available on Flo.w RDF state for the map to consume. In a full web application, Flo.w RDF reactivity is used much more extensively (including Flow. RDF reactive queries) and replaces Observable reactivity used in notebooks. ~~~js // Sync data and options to reactive state for map to consume Flow.stateTransation(() => { Flow.stateSet('mapOptions': ....); Flow.stateSet('airqualityData', airqualityQueryResults); Flow.stateSet('boroughData', boroughQueryResults); }); ~~~ 35:[] 2f:{"title":"Flo.w RDF v4 Helper Library Examples","cells":[{"id":0,"value":"# Flo.w RDF v4 Helper Library Examples","pinned":false,"hidden":false,"mode":"md"},{"id":179,"value":"Flow.toc(\"h2,h3\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":183,"value":"## Introduction","pinned":false,"hidden":false,"mode":"md"},{"id":218,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":186,"value":"## Flo.w RDF UI Components","pinned":false,"hidden":false,"mode":"md"},{"id":225,"value":"All Flo.w RDF UI web components are automatically registered by the helper library and are available for use in HTML cells, Markdown cells, and by using HTML template literals in Javascript code.\n\nSee [Flo.w RDF UI Storybook](https://developer.emu-analytics.net/storybook/) for a fill list of available components, their properties and methods.\n","pinned":false,"hidden":false,"mode":"md"},{"id":26,"value":"Welcome to Flo.w RDF v4","pinned":true,"hidden":false,"mode":"html"},{"id":238,"value":"{\n const button = html`Click Me`;\n button.addEventListener(\"click\", () =>\n console.log(\"Hello from Flo.w RDF UI\")\n );\n\n return button;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":235,"value":"### Icons\n\nAll FontAwesome icons are automatically registered by the helper library and are available for immediate use without individual registration with `Flow.ui.addIcon(...)`. Missing or unrecognized icons will be shown as .\n\n","pinned":false,"hidden":false,"mode":"md"},{"id":247,"value":"

\n\n\n\n\n

","pinned":true,"hidden":false,"mode":"html"},{"id":385,"value":"### Binding UI controls\n\nAll Flo.w RDF UI input controls have a `value` property and emit `flow-ui-change` and `flow-ui-input` events in response to user interaction. Use the [`Flow.bindControl`](https://observablehq.com/@emuanalytics/flow-rdf-v4-helper-library#cell-1055) helper function in conjuction with `viewof` to bind a control's value to a cell value. The cell value updates reactively when the control value is changed by the user.\n\nBy default, `Flow.bindControl` attaches an event listener to the `flow-ui-change` event of the control, which typically indicates a 'confirmed' value. To bind to `flow-ui-input` instead, which typically indicates an intermediate value, pass the event name as a second argument to `Flow.bindControl`.\n\n\n\n\n","pinned":false,"hidden":false,"mode":"md"},{"id":387,"value":"viewof timeVal = Flow.bindControl(html`

`)","pinned":true,"hidden":false,"mode":"ojs"},{"id":393,"value":"timeVal","pinned":true,"hidden":false,"mode":"ojs"},{"id":396,"value":"The example below shows how to bind to the `flow-ui-input` event of the `` control so that the bound cell value updates as the user slides the control.","pinned":false,"hidden":false,"mode":"md"},{"id":398,"value":"viewof rangeVal = Flow.bindControl(\n html``,\n \"flow-ui-input\"\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":419,"value":"rangeVal","pinned":true,"hidden":false,"mode":"ojs"},{"id":425,"value":"`Flow.bindControl` can be used with any element that has a `value` property and emits an event on change. The example below shows a native `` element, which emits an `input` event, being bound to a cell value.","pinned":false,"hidden":false,"mode":"md"},{"id":421,"value":"viewof inputVal = Flow.bindControl(\n html``,\n \"input\"\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":423,"value":"inputVal","pinned":true,"hidden":false,"mode":"ojs"},{"id":177,"value":"----\n\n## Query Builder\n\nThe helper library adds convenience function for working with the Flo.w UI Query Builder component:\n\n`Flow.queryBuilderConfig` can be used to auto-generate a query builder config suitable for querying a specified Flo.w dataset by ID.\n\n`Flow.queryBuilder` can be used with `viewof` to display a Query Builder and reactively retrieve its `RuleSet` value for use in a notebook.\n\n`Flow.flowQueryConverter` converts a Query Builder `RuleSet` to a set of `where` clauses suitable for incorporating into a Flo.w dataset query.\n\n`Flow.mapLayerFilerConverter` converts a Query Builder `RuleSet` to a Maplibre layer filter expression for setting as the `filter` property on a map layer using the `MapLayer.setFilter(expression)` method.\n","pinned":false,"hidden":false,"mode":"md"},{"id":258,"value":"A query builder for the `airquality` dataset is shown below. Changes are applied when the `Apply` button is click and the cell value is updated with the Query Builder's current `RuleSet` value.","pinned":false,"hidden":false,"mode":"md"},{"id":39,"value":"viewof qb = Flow.queryBuilder(qbConfig, {\n condition: \"and\",\n rules: [{ enabled: true }]\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":201,"value":"The query builder config. This is passed to the query builder and also used to convert the query builder's `value` to usable formats.","pinned":false,"hidden":false,"mode":"md"},{"id":64,"value":"qbConfig = Flow.queryBuilderConfig({\n datasetId: \"airquality\",\n size: \"small\",\n // Extra fields or overrides\n fields: {\n field1: { name: \"Field 1\", type: \"string\" }\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":326,"value":"console.log(qbConfig)","pinned":true,"hidden":false,"mode":"ojs"},{"id":196,"value":"The query builder's `value` (a `RuleSet` object)","pinned":false,"hidden":false,"mode":"md"},{"id":47,"value":"qb","pinned":false,"hidden":false,"mode":"ojs"},{"id":194,"value":"The query as a set of `where` clauses for adding to a Flo.w reactive query definition:","pinned":false,"hidden":false,"mode":"md"},{"id":61,"value":"Flow.ui.flowQueryConverter(qb, qbConfig)","pinned":true,"hidden":false,"mode":"ojs"},{"id":203,"value":"The query as a set Flo.w Core map layer filter:","pinned":false,"hidden":false,"mode":"md"},{"id":205,"value":"Flow.ui.mapLayerFilterConverter(qb, qbConfig)","pinned":true,"hidden":false,"mode":"ojs"},{"id":190,"value":"----\n\n## Maps","pinned":false,"hidden":false,"mode":"md"},{"id":261,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":92,"value":"viewof mainMap = Flow.map({\n id: \"main-map\",\n center: [-0.1, 51.5],\n zoom: 10,\n height: \"500px\",\n timer: true // Display a timer control on the map\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":268,"value":"Popup templates are defined using the `Flow.html` template literal. This is actually a very thin wrapper of [lit-html](https://lit.dev/docs/v1/lit-html/introduction/) and supports all the features of `lit-html`. The popup template is a pure function that accepts a clicked Flo.w Map feature and return an HTML template literal for rendering.\n\nTemplates can be composed from sub-templates for re-using template parts, mapping over sets of data or simplifying the template code.\n\nNote that the underlying rendering functionality performs an optimal and minimal set of DOM changes when the popup feature changes and does **not** completely re-render the popup as might be inferred from how popup templates are defined.","pinned":false,"hidden":false,"mode":"md"},{"id":131,"value":"popupTemplate = {\n // Popup header template\n const popupHeaderTemplate = (title) => Flow.html`

${title}

`;\n\n // Table header template\n const tableHeaderTemplate = () =>\n Flow.html`PropertyValue`;\n\n // Property row template\n const rowTemplate = (props, key) =>\n Flow.html`${key}${props[key]}`;\n\n // Main popup template\n return (feature) => Flow.html`\n${popupHeaderTemplate(feature.properties.name)}\n\n ${tableHeaderTemplate()}\n ${Object.keys(feature.properties)\n .filter((key) => key !== \"name\")\n .map((key) => rowTemplate(feature.properties, key))}\n

\n`;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":271,"value":"The main configuration of the map is performed in a dependent cell using the API exposed by the Flo.w Core Map instance. This cell will only be run once the map instance has been initialized and the API is ready for use. It will automatically re-run if the map cell above is changed.\n\nIf this cell is modified, the configuration is reapplied to the existing map. This works as expected, map data sources and map layers are re-created and attached, however, map data sources or layers that are removed from this cell will not be removed from the map. Re-run the map cell to ensure that the map is in sync with the config defined in this cell.","pinned":false,"hidden":false,"mode":"md"},{"id":113,"value":"$33","pinned":true,"hidden":false,"mode":"ojs"},{"id":432,"value":"#### Built-in Popup Templates\n\nSome pre-build popup templates are provided for common use-cases. These are all accessed as properties of `Flow.map`. The available templates are:\n\nTemplate | Description\n---------| -----------\nFlow.map.propertyPopupTemplate | Basic property that displays a table of the selected feature's properties\n\nTo use a pre-built popup, use it as the `content` option when you register a popup. For example,\n```javascript\nmainMap.popupPlugin.registerPopup(\"popup\", {\n content: Flow.map.propertyPopupTemplate\n});\n```","pinned":false,"hidden":false,"mode":"md"},{"id":440,"value":"#### Accessing clicked feature and selection state","pinned":false,"hidden":false,"mode":"md"},{"id":275,"value":"Information about clicked features. This cell value updates reactively.","pinned":false,"hidden":false,"mode":"md"},{"id":149,"value":"Flow.mapClickedFeature(mainMap)","pinned":true,"hidden":false,"mode":"ojs"},{"id":277,"value":"Information about map selection state. This cell value updates reactively.","pinned":false,"hidden":false,"mode":"md"},{"id":154,"value":"Flow.mapSelection(mainMap, \"airquality\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":447,"value":"#### Accessing the time value from the map's timer control\n\nThe timer control is bound to the `time` reactive state property. Retrieve its value as shown below and reference the cell's reactive value in other cells.\n","pinned":false,"hidden":false,"mode":"md"},{"id":444,"value":"time = Flow.stateGet(\"time\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":192,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":293,"value":"viewof selectedNumber = Inputs.range([0, 10], {\n label: \"Select a value:\",\n step: 0.5\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":300,"value":"Flow.stateSet(\"numberVal\", selectedNumber)","pinned":true,"hidden":false,"mode":"ojs"},{"id":291,"value":"num = Flow.stateGet(\"numberVal\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":279,"value":"## Dataset Information and Queries\n\nSupport for displaying Flo.w dataset information and querying datasets is included unchanged in this version of the support library.\n","pinned":false,"hidden":false,"mode":"md"},{"id":282,"value":"Flow.datasetSummary(\"airquality\", { headingLevel: 4 })","pinned":true,"hidden":false,"mode":"ojs"},{"id":287,"value":"viewof selected = Flow.datasetQueryTable({ datasetId: \"airquality\" })","pinned":true,"hidden":false,"mode":"ojs"},{"id":168,"value":"## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"config = {\n return {\n host: \"https://flow.flow-ng.emu-analytics.net\",\n apiKey: \"f7748763-e75f-4a79-a40a-92148855da49\",\n state: {\n numberVal: 0,\n time: new Date().toISOString(),\n timerRunning: true\n },\n enableDebug: true,\n version: \"^4.0.4\"\n };\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":5,"value":"import { Flow } with { config as config } from \"@emuanalytics/flow-rdf-v4-helper-library\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":215,"value":"The `Flow` entry point to the Flo.w RDF v4 helper library:","pinned":false,"hidden":false,"mode":"md"},{"id":172,"value":"Flow","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W35","stdlib":"1","titling":"auto"}