Merge pull request #211 from plotly/cyleaflet-improvements-and-readme

Expose CyLeaflet subcomponent IDs + Add additional documentation of CyLeaflet design

Author: Farkites

CYLEAFLET.md

@@ -0,0 +1,49 @@
+# CyLeaflet: Cytoscape graph component with map layer
+
+CyLeaflet is a Dash component included with Dash Cytoscape which adds geospatial mapping layer to Cytoscape. Node latitude and longitude are specified in the node data, and then rendered by CyLeaflet in the correct position on the map. See the [CyLeaflet documentation](https://dash.plotly.com/cytoscape/cyleaflet) for full usage information.
+
+ This document describes the architecture of the CyLeaflet component.
+
+
+## Component structure
+
+CyLeaflet uses the Dash [All-in-One Component](https://dash.plotly.com/all-in-one-components) pattern to combine Dash Cytoscape and Dash Leaflet with minimal overhead.
+
+This means that CyLeaflet appears at first glance to be a first-class Dash component, but is actually multiple Dash components in a trenchcoat.
+
+Under the hood, an instance of CyLeaflet consists of:
+
+1. A Dash Cytoscape instance
+2. A Dash Leaflet instance
+3. A dcc.Store instance used for holding element data (explained in more detail below)
+4. Some surrounding html.Divs which apply the necessary styling to align the Cytoscape canvas exactly on top of the Leaflet canvas.
+5. Several clientside callbacks to link the individual components together
+
+![fig1](img/cyleaflet-layers.png)
+
+## Files
+
+CyLeaflet functionality is implemented in the following files:
+
+1. `dash_cytoscape/CyLeaflet.py`: CyLeaflet class definition, instantiation of underlying Cytoscape and Leaflet components, layout and styling to align the two canvases, and registration of clientside callbacks
+2. `src/lib/cyleaflet_clientside.js`: Clientside callback function implementations
+
+
+## Callbacks
+
+![fig2](img/cyleaflet-callbacks.png)
+
+
+The following callbacks are used by CyLeaflet:
+
+- **Synchronize Leaflet view with Cytoscape view**
+  - Input: Cytoscape `extent` property
+  - Outputs: Leaflet `viewport` property, Leaflet `invalidateSize` property
+  
+  Purpose: Ensures that the nodes remain in the same places on the map whenever the view is zoomed or dragged. Whenever the Cytoscape view changes, this callback updates the Leaflet view to match. An additional output, the Leaflet  `invalidateSize` property, ensures the map gets refreshed properly.
+
+- **Update Cytoscape graph elements**
+  - Input: dcc.Store `data` property
+  - Output: Cytoscape `elements` property
+  
+  Purpose: Provides a way for the Dash developer to update the graph elements displayed in Cytoscape. This callback transforms the `lat` and `lon` coordinates specified in the node data into a corresponding (x, y) canvas position that will align with the map. Updating the Cytoscape nodes directly does not work, because this skips the transformation step, and the nodes will not appear in the correct map positions. 

dash_cytoscape/CyLeaflet.py

@@ -64,7 +64,11 @@ def __init__(
             s: {"id": id, "component": "cyleaflet", "sub": s}
             for s in ["cy", "leaf", "elements"]
         }
-        self.ids["component"] = "leaflet"
+
+        self.CYTOSCAPE_ID = self.ids["cy"]
+        self.LEAFLET_ID = self.ids["leaf"]
+        self.ELEMENTS_ID = self.ids["elements"]
+
         cytoscape_props = cytoscape_props or {}
         leaflet_props = leaflet_props or {}
         elements = cytoscape_props.get("elements", [])

demos/usage-cy-leaflet-aio.py

@@ -50,19 +50,23 @@
     "Gold Coast": (-28.026901440211205, 153.4208293956674),
 }
 
+# Create an instance of CyLeaflet
+cyleaflet_instance = cyto.CyLeaflet(
+    id="my-cy-leaflet",
+    cytoscape_props={
+        "elements": [],
+        "stylesheet": cy_stylesheet,
+    },
+    width=int(default_div_style["width"][:-2]),
+    height=int(default_div_style["height"][:-2]),
+)
+
+
 # App
 app.layout = html.Div(
     [
         html.Div(
-            cyto.CyLeaflet(
-                id="my-cy-leaflet",
-                cytoscape_props={
-                    "elements": [],
-                    "stylesheet": cy_stylesheet,
-                },
-                width=int(default_div_style["width"][:-2]),
-                height=int(default_div_style["height"][:-2]),
-            ),
+            cyleaflet_instance,
             id="cy-leaflet-div",
             style=default_div_style,
         ),
@@ -97,9 +101,7 @@
 @callback(
     Output("cy-leaflet-div", "children"),
     Output("cy-leaflet-div", "style"),
-    Output(
-        {"id": "my-cy-leaflet", "sub": "leaf", "component": "cyleaflet"}, "children"
-    ),
+    Output(cyleaflet_instance.LEAFLET_ID, "children"),
     Input("location-dropdown", "value"),
     Input("width-input", "value"),
     Input("height-input", "value"),